fluentdのout_fileプラグインの仕様について
ウィークリーFluentdユースケースエントリリレー #1 の記事です。
@oranie さんが in_tail を解説されてたんで、Output plugin から out_file を解説しようかと思います。さまざまな output に対応する Fluentd ですが、一番シンプルで基本的なこのプラグインの動作を今一度確認してみました。
file plugin
out_file はその名の通り、他の出力から受け取ったバッファをファイルに書き出すプラグインです。
公式ドキュメントは こちら
設定例はこんな感じです
<match pattern>
type file
path /var/log/fluent/myapp
time_slice_format %Y%m%d
time_slice_wait 10m
time_format %Y%m%dT%H%M%S%z
compress gzip
utc
</match>
各項目について説明していきます。
path (required)
ファイルの出力先で必須指定項目です。実際は後述する time_slice_format suffix + ".log" (圧縮の場合は + .gz) がつくファイル名になります。
path は絶対パス、相対パスで記載が可能です。相対パスの場合、 fluentd を実行したパスから辿る為、fluentd を /path/to/fluentd で実行して path に "./log/myapp" と指定すると "/path/to/fluentd/log/myapp〜.log" というファイルに出力されます。
time_slice_format
ファイル名の path 以降に追加される時間のフォーマット形式で、デフォルト値は %Y%m%d です。
出力するファイルが分割される時間の指定と考えても良いと思います。デフォルトの指定だと一日ごと（正確には後述する buffer_chunk_limit でさらに分割）でファイルが出力されていきます。
主に指定出来る時間のフォーマットは以下です。
- %Y : 西暦の年
- %m : 月 (01..12)
- %d : 日 (01..31)
- %H : 時 24時間形式 (00..23)
- %M : 分 (00..59)
- %S : 秒 (00..60)
秒単位でもファイルに出力していくことが可能ということですね。（あんまりやらないと思うけど。。）
time_slice_wait
バッファをフラッシュするまでの待ち時間(分指定)で、デフォルト値は10分です。
設定例で言うと、バッファのライフサイクルは以下のようになります。
- time_slice_format (00:00) のタイミングで生成され
- 指定単位 (翌日の 00:00) + time_slice_wait (10分) 待ってから
- 最後にファイルに出力 (/var/log/fluent/myapp.20121019_0.log.gz) して終了
送られてくるデータで遅延が発生した場合でも切り捨てられない為の救済時間と考えると良いでしょう。
time_format
ファイルに記載される時間の形式で、デフォルトはISO-8601なので "2012-10-19T22:39:11+09:00" こんな感じ。
設定例にある %Y%m%dT%H%M%S%z と指定した場合は "20121019T225207+0900" こんな感じになります。
utc
ファイルに付く時刻部分にUTFを使うかどうかで、指定しない場合は localtime が利用されます。
例えば、タイムゾーンが日本で22時10分にファイルが生成された場合ファイル名は file-2012-10-19-22-10_0.log のようになりますが、utc が指定されていた場合は file-2012-10-19-14-10_0.log と日本時間より9時間前の時刻がファイル名に付加されます。
compress
圧縮の有無で、デフォルトは無しです。
現在サポートされているのは gzip 圧縮で、 gz もしくは gzip と指定することで圧縮が可能です。
補足
例えば設定が
<match pattern>
type file
path /path/to/fluent/log/test
time_slice_format %Y-%m-%d-%H-%M
</match>
とあった場合、ファイル名は "/path/to/fluent/log/test.2012-10-19-22-54.log" のようになりそうなものですが、実際は "/path/to/fluent/log/test.2012-10-19-22-54_0.log" と日時のフォーマット後に "_0" がついていると思います。
この部分が何なのかということで "out_file.rb" を読んで見ると、以下のような記載が見つかります。
# override default buffer_chunk_limit
conf['buffer_chunk_limit'] ||= '256m'
文字通りバッファのチャンクの上限値で、これを超えると自動的にファイルに出力される制限値ととれます。指定が無い場合は256MBです。
仮に一日のログのデータが数GBを超えるケースがあり、且つ time_slice_format が %Y-%m-%d の場合、一日に一度のファイルの出力ではバッファのサイズが足らなくなりますが、このリミット単位でファイルが出力されていく為、256MBごとにファイル名に "_0", "_1" ... という形で連番採番されていくということになります。
buffer_chunk_limit はバイト単位で指定が可能です、たとえば先ほどの例に一行付け加えて
<match pattern>
type file
path /path/to/fluent/log/test
time_slice_format %Y-%m-%d-%H-%M
buffer_chunk_limit 128
</match>
とすると、一分ごとのファイルがさらに128バイトごとに連番で出力されていくのが分かるかと思います。