'Directives'에 해당하는 글 1건

td-agent.conf 문법

Tool/Fluentd 2017. 4. 11. 01:10

이 설정 파일을 수정하여 사용자 정의하기 전에 몇가지 문법을 확인해 보자.

설정 파일에서 쓰이는 지시자(Directives) 목록은 다음과 같다.


- source : 입력 형태 결정.

- match : 출력 목적지 결정

- filter : 이벤트 처리 파이프라인 결정

- system : 시스템 광역 설정

- label : 내부 라우팅을 위한 출력 및 필터를 그룹화

- @include : 다른 설정 파일 삽입



1. source


input 플러그인을 매개변수로 하는 지시자로 어떤 방식으로 이벤트를 입력받을 것인지 설정한다.

Fluentd 의 표준 input 플러그인에는 http 와 forward 가 있다.

http 플러그인은 fluentd 를 HTTP 엔드포인트로 바꿔 HTTP 메시지를 전달 받는다.

forward 플러그인은 fluentd 를 TCP 엔드포인트로 바꿔 TCP 패킷을 전달 받는다.

원하는 만큼 source 지시자를 추가하여 동시에 여러개의 이벤트를 받아들일 수 있다.


각 source 지시자에 사용할 input 플러그인을 tyep 파라미터(@type) 에 설정한다.

사이트에서 더 많은 input plugin 리스트를 확인할 수 있다. (http://docs.fluentd.org/v0.12/articles/input-plugin-overview)


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


source 는 Fluentd 의 라우팅 엔진에 이벤트를 전송한다. 이벤트는 tag, time, record 의 세 엔티티로 구성된다.

- tag 는 마침표 '.' (예: myapp.access) 로 구분된 문자열이며 Fluentd 내부 라우팅 엔진의 지침으로 사용된다.

- time 필드는 input 플러그인으로 부터 지정되며 Unix 시간 형식이어야 한다.

- record 는 JSON 객체이다.


tag 는 모든 문자를 허용하지만, output 플러그인에서 다른 컨텍스트로 전달되어 사용(예: table / database / key name 등) 되기 때문에 되도록 소문자, 숫자, 밑줄 정도만 사용하는 것이 좋다. (정규식: ^[a-z0-9_]+$)


위의 예에서 HTTP input 플러그인으로 이벤트를 전송하는 예제이다.


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



2. match


match 지시자은 source 지시자로부터 전달받은 이벤트 중 일치하는 tag 가 있는 이벤트만을 찾아 처리한다.

주로 다른 시스템에 이벤트를 출력하는 등의 동작을 하여 output 플러그인이라고 한다.

Fluentd 의 표준 output 플러그인은 file 과 forward 가 있다.

file 은 다른 파일에 출력을 기록할 때, forward 는 다른 서버로 출력을 보낼 때 사용한다.


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


각 match 지시자은 tag 와 매칭할 패턴 및 사용할 output 플러그인을 지정하는 type 파라미터(@type) 를 포함해야 한다. 

패턴과 일치하는 tag 의 이벤트만 output 목적지로 전송된다. (위의 예에서는 "myapp.access" 태그가 있는 이벤트만 일치).


match 패턴

- * 는 tag 의 마침표(.)로 구분된 한 파트와 매칭 : a.* 는 a.b 와 일치, a 나 a.b.c 와 불일치)

- ** 는 tag 의 마침표(.)로 구분된 모든 파트와 매칭 : a.** 는 a, a.b, a.b.c 와 일치

- {X,Y,Z} 는 X tag, Y tag, Z tag 등이 매칭. 여러 tag 리스트를 콤마로 구분해 지정할 수 있으며 *,** 도 사용 가능하다. : a.{b,c.**} 는 a.b 나 a.c.** 와 일치

- 하나의 match 지시자안에 여러개의 패턴을 공백으로 구분할 수도 있다. 


match 순서

match 지시자도 여러 개를 사용할 수 있으며 상단에 쓰여진 순서대로 일치 여부를 판단한다.

아래처럼 match 지시자가 있을 때 두번째 match 지시자(myapp.access 패턴) 는 불려질 수 없다.


# ** matches all tags. Bad :(
<match **>
  @type blackhole_plugin
</match>
 
<match myapp.access>
  @type file
  path /var/log/fluent/access
</match>
cs


마찬가지로 사이트에서 더 많은 output plugin 리스트를 확인할 수 있다. (http://docs.fluentd.org/v0.12/articles/output-plugin-overview)



3. filter


filter 지시자는 match 와 동일하지만, 또 다른 filter 로 전달이 가능하다. (chained pipeline)

Input -> Output 플로우가 filter 를 거치면 Input -> filter 1 -> ... -> filter N -> Output 가 된다.

아래는 표준 filter 인 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>
cs


먼저 {"event":"data"} 이벤트는 record_transformer 플러그인을 사용하여, 이벤트에 "host_param" 이라는 필드를 추가하고, 추가된 필드 {"event":"data","host_param":"webserver1"} 를 match 지시자의 file output 으로 보낸다.


<filter> 순서 역시 <match> 과 동일하게 쓰여진 순서대로 처리되므로 <match> 전에 <filter> 가 들어가야 한다.



4. system


system 지시자로 지정되는 다음 설정들은 fluentd 콘솔 명령의 옵션들과 동일하다.


log_level - 로그 표시 수준

suppress_repeated_stacktrace - true 로 설정되면 로그에 stacktrace 를 숨김 (기본값)

emit_error_log_interval - 오류 로그를 내보내는 시간 간격(초)

suppress_config_dump - 설정 파일의 내용이 로그에 표시되지 않음.

without_source - input 플러그인 없이 시작 (오래된 버퍼를 비울때 유용)

process_name - 프로세스 이름 변경


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



5. label


label 지시자는 내부 라우팅을 위한 ouput 및 filter 를 그룹화하여, tag 처리의 복잡성을 줄여준다.

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


위 설정에서 forward 이벤트는 elasticsearch output 으로 라우트되고, in_tail 이벤트는 @SYSTEM label 의 grep filter 와 s3 ouput 으로 라우트 된다.

이처럼 label 은 <filter>, <match> 지시자등을 그룹화 할 수 있다.


@ERROR label

@ERROR label 은 플러그인의 emit_error_event API 에 의해 생성된 오류 레코드에 사용되는 내장 label 이다.

<label @ERROR> 를 설정하면 관련된 오류가 발생했을 때 이벤트가 이 label 로 라우팅 된다. (예: 버퍼가 가득 찼거나 유효하지 않은 레코드일 때)



6. @include


@include 지시자를 사용하여 별도의 설정 파일에 있는 지시자를 가져올 수 있다.


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


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


glob 패턴에서 파일은 알파벳순으로 불려지므로, a.conf 와 b.conf 가 있으면 fluentd 는 a.conf 를 먼저 분석한다.

중요한 설정 파일은 안전하게 @include 로 따로 구분하라.


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




WRITTEN BY
손가락귀신
정신 못차리면, 벌 받는다.

,