Fluentd配置文件语法

Posted on 2018-02-08(星期四) 14:45 in Data

  • source中配置数据源和匹配规则,并打上标识tag
  • filter中配置处理规则,对与匹配tag的数据进行过滤、处理
  • match中配置数据存储目标,将符合tag的数据发送至指定目标存储,比如elasticsearch、mongodb等。

fluentd.conf主要用于配置fluentd采集日志数据、处理数据、发送数据的整个生命周期规则:

  • source中配置数据源和匹配规则,并打上标识tag
  • filter中配置处理规则,对与匹配tag的数据进行过滤、处理
  • match中配置数据存储目标,将符合tag的数据发送至指定目标存储,比如elasticsearch、mongodb等。

语法

指令列表

fluentd.conf配置文件包括以下可用指令:

  • source指令确定输入源
  • match指令确定输出目标
  • filter指令确定事件处理管道
  • system指令设置系统配置
  • label指令对输出和过滤器进行分组以用于内部路由
  • @include指令用于包括其他文件

下面一步一步创建一个配置文件:

(1)source

source 告诉Fluentd数据从哪来, 配置数据从哪输入,默认自带两种 httpforward, http主要用于接收http请求,forward主要用于接受tcp数据包。

例如:

Receive events from 24224/tcp
This is used by log forwarding and the fluent-cat command
<source>
  @type forward
  port 24224
</source>

http://this.host:9880/myapp.access?json={"event":"data"}
<source>
  @type http
  port 9880
</source>

source 指令中必须有type参数,type参数指明使用的input插件。source 指令会提交事件(event)给Fluentd的路由引擎,事件由三个实体组成:标签(tag)时间(time)记录(record)。标签(tag)是 由点(.)分隔的字符串,如:myapp.access,在内部路由引擎中起到区分、指示路由的作用。时间(time)字段由输入插件指定,它必须是Unix时间格式。 记录(record)是一个JSON对象。可以同时配置使用多个输入插件,对插件的使用数量并无上限,主要会受到机器本身配置和实际业务场景限制。

由于标签(tag)一般会在整个配置的不同上下文中使用,因此强烈建议标签以小写字母、数字和下划线命名,如:^[a-z0-9_]+$。

对于上面的例子,HTTP输入插件提交以下事件:

# generated by http://this.host:9880/myapp.access?json={"event":"data"}
tag: myapp.access
time: (current time)
record: {"event":"data"}

(2)match

match 指令用于查找匹配相应标签(tag)的事件(event),并对匹配事件进行处理。match 指令最常见的用法是将事件(event)输出到其他系统中(由于这个原因,与 match 指令相对应的插件称为输出插件)。与前文提到的输入插件类似,Fluentd也可以通过安装相应的输出插件来增强输出功能。Fluentd标准的输出插件包含 fileforward ,无需额外安装即可使用。

我们试着在之前的配置文件中添加输出插件:

# Receive events from 24224/tcp
# This is used by log forwarding and the fluent-cat command
<source>
  @type forward
  port 24224
</source>

# http://this.host:9880/myapp.access?json={"event":"data"}
<source>
  @type http
  port 9880
</source>

# Match events tagged with "myapp.access" and
# store them to /var/log/fluent/access.%Y-%m-%d
# Of course, you can control how you partition your data
# with the time_slice_format option.
<match myapp.access>
  @type file
  path /var/log/fluent/access
</match>

每一个 match 指令必须包括匹配模式和 type 参数。只有标签(tag)和匹配模式匹配的事件(event)才会输出到指定目标(在上面的例子中, 只有当事件的标签是 myapp.access 时,才能符合匹配模式)。type 参数表示当前使用的输出插件类型。

与输入插件一样,Fluentd也提供了丰富的output插件,请 点击这里 访问。当然,也可以自己开发输出插件。

匹配模式(Match Pattern)

match 中可以使用以下匹配模式(Match Pattern):

  • * 匹配单个标签(tag)部分

    • 例如:模式 a.* 能匹配 a.b ,但不能匹配 aa.b.c
  • ** 匹配零或多个标签(tag)部分

    • 例如:模式 a.** 能匹配 aa.ba.b.c
  • {X,Y,Z} 匹配X,Y或Z,其中X、Y、Z是匹配模式

    • 例如:模式 {a,b} 匹配 ab ,但不能匹配 c
    • 可以同时跟 *** 结合使用。例如: a.{b,c}.*a.{b,c.**}
  • 当一个标签中有多个匹配模式(匹配模式由一个或多个空格分隔)时,会匹配其中任何一个模式。

    • 例如:模式 <match a b> 匹配 ab
    • 例如:模式 <match a.** b.**> 匹配 aa.ba.b.c 以及 b.d

匹配顺序(Match Order)

Fluentd会尝试按照 match 在配置文件中出现的顺序来匹配标签(tag)。所以,对于以下配置:

# ** matches all tags. Bad :(
<match **>
  @type blackhole_plugin
</match>

<match myapp.access>
  @type file
  path /var/log/fluent/access
</match>

myapp.access 永远不会被匹配到,应该将范围大的匹配模式(Wider Match Patterns)放在范围小的匹配模式(Tight Match Patterns)后面。

<match myapp.access>
  @type file
  path /var/log/fluent/access
</match>

# Capture all unmatched tags. Good :)
<match **>
  @type blackhole_plugin
</match>

当然,如果你有两个相同的匹配模式,那么第二个匹配模式永远不会被匹配到。

如果你希望同时发送事件(events)到多个输出目标,可以考虑使用 out_copy 插件。访问 插件列表

(3)filter

filter 指令的语法和 match 指令相同,但是 filter 可以被链接处理管道。使用过滤器,事件流如下:

Input -> filter 1 -> ... -> filter N -> Output

下面我们添加标准的 record_transformer 过滤器到之前的匹配示例中:

# http://this.host:9880/myapp.access?json={"event":"data"}
<source>
  @type http
  port 9880
</source>

<filter myapp.access>
  @type record_transformer
  <record>
    host_param "#{Socket.gethostname}"
  </record>
</filter>

<match myapp.access>
  @type file
  path /var/log/fluent/access
</match>

接收事件 {"event":"data"} ,先到 record_transformer 过滤器,record_transformer 过滤器将host_param字段添加到事件中, 过滤后的事件是 {"event":"data","host_param":"webserver1"} ,然后过滤后的事件输出到文件中。

Filter的匹配顺序和Output相同,而且应该将放至前面。

(4)system

system 指令可以设置以下配置,也可以通过Fluentd的选项来设置:

  • log_level
  • suppress_repeated_stacktrace
  • emit_error_log_interval
  • suppress_config_dump
  • without_source
  • process_name (只能通过 system 指令设置,不能通过fluentd或Fluentd选项设置)

下面是一个例子:

<system>
  # equal to -qq option
  log_level error
  # equal to --without-source option
  without_source
  # ...
</system>

如果设置了process_name,将会改变Fluentd的supervisor和worker process名称。

<system>
  process_name fluentd1
</system>

如果配置了该项,ps 命令会显示以下结果:

% ps aux | grep fluentd1
foo      45673   0.4  0.2  2523252  38620 s001  S+    7:04AM   0:00.44 worker:fluentd1
foo      45647   0.0  0.1  2481260  23700 s001  S+    7:04AM   0:00.40 supervisor:fluentd1

该功能需要ruby 2.1及以上版本支持。

(5)label

label 指令对filter和output进行分组以便于内部路由。label 降低了标签(tag)处理的复杂性。

下面是一个示例,由于 label 是内置的插件参数,需要加 @ 作为前缀:

<source>
  @type forward
</source>

<source>
  @type tail
  @label @SYSTEM
</source>

<filter access.**>
  @type record_transformer
  <record>
    # ...
  </record>
</filter>
<match **>
  @type elasticsearch
  # ...
</match>

<label @SYSTEM>
  <filter var.log.middleware.**>
    @type grep
    # ...
  </filter>
  <match **>
    @type s3
    # ...
  </match>
</label>

在上面配置中,forward 事件被路由到 record_transformer 过滤器和 elasticsearch 输出,in_tail 事件被路由到 @SYSTEM 标签内部的 grep 过滤器和 s3 输出。

label 对于没有标签(tag)前缀的的事件流分离是很有用的。

label和tag都有标签的意思,为了加以区分,可以将tag翻译成标签,将label翻译成标记或者标注。 @ERROR 标记(Label)是用于由插件 emit_error_event API发出的错误记录的内置标记。如果在配置中配置了

(6)@include

可以使用 @include 指令导入其他配置文件中的指令:

# Include config files in the ./config.d directory
@include config.d/*.conf

@include 指令支持常规的文件路径、glob模式和HTTP URL约定:

# absolute path
@include /path/to/config.conf

# if using a relative path, the directive will use
# the dirname of this config file to expand the path
@include extra.conf

# glob match pattern
@include config.d/*.conf

# http
@include http://example.com/fluent.conf

对于glob模式,文件以字母顺序扩展。如果有 a.conf 和 b.conf ,Fluentd会首先解析 a.conf 。但是不建议按照这个顺序来编写配置文件,因为这很容易出错。为了安全起见,应该分开写:

# If you have a.conf,b.conf,...,z.conf and a.conf / z.conf are important...

# This is bad
@include *.conf

# This is good
@include a.conf
@include config.d/*.conf
@include z.conf

参考文档

td-agent配置文件语法