15. Fluentd输入插件：in_tail用法详解

in_tail输入插件内置于Fluentd中，无需安装。

它允许fluentd从文本文件尾部读取日志事件，其行为类似linux的tail -F命令（按文件名来tail）。

这几乎是最常用的一个输入插件了。

1. 示例配置

<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>

这个示例用于tail Apache的日志。

2. 工作原理
   当Fluentd首次配置使用in_tail插件时，它会从path指定的日志文件尾部读取数据。

一旦日志文件被轮转重写，Fluentd则开始从新文件头部读取数据。Fluentd会持续追踪文件当前的inode编号。

当td-agent重启时，它会从重启前的位置开始读取数据，这个位置保存在pos_file指定的文件中。

3. 插件参数

• @type（必需）插件类型，取值为tail

• tag（必需，0.14.0（最低版本要求，下同））指定生成的事件的tag，取值为一个字符串。可以使用作为占位符，会将日志文件路径中的/替换为.号，
  比如：

path /path/to/file
tag foo.*

上边这个配置会产生foo.path.to.file这样的tag。

• path（必需，0.14.0）
  指定日志文件路径，可使用逗号（,）作为分隔符指定多个路径。
  路径中可包含*和strftime格式时间字符串，用以动态增删文件。
  Fluentd会定期刷新监控文件列表。

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

这个示例监控时间字符串指定的目录，比如若日期为20140401，Fluentd会监控/path/to/2014/04/01路径下的所有文件。

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

这个示例监控多个目录。
需要注意的是，*不能用于存在日志文件轮转的情况，这会导致日志重复。这种情况建议使用单独的in_tail配置。

• path_timezone（1.8.1）若path参数中包含strftime时间字符串，可通过path_timezone设置采用的时区。in_tail默认使用系统时区，可通过如下配置来设置：

path_timezone "+00"

• exclude_path（0.14.0）指定从监控文件列表中排除哪些文件，这是一个字符串数组。

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

这个示例会排除path中的gz和zip压缩文件。

• refresh_interval（0.14.0）指定监控列表刷新间隔，默认为60秒。当path中包含*时生效。

• limit_recently_modified（0.14.13）只监控指定修改时间范围内的文件。该参数取值为time类型的时间，且当path中包含*时生效。

• skip_refresh_on_startup（0.14.13）设置程序启动时是否刷新文件列表，默认为false。不刷新，可在path中包含*时减少启动耗时。

• read_from_head（0.14.0）从文件头部读取数据，默认为false。当取值true时，in_tail会在启动阶段读取文件，若文件太大会很耗时，且会阻塞其他插件的启动。

• encoding, from_encoding（0.14.0）设置in_tail输出数据的编码，默认采用ASCII-8BIT编码。

• read_lines_limit（0.14.0）设置每次从文件中读取的行数，默认为1000.如果在日志中发现“chunk bytes limit exceeds for an emittedevent stream”这样的错误，应该减小此参数值。

• multiline_flush_interval（0.14.0）多行处理模式下的缓存输出间隔，默认不启用此配置。该参数配合format_firstline使用。

• pos_file（强烈推荐配置，0.14.0）Fluentd使用pos_file保存文件读取位置。pos_file可在一个文件中保存多个位置，每个source中配置一个pos_file即可。需要注意的是，多个in_tail不能共用一个pos_file配置，这可能导致未知的行为，比如pos_file
  文件损坏。

• pos_file_compaction_interval（1.9.2）设置pos_file的压缩间隔，被压缩的内容包含： 已移出监控列表的文件、 无法解析的文件、 重复文件行。可在设置pos_file的情况下设置此参数。

pos_file /var/log/td-agent/tmp/access.log.pos
pos_file_compaction_interval 72h

• <parse>指令（必需）用于配置解析文件内容使用的解析器。我们会在后续的文章中了解到解析器的使用。这里有一个例子：

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

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

• path_key（0.14.0）可以将监控文件路径添加到生成的日志事件中，path_key用于指定事件中path的key名称。

path /path/to/access.log
path_key tailed_path

使用上边这个配置，会生成如下的日志事件：

{"tailed_path":"/path/to/access.log","k1":"v1",...,"kN":"vN"}

• rotate_wait（0.14.0）文件轮转等待时间。在监控文件存在轮转的情况下，Fluentd会在监测到文件轮转时，再监控老文件一段时间，以避免数据丢失。默认的等待时间为5秒。

• enable_watch_timer（0.14.0）是否启用监控定时器，默认开启一个间隔1秒的定时器，关闭后会降低CPU和IO消耗。用于解决某些系统监控不准确的问题，未来版本会禁用此功能。

• enable_stat_watcher（1.0.1）是否启用额外的基于inotify的监控器。默认为true，关闭后会禁用inotify事件，仅通过定时监控器来追踪文件。

• emit_unmatched_lines 是否输出无法解析的文件行信息，默认为false。

3.常见问题
3.1 当无法匹配日志时会如何处理
若emit_unmatched_lines设为true，in_tail会打印出告警信息。
比如，<parse>指定的解析器为json，而日志中包含“123,456,str,true”这样的记录，那么在fluentd运行日志中就会看到如下输出：

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

3.2 in_tail为何没有开始读取日志 可能监控文件确实没有产生新的数据，试着追加一条数据看看。

3.3 in_tail输出“/path/to/file unreadable”，这是什么导致的若在运行日志中发现如下信息，可能是fluentd没有监控文件的读权限。

/path/to/file unreadable. It is excluded and would be examined next time.

3.4 如何避免监控大量文件时in_tail停止运行 可设置enable_stat_watcher为false。