【原】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. 插件参数
1. @type（必需）
   插件类型，取值为tail
   
   
2. tag（必需，0.14.0（最低版本要求，下同））
   指定生成的事件的tag，取值为一个字符串。可以使用*作为占位符，*会将日志文件路径中的/替换为.号，比如：
   
   path /path/to/filetag foo.*

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

3. 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配置。

4. path_timezone（1.8.1）
   若path参数中包含strftime时间字符串，可通过path_timezone设置采用的时区。in_tail默认使用系统时区，可通过如下配置来设置：
   path_timezone "+00"
5. exclude_path（0.14.0）
   指定从监控文件列表中排除哪些文件，这是一个字符串数组。
   
   path /path/to/*exclude_path ["/path/to/*.gz", "/path/to/*.zip"]

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

6. refresh_interval（0.14.0）
   指定监控列表刷新间隔，默认为60秒。当path中包含*时生效。
   
   
7. limit_recently_modified（0.14.13）
   只监控指定修改时间范围内的文件。该参数取值为time类型的时间，且当path中包含*时生效。
   
   
8. skip_refresh_on_startup（0.14.13）
   设置程序启动时是否刷新文件列表，默认为false。不刷新，可在path中包含*时减少启动耗时。
   
   
9. read_from_head（0.14.0）
   从文件头部读取数据，默认为false。当取值true时，in_tail会在启动阶段读取文件，若文件太大会很耗时，且会阻塞其他插件的启动。
   
   
10. encoding, from_encoding（0.14.0）
    设置in_tail输出数据的编码，默认采用ASCII-8BIT编码。
11. read_lines_limit（0.14.0）
    设置每次从文件中读取的行数，默认为1000.
    如果在日志中发现“chunk bytes limit exceeds for an emitted
    event stream”这样的错误，应该减小此参数值。
12. multiline_flush_interval（0.14.0）
    多行处理模式下的缓存输出间隔，默认不启用此配置。
    当使用format_firstline选项时，这个参数有用一些。
13. pos_file（强烈推荐配置，0.14.0）
    Fluentd使用pos_file保存文件读取位置。
    pos_file可在一个文件中保存多个位置，所以每个source中
    配置一个pos_file即可。
    需要注意的是，多个in_tail插件不能共用一个pos_file配置，这可能
    导致未知的行为，比如pos_file文件损坏。
14. pos_file_compaction_interval（1.9.2）
    设置pos_file的压缩间隔，被压缩的内容包含：已移出监控列表的
    文件、无法解析的文件、重复文件行。可在设置pos_file的情况下
    设置此参数。
    pos_file /var/log/td-agent/tmp/access.log.pospos_file_compaction_interval 72h
15. <parse>指令（必需）
    用于配置解析文件内容使用的解析器。我们会在后续的文章中了解到解析器的使用。这里有一个例子：
    
    # json<parse> @type json</parse>
# regexp<parse> @type regexp expression ^(?<name>[^ ]*) (?<user>[^ ]*) (?<age>\d*)$</parse>
16. format（已废弃，使用上边的parse）
    
    
17. path_key（0.14.0）
    可以将监控文件路径添加到生成的日志事件中，path_key用于指定事件中path的key名称。
    
    path /path/to/access.logpath_key tailed_path

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

    {"tailed_path":"/path/to/access.log","k1":"v1",...,"kN":"vN"}
18. rotate_wait（0.14.0）
    文件轮转等待时间。在监控文件存在轮转的情况下，Fluentd会在监测到文件轮转时，再监控老文件一段时间，以避免数据丢失。默认的等待时间为5秒。
    
    
19. enable_watch_timer（0.14.0）
    是否启用监控定时器，默认开启一个间隔1秒的定时器，关闭后会降低
    CPU和IO消耗。这个是用来解决某些系统监控不准确的问题，未来
    版本会禁用此功能。
20. enable_stat_watcher（1.0.1）
    是否启用额外的基于inotify的监控器。默认为true，关闭后会禁用
    inotify事件，仅通过定时监控器来追踪文件。
21. emit_unmatched_lines
    是否输出无法解析的文件行信息，默认为false。
4. 常见问题
1. 当<parse>无法匹配日志时会如何处理
   若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"
2. in_tail为何没有开始读取日志
   可能监控文件确实没有产生新的数据，试着追加一条数据看看。
   
   
3. in_tail输出“/path/to/file unreadable”，这是什么导致的
   若在运行日志中发现如下信息，可能是fluentd没有监控文件的读权限。
   /path/to/file unreadable. It is excluded and would be examined next time.
4. 如何避免监控大量文件时in_tail停止运行
   可设置enable_stat_watcher为false。