in_tail.txt

# tail Input Plugin

The `in_tail` Input plugin allows Fluentd to read events from the tail of text files. Its behavior is similar to the `tail -F` command.

## Example Configuration

`in_tail` is included in Fluentd's core. No additional installation process is required.

    :::text
    <source>
      @type tail
      path /var/log/httpd-access.log
      pos_file /var/log/td-agent/httpd-access.log.pos
      tag apache.access
      <parse>
        @type apache2
      </parse>
    </source>

NOTE: Please see the <a href="config-file">Config File</a> article for the basic structure and syntax of the configuration file. For &lt;parse&gt; section, please check <a href="parse-section">Parse section cofiguration</a>.

### How it Works

* When Fluentd is first configured with `in_tail`, it will start reading from the **tail** of that log, not the beginning.
* Once the log is rotated, Fluentd starts reading the new file from the beginning. It keeps track of the current inode number.
* If `td-agent` restarts, it starts reading from the last position td-agent read before the restart. This position is recorded in the position file specified by the pos_file parameter.

## Plugin helpers

* [timer](api-plugin-helper-timer)
* [event_loop](api-plugin-helper-event_loop)
* [parser](api-plugin-helper-parser)
* [compat_parameters](api-plugin-helper-compat_parameters)

## Parameters

[Common Parameters](plugin-common-parameters)

### @type (required)
The value must be `tail`.

### tag

| type    | default | version |
|:-------:|:-------:|:-------:|
| string | required parameter | 0.14.0  |

The tag of the event.

`*` can be used as a placeholder that expands to the actual file path, replacing `/` with `.`. For example, if you have the following configuration

    :::text
    path /path/to/file
    tag foo.*

in_tail emits the parsed events with the 'foo.path.to.file' tag.

### path

| type    | default | version |
|:-------:|:-------:|:-------:|
| string | required parameter | 0.14.0  |

The paths to read. Multiple paths can be specified, separated by `,`.

`*` and strftime format can be included to add/remove watch file dynamically. At interval of `refresh_interval`, Fluentd refreshes the list of watch file.

    :::text
    path /path/to/%Y/%m/%d/*

For multiple paths:

    :::text
    path /path/to/a/*,/path/to/b/c.log

If the date is 20140401, Fluentd starts to watch the files in /path/to/2014/04/01 directory. See also `read_from_head` parameter.

NOTE: You should not use '*' with log rotation because it may cause the log duplication. In such case, you should separate in_tail plugin configuration. 

### exclude_path

| type    | default | version |
|:-------:|:-------:|:-------:|
| array | [] (empty) | 0.14.0  |

The paths to exclude the files from watcher list. For example, if you want to remove compressed files, you can use following pattern.

    :::text
    path /path/to/*
    exclude_path ["/path/to/*.gz", "/path/to/*.zip"]

NOTE: `exclude_path` takes its input as an array, unlike `path` which takes it as a string.

### refresh_interval

| type | default | version |
|:----:|:-------:|:-------:|
| time | 60 (seconds) | 0.14.0  |

The interval of refreshing the list of watch file. This is used when path includes `*`.

### limit_recently_modified

| type | default | version |
|:----:|:-------:|:-------:|
| time | nil (disabled) | 0.14.13  |

Limit the watching files that the modification time is within the specified time range when use `*` in `path` parameter.

### skip_refresh_on_startup

| type | default | version |
|:----:|:-------:|:-------:|
| bool | false | 0.14.13  |

Skip the refresh of watching list on startup. This reduces the start up time when use `*` in `path`.

### read_from_head

| type | default | version |
|:----:|:-------:|:-------:|
| bool | false | 0.14.0 |

Start to read the logs from the head of file, not bottom.

If you want to tail all contents with `*` or strftime dynamic path, set this parameter to `true`.
Instead, you should guarantee that log rotation will not occur in `*` directory.

NOTE: When this is true, in_tail tries to read a file during start up phase. If target file is large, it takes long time and starting other plugins isn't executed until reading file is finished.

### encoding, from_encoding

| type | default | version |
|:----:|:-------:|:-------:|
| string | nil (string encoding is `ASCII-8BIT`) | 0.14.0 |

Specify the encoding of reading lines.

By default, in_tail emits string value as ASCII-8BIT encoding. These options change it.

- If specify only `encoding`, in_tail changes string to `encoding`. This use ruby's [String#force_encoding](https://docs.ruby-lang.org/en/trunk/String.html#method-i-force_encoding)
- If specify `encoding` and `from_encoding`, in_tail tries to encode string from `from_encoding` to `encoding`. This uses ruby's [String#encode](https://docs.ruby-lang.org/en/trunk/String.html#method-i-encode)

You can get supported encoding list by typing following command:

    :::text
    $ ruby -e 'p Encoding.name_list.sort'

### read_lines_limit

| type | default | version |
|:----:|:-------:|:-------:|
| integer | 1000 | 0.14.0 |

The number of reading lines at each IO.

If you see "Size of the emitted data exceeds buffer_chunk_limit." log with in_tail, set smaller value.

### multiline_flush_interval

| type | default | version |
|:----:|:-------:|:-------:|
| time | nil (disabled)| 0.14.0 |

The interval of flushing the buffer for multiline format.

If you set `multiline_flush_interval 5s`, in_tail flushes buffered event after 5 seconds from last emit. This option is useful when you use `format_firstline` option. Since v0.12.20 or later.

### pos_file (highly recommended)

| type | default | version |
|:----:|:-------:|:-------:|
| string | nil | 0.14.0  |

This parameter is highly recommended. Fluentd will record the position it last read into this file.

    :::text
    pos_file /var/log/td-agent/tmp/access.log.pos

`pos_file` handles multiple positions in one file so no need multiple `pos_file` parameters per `source`.

NOTE: Don't share pos_file between in_tail configurations. It causes unexpected behavior, e.g. corrupt pos_file content.

NOTE: in_tail removes untracked file position during startup phase. It means the content of pos_file is growing until restart
when you tails lots of files with dynamic path setting. I will fix this problem in the future. Check <a href="https://github.com/fluent/fluentd/issues/1126">this issue</a>.

### &lt;parse&gt; directive (required)
The format of the log. `in_tail` uses parser plugin to parse the log. See [parser article](parser-plugin-overview) for more detail.

Here are several examples:

    :::text
    # json
    <parse>
      @type json
    </parse>

    # regexp
    <parse>
      @type regexp
      expression ^(?<name>[^ ]*) (?<user>[^ ]*) (?<age>\d*)$
    </parse>

If `@type` contains `multiline`, in_tail works as multiline mode.

### format
Deprecated parameter. Use `<parse>` instead.

### path_key

| type | default | version |
|:----:|:-------:|:-------:|
| string | nil (no assign) | 0.14.0 |

Add watching file path to `path_key` field.

    :::text
    path /path/to/access.log
    path_key tailed_path

With this config, generated events are like `{"tailed_path":"/path/to/access.log","k1":"v1",...,"kN":"vN"}`.

### rotate_wait

| type | default | version |
|:----:|:-------:|:-------:|
| time | 5 (seconds) | 0.14.0  |

in_tail actually does a bit more than `tail -F` itself. When rotating a file, some data may still need to be written to the old file as opposed to the new one.

in_tail takes care of this by keeping a reference to the old file (even after it has been rotated) for some time before transitioning completely to the new file. This helps prevent data designated for the old file from getting lost. By default, this time interval is 5 seconds.

The rotate_wait parameter accepts a single integer representing the number of seconds you want this time interval to be.

### enable_watch_timer

| type | default | version |
|:----:|:-------:|:-------:|
| bool | true    | 0.14.0  |

Enable the additional watch timer.  Setting this parameter to `false` will significantly reduce CPU and I/O consumption when tailing a large number of files on systems with inotify support.  The default is `true` which results in an additional 1 second timer being used.

`in_tail` (via Cool.io) uses inotify on systems which support it.  Earlier versions of libev on some platforms (eg Mac OS X) did not work properly; therefore, an explicit 1 second timer was used.  Even on systems with inotify support, this results in additional I/O each second, for every file being tailed.

Early testing demonstrates that modern Cool.io and `in_tail` work properly without the additional watch timer.  At some point in the future, depending on feedback and testing, the additional watch timer may be disabled by default.

### enable_stat_watcher

| type | default | version |
|:----:|:-------:|:-------:|
| bool | true    | 1.0.1   |

Enable the additional inotify based watcher. Setting this parameter to `false` will disable inotify events and use only timer watcher for file tailing.

This option is mainly for avoiding stuck issue with inotify.

### open_on_every_update

| type | default | version |
|:----:|:-------:|:-------:|
| bool | false   | 0.14.12 |

Open and close the file on every update instead of leaving it open until it gets rotated.

### emit_unmatched_lines

| type | default | version |
|:----:|:-------:|:-------:|
| bool | false   | 0.14.12 |

Emit unmatched lines when `<parse>` format is not matched for incoming logs.

Emitted record is `{"unmatched_line" : incoming line}`, e.g. `{"unmatched_line" : "Non JSON format!"}`.

### ignore_repeated_permission_error

| type | default | version |
|:----:|:-------:|:-------:|
| bool | false | 0.14.0  |

If you hard to exclude non-permision files from watching list, set this parameter to `true`.
It suppress repeated permission error logs.

INCLUDE: _log_level_params

## Learn More

* [Input Plugin Overview](input-plugin-overview)

## FAQ

### What happens when `<parse>` type is not matched for logs.

`in_tail` prints warning message. For example, if you specify `@type json` in `<parse>` and your log line is `123,456,str,true`, then you will see following message in fluentd log.

    2018-04-19 02:23:44 +0900 [warn]: #0 pattern not match: "123,456,str,true"

See also `emit_unmatched_lines` parameter.

### in_tail doesn't start to read log file, why?

`in_tail` follows `tail -F` command behaviour by default, so `in_tail` reads only newer logs. If you want to read existing lines for batch use case, set `read_from_head true`.

### in_tail shows '/path/to/file unreadable' log message. Why?

If you see "/path/to/file unreadable. It is excluded and would be examined next time." message in the log, it means fluentd doesn't have read permission for `/path/to/file`. Check your fluentd and target files permission.

### logrotate setting

`logrotate` has `nocreate` parameter and it doesn't create new file after triggered log rotation. It means `in_tail` can't find new file to tail.

This parameter doesn't fit typical application log cases, so check your `logrotate` setting which doesn't include `nocreate` parameter.

### What happens when in_tail receives BufferOverflowError?

in_tail stops reading new lines and pos file update until BufferOverflowError is resolved. After resolved BufferOverflowError, restart emitting new lines and pos file update.

### in_tail is sometimes stopped when monitor lots of files. How to avoid it?

Try to set `enable_stat_watcher false` in `in_tail` setting. We got several reports in_tail is stopped when use `*` included `path`, and the problem is resolved by disabling inotify events.