File Reader

file reader 是 logkit 从文件读取日志的配置方式，共包含 dir、file、tailx 和 dirx 四种模式。

典型配置如下

    "reader":{
        "log_path":"./logdir",
        "meta_path":"./meta",
        "file_done":"./meta",
        "mode":"dir",
        "encoding":"utf-8",
        "donefile_retention":"7",
        "read_from":"newest",
        "readio_limit":"20",
        "ignore_hidden":"true",  // 可不选，默认开启
        "ignore_file_suffix":".pid, .swp", // 可不选，默认不忽略
        "valid_file_pattern":"qiniulog-*.log" // 可不选，默认为 "*"
    },

1. log_path 必填项，需要收集的日志的文件（夹）路径
2. meta_path 可选项，是reader的读取offset的记录路径，必须是一个文件夹，在这个文件夹下，会记录本次reader的读取位置。默认会根据runner名称结合log_path的hash值自动生成。
3. file_done 可选项，是reader完成后标志读取完成的文件放置位置，如果不填，默认放在meta_path下。singleFile模式下，若文件被rotate，则只匹配当前日志文件夹下，前缀相同的文件，inode相同作为rotate后的文件记录到file_done文件中，该策略只是把移动后的第一个文件放到meta的file_done文件里面。
4. mode 必填项，读取方式，有 dir 、 file 、 tailx 和 fileauto 四种读取模式。
   • 当选项为dir的时候，log_path 必须是精确的文件夹路径，例如 /home/qiniu/path/, logkit会在启动时根据文件夹下文件时间顺序依次读取文件，当读到时间最新的文件时会不断读取追加的数据，直到该文件夹下出现新的文件。使用dir模式的经典日志存储方式为整个文件夹下存储业务日志，文件夹下的日志使用统一前缀，后缀为时间戳，根据日志的大小rotate到新的文件。
   • 当选项为file的时候，log_path 必须是精确的文件路径，例如 /home/qiniu/path/server.log , logkit会不断读取该文件追加的数据。使用file模式的经典日志存储方式类似于nginx的日志rotate方式，日志名称为固定的名称，如access.log,rotate时直接move成新的文件如access.log.1，新的数据仍然写入到access.log。
   • 当选项为tailx的时候，logpath 是一个匹配路径的模式串，例如 /home/*/path/*/logdir/*.log*, 此时会展开并匹配所有符合该表达式的文件，并持续读取所有有数据追加的文件。每隔stat_interval的时间，重新刷新一遍logpath模式串，添加新增的文件。tailx模式比较灵活，几乎可以读取所有日志更新，需要注意的是，使用tailx模式容易导致文件句柄打开过多。tailx模式的文件重复判断标准为文件名称，若使用rename, copy等方式改变日志名称，并且新的名字在logpath模式串的包含范围内，在read_from为oldest的情况下则会导致重复写入数据。
   • 当选项为fileauto的时候，会自动根据路径匹配上述三种模式中的一种。
5. read_from 可选项，在创建新文件或meta信息损坏的时候(即历史读取记录不存在)，将从文件的哪个位置开始读取。可以设置为oldest，从文件开始的部分全量读取，也可以设置为newest从文件最新的部分开始读取。如果字段不填，默认从最老的开始消费。tailx读取模式下，设置为oldest模式可能会导致数据重复读取(如rotate的方式是copy一份数据)，设置为newest则有可能在感知的时间周期内丢失一部分数据。
6. expire 可选项，针对 tailx 和 dirx 读取模式读取的日志, 写法为数字加单位符号组成的字符串duration写法，支持时h、分m、秒s为单位,类似3h(3小时),10m(10分钟),5s(5秒), 默认的expire时间是24h, 当达到expire时间的日志，就放弃追踪。放弃追踪的文件会被记录到file_done中，认为已经读取完毕。若 expire 时间为 0s 时则表示永不过期
7. max_open_files 可选项，针对tailx读取模式读取的日志，最大能追踪的文件数，默认为256。同时追踪的文件过多会导致打开的文件句柄超过系统限制，请谨慎配置该项。超过限制后，不再追踪新添加的日志文件，直到部分追踪文件达到expire时间。
8. stat_interval 可选项，针对tailx读取模式读取的日志，刷新过期的跟踪日志文件, 刷新logpath模式串，感知新增日志的定时检查时间, 写法为数字加单位符号组成的字符串duration写法，支持时h、分m、秒s为单位,类似3h(3小时),10m(10分钟),5s(5秒),默认3m(3分钟)。
9. datasource_tag 可选项，表示把读取日志的路径名称也作为标签，记录到解析出来的数据结果中，默认不添加，若datasource_tag不为空，则以该字段名称作为标签名称。例如 "datasource_tag":"mydatasource"; 则最终解析的日志中会增加一个字段mydatasource记录读取到日志的路径。可用于区分tailx模式下的日志数据是从哪个日志路径下读取的问题。dir模式下，可能存在部分数据标记的不准确，偏差到下一个文件。（因为读取的时候是读到bufferreader的缓冲区，所以当buffer reader还在读前一部分数据的时候，可能底层的多文件拼接的seq reader已经读取到下一个文件，而此时调用的结果会是下一个文件的结果，所以出现异常。这种情况只有在数据出现在文件末尾且缓冲区已经读到下一个文件的情况。）
10. ignore_hidden 可选项，读取的过程中是否忽略隐藏文件，默认忽略
11. readio_limit 可选项，读取文件的磁盘限速，填写正整数，单位为MB/s, 默认限速20MB/s.
12. ignore_file_suffix 可选项，针对dir读取模式需要解析的日志文件，可以设置读取的过程中忽略哪些文件后缀名，默认忽略的后缀包括".pid", ".swap", ".go", ".conf", ".tar.gz", ".tar", ".zip",".a", ".o", ".so"
13. donefile_retention 可选项，日志读取完毕后donefile的保留时间，默认7天。如果donefile里面的文件一直因为别的runner不能删除，donefile也不会删除。
14. valid_file_pattern 可选项，针对dir读取模式需要解析的日志文件，可以设置匹配文件名的模式串，匹配方式为linux通配符展开方式，默认为*，即匹配文件夹下全部文件。
    • 通配符语法说明：
    • * 匹配任意非文件路径分隔符的零或多个字符
    • ? 匹配任意非文件路径分隔符的单个字符
    • [符号集] 匹配符号集中的所有字符
15. encoding 可选项，读取日志文件的编码方式，默认为utf-8，即按照utf-8的编码方式读取文件。支持读取文件的编码格式包括：UTF-16,GB18030,GBK,cp51932,windows-51932,EUC-JP,EUC-KR,ISO-2022-JP,Shift_JIS,TCVN3及其相关国际化通用别名。
16. head_pattern 可选项，默认不填，reader每次读取一行，若要读取多行，则填写head_pattern表示匹配多行的第一行使用的正则表达式。tailx模式在多行匹配时，若一条日志的多行被截断到多个文件，那么此时无法匹配多行。dir、file模式下会自动处理文件截断的拼接。head_pattern最多缓存20MB的日志文件进行匹配。使用多行匹配情况的一个经典场景就是使用grok parser解析应用日志，此时需要在head_pattern中指定行首的正则表达式，每当匹配到符合行首正则表达式的时候，就将之前的多行一起返回，交由后面的 parser解析。
17. tag_file可选项，可以读取一个json格式的文件，并把json的数据作为标签附着在所有数据之上。典型的应用场景为一些机器或者容器相关的元数据存以json格式放在文件中，logkit发送的数据都带上这些元数据，以便查询时可以快速定位机器元数据，并根据元数据做报警等后续事宜。
18. newfile_newline 可选项，默认为false，只针对dir模式，开启后，不同文件结尾自动添加换行符。

日志收集的模式对应的日志生成场景

file模式

使用file模式的经典日志存储方式类似于nginx的日志rotate方式，日志名称为固定的名称，如access.log,rotate时直接move成新的文件如access.log.1，新的数据仍然写入到access.log。此时配置logkit收集永远只针对access.log这一个固定名称的文件进行收集。对于logkit来说，配置的Runner也只会不断收集access.log这一个文件。检测文件是否rotate成功的标志是文件的inode号，在windows下则是fd的属性编号。对于使用nfs系统的用户来说，由于inode号不稳定，请谨慎使用这个模式。

dir 模式

使用dir模式的经典日志存储方式为整个文件夹下存储单个服务的业务日志，文件夹下的日志通常有统一前缀，后缀为时间戳，根据日志的大小rotate到新的文件。如配置的文件夹为logdir，下面的文件为 logdir/a.log.20170621 , logdir/a.log.20170622, logdir/a.log.20170623 这种模式的日志。即某个服务日志按文件大小分隔日志，每次分割后新命名文件并以时间戳为后缀，并且该文件夹下只有这一个服务。dir模式首先会对文件夹下文件整体排序，依次读取各个文件，读完最后有个文件后会查找时间(文件ctime)更新文件并重新排序，依次循环。logkit会负责将多个文件串联起来。即数据读取过程中a.log.20170621中最后一行的下一行就是a.log.20170622的第一行。

tailx 模式

tailx模式比较灵活，几乎可以读取所有被通配符匹配上的日志文件，对于单个日志文件使用file模式不断追踪日志更新，logpath 是一个匹配路径的模式串，例如 /home/*/path/*/logdir/*.log*, 此时会展开并匹配所有符合该表达式的文件，并持续读取所有有数据追加的文件。每隔stat_interval的时间，重新刷新一遍logpath模式串，添加新增的文件。需要注意的是，使用tailx模式容易导致文件句柄打开过多。tailx模式的文件重复判断标准为文件名称，若使用rename, copy等方式改变日志名称，并且新的名字在logpath模式串的包含范围内，在read_from为oldest的情况下则会导致重复写入数据，设置为newest则有可能在感知的时间周期内丢失一部分数据。选择tailx模式请谨慎配置文件名称，防止日志rotate时老数据的命名进入tailx的模式串范围内，导致不断重复读取数据。

dirx 模式

dirx 模式 tailx 的功能如出一辙，唯一的区别就是这个模式通配的对象仅限于目录，例如 /home/*/path/*/logdir。默认的过期时间也延长为 0s（即永不过期），且判断目录是否过期的依据是目录下所有的文件全都过期。

fileauto 模式

fileauto 模式会自动根据用户传入的 logpath 选择 dir、file 和 tailx 三种文件读取的模式之一。

选择的策略如下：

1. 判断路径中是否带有 * ， 若包含，则选择 tailx 模式。
2. 判断路径是否为文件夹，若是文件夹，则选择 dir 模式。注意：dir模式下，不同文件不断append，会导致数据重复收集，请手动选择tailx模式
3. 最后选择 file 模式。