公式サイトに従って、Quickstart Quide をやってみる。

fluentd のバージョンは v1.0 を使う。

Quickstart は以下の3ステップで構成される。

Step 1: Installing Fluentd
Step 2: Use Cases
Step 3: Learn More

Step 1: Installing Fluentd

Installing Fluentd Using Ruby Gem | Fluentd

install & setup

$ mkdir fluentd_quickstart # working directory の作成
$ cd fluentd_quickstart
$ gem install fluentd --no-ri no-rdoc # fluentd のインストール
$ fluentd --setup ./fluent # 設定ファイル（./fluent/fluent.conf ）の生成

daemon 起動

# バックグラウンド で fluentd を起動
# -c 設定ファイルの指定
# -vv verbose
$ fluentd -c ./fluent/fluent.conf -vv & # バックグラウンド

動作確認

$ echo '{"json":"message"}' | fluent-cat debug.test
# 以下のメッセージが表示される
2018-02-26 14:32:19.831807000 +0900 debug.test: {"json":"message"}

daemon 終了

$ pkill -f fluentd # fluentd プロセスの kill

Step 2: Use Cases

実例を見る前に Step 1 で何がどうなってログが表示されたかわからないので設定ファイルの詳細を見てみる。

Configuration File Syntax | Fluentd

SlideShare による概要説明があった。

全ての Fluentd のイベントでは一つの入力に一つの tag が対応する
Fluentd は tag が match するかどうかで出力先を判定
match した出力にイベントが送られる
Fluentd は複数の input、複数の output をサポートする
Fluentd は受け取ったイベントを新しい tag を付けて、自分に再送信する（フィルタ機能）ことも可能

Life of an Fluentd event from Kiyoto Tamura

www.slideshare.net

続けて、設定ファイルは以下のディレクティブから構成されるとの説明。これらのディレクティブについて見ていく。

1. source directives determine the input sources.
2. match directives determine the output destinations.
3. filter directives determine the event processing pipelines.
4. system directives set system wide configuration.
5. label directives group the output and filter for internal routing
6. @include directives include other files.

source

入力ソースを指定するディレクティブ。 @type に入力プラグインを指定する。入力プラグインは in_xxxx と呼ばれる。（出力プラグインは out_xxxx と呼ばれる）

なお、@ プレフィクス付きの項目はシステムの設定値、@ なしの項目は指定したプラグインの設定値を表す。

設定例 1. in_forward

設定例

## built-in TCP input
## $ echo <json> | fluent-cat <tag> 
<source>
  @type forward
  @id forward_input
</source>

type: forward の指定で、in_forward プラグインを利用する（"in_" は不要）。 in_forward では TCP のエンドポイントで out_forward プラグイン（後述）が送信する形式の TCP パケットを待ち受ける。 Step.1 で利用した fluent-cat は out_forward 形式の TCP パケットを内部で構築して fluentd に送信しているということだ。

port 番号など、その他の設定値はこちらから。

forward Input Plugin | Fluentd

設定例 2. in_http

in_http プラグインでは HTTP でデータを待ち受ける。

設定例

# HTTP input
# http://localhost:8888/<tag>?json=<json>
<source>
  @type http
  @id http_input

  port 8888
</source>

動作確認

# 前提：Step.1 で fluentd が起動されていること
$ curl -X GET -d 'json={"message":"using in_http with GET"}' http://localhost:8888/debug.in_http
$ curl -X POST -d 'json={"message":"using in_http with POST"}' http://localhost:8888/debug.in_http
# stdout に GET, POST で送信したログが表示される
2018-02-26 16:09:38.238439000 +0900 debug.in_http: {"message":"using in_http with POST"}
2018-02-26 16:09:41.237832000 +0900 debug.in_http: {"message":"using in_http with GET"}

その他の設定値はこちらから。

HTTP Input Plugin | Fluentd

設定例 3. in_tail

in_tail はファイルの末尾からイベントを読み取る。ファイルが追記されたらイベント発火とみなす。

tail Input Plugin | Fluentd

設定例

## File input
## read apache logs with tag=apache.access
#<source>
#  @type tail
#  format apache
#  path /var/log/httpd-access.log
#  tag apache.access
#</source>

format にログの形式を指定する。標準で apache, syslog, nginx, json, csv などの形式に対応している

format による指定は古い設定方法になっており、v1.0 では parse プラグインとして内で指定することが推奨されている。

Parser Plugin Overview | Fluentd

parse プラグインを指定した書き方は下記の通り。

## File input
## read apache logs with tag=apache.access
#<source>
#  @type tail
#  <parse>
#    @type apache
#  </parse>
#  path /var/log/httpd-access.log
#  tag apache.access
#</source>

in_tail プラグインの使用に際しては pos_file という設定値の指定が推奨されている。 fluetnd がファイルの何行目までを読んだかを pos_file に記録しており、fluentd が終了・再起動した際に pos_file がないとファイルの先頭から全てのイベントが再発火されてしまう。

source のまとめ

source では入力ソースを指定する。 source の中の3種類のタイプ（forward, http, tail）を紹介した。その他の input plugin については下記のリンクから。

Input Plugin Overview | Fluentd

なお、入力プラグインは独自で作成することも可能。

match

match ではタグによって出力先を決定する。 @type に出力プラグインを指定する。出力プラグインは out_xxxx と呼ばれる。

match で使う正規表現は以下のパターンがある。

* matches a single tag part.
** matches zero or more tag parts.
{X,Y,Z} matches X, Y, or Z, where X, Y, and Z are match patterns.

match には複数のパターンを組み合わせることも可能だし、複数のパターンを条件の OR として使うことも可能。

設定例 1. out_stdout

out_stdout はその名の通り stdout にイベントを出力する。 tag が debug.**(ゼロ個以上の任意のタグ列) にマッチすると、stdout にイベントを出力するようにする設定は次のようになる。

設定例

## match tag=debug.** and dump to console
<match debug.**>
  @type stdout
  @id stdout_output
</match>

設定例 2. out_forward

out_forward は TCP でログを送信する。送信先は fluentd の in_forward が一般的（かな？）

設定例

# match tag=system.** and forward to another fluent server
<match system.**>
  @type forward
  @id forward_output

  <server>
    host 192.168.0.11
  </server>
  <secondary>
    <server>
      host 192.168.0.12
    </server>
  </secondary>
</match>

<server></server> で指定されたホストにデータを送る。もし、データの送信に失敗した場合は Secondary Output の設定が使われる。

Output Plugin Overview | Fluentd

match 順について

一つのイベントは最大一つにマッチする。マッチ順は config ファイルの先頭から先に行われ、一度マッチした場合はその後の match ディレクティブをチェックすることはない。イベントを複数の出力先に送りたい場合は out_copy プラグインを使うことを検討する。

out_copy では複数の出力先を指定することが可能。

copy Output Plugin | Fluentd

match まとめ

match は出力ソースを指定する。 match の中の2種類のタイプ（stdout, forward）を紹介した。その他の output plugin については下記のリンクから。

Output Plugin Overview | Fluentd

入力プラグインと同様に出力プラグインも独自で作成することが可能。

filter

フィルタ処理を記載するディレクティブ。 filter は match と同じ syntax を持つが、filter はチェーンされる。

Input -> filter1 -> ... -> filterN -> output

設定例 1. record_transformer

record_transformer では、イベントに対して新たな key-value を追加したり、修正、削除ができる。

設定例

## Mutating event filter
## Add hostname and tag fields to apache.access tag events
#<filter apache.access>
#  @type record_transformer
#  <record>
#    hostname ${hostname}
#    tag ${tag}
#  </record>
#</filter>

record ディレクティブには追加/修正する key-value を記載する。（上記例での tag フィールドの追加は不要な気がするが何か意味があるのだろうか・・・？）

上記例では利用していないが、remove_keys で削除する key の一覧を指定することもできる。

設定例 2. grep

その名の通り、特定のフィールドにある文字列が含まれたり含まれなかったりすることを条件にイベントの取捨選択ができる。

grep Filter Plugin | Fluentd の例

<filter foo.bar>
  @type grep
  <regexp>
    key message
    pattern cool
  </regexp>
  <regexp>
    key hostname
    pattern ^web\d+\.example\.com$
  </regexp>
  <exclude>
    key message
    pattern uncool
  </exclude>
</filter>

regexp ディレクティブでは、key に指定したフィールドが pattern で指定した正規表現にマッチしたイベントを後続に渡す。 exclude ディレクティブでは、key に指定したフィールドが pattern で指定した正規表現にマッチしたイベントは後続に渡さない。

regexp, exclude は上記例のように複合条件として一つの filter ディレクティブに記述できる。

filter まとめ

filter ができることは大きく次の３通り。

一つまたは複数のフィールドの値でイベントをフィルタ（grep）する
新しいフィールドを追加することによって、イベントを拡張する
プライバシー保護やコンプライスのために、フィールドを削除したりマスクする。

Filter Plugin Overview | Fluentd

system

次のシステムの設定を設定できる。

- log_level
- suppress_repeated_stacktrace
- emit_error_log_interval
- suppress_config_dump
- without_source
- process_name

設定例

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

label

label は内部のルーティングのために filter と output をグルーピングする。

設定例

<source>
  @type tail
  path /var/log/production.log
  tag system.log
</source>

<source>
  @type tail
  @label @STAGING
  path /var/log/staging.log
  tag system.log
</source>

<filter **>
  @type grep
  #...
</filter>
<match **>
  @type forward
  #...
</match>

<label @STAGING>
  <filter **>
    @type grep
    #...
  </filter>
  <match **>
    @type forward
    @id staging_forward_output
    <server>
      host 192.168.0.101
    </server>
  </match>
</label>

staging と本番環境で出力するログファイルを分ける時に、@STAGING でラベルされた in_tail による入力イベントは @STAGING 用の filter, match で処理が行われる。

使用用途としては、tag の prefix を使わずにイベントのフローを分離する時に役に立つ。

include

@include ディレクティブでは、外部の設定ファイルを読み込むことができる。指定できるのは以下のパターン

ファイルパス
ファイルパス（glob パターン）
http URL

設定例

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

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

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

設定ファイルの syntax チェック

設定ファイルの形式が誤っていると fluentd が起動できないので、起動前に dry-run で設定ファイルの形式に誤りがないかチェックすることができる。

$ fluentd --dry-run -c fluent.conf

Step 3: Learn More

Step 3 は Fluentd の詳細について学ぶステップになっている。ここまでのステップで input/output/filter plugin についてはなんとなく理解できたので、残りの項目としては次のようなものがある。この辺りは各自読んでもらいたい。

Fluentd のアーキテクチャについて What is Fluentd? | Fluentd
buffer plugin について Buffer Plugin Overview | Fluentd
parse plugin について Parser Plugin Overview | Fluentd
formatter plugin について Formatter Overview | Fluentd
Fluentd の High Availability 設定について Fluentd High Availability Configuration | Fluentd

まとめ

Fluentd v1.0 の Quickstart guide をやりました。 Quickstart を通して、Fluentd で何ができるかがだいたいわかった気がします。 Fluentd を使うことによって簡単に・柔軟に・多目的なイベントが扱えるようになるという印象です。

kmikmy's blog

Fluentd (v1.0) Quickstart Guide をやってみた

Step 1: Installing Fluentd

install & setup

daemon 起動

動作確認

daemon 終了

Step 2: Use Cases

source

設定例 1. in_forward

設定例 2. in_http

設定例 3. in_tail

source のまとめ

match

設定例 1. out_stdout

設定例 2. out_forward

match 順について

match まとめ

filter

設定例 1. record_transformer

設定例 2. grep

filter まとめ

system

label

include

設定ファイルの syntax チェック

Step 3: Learn More

まとめ