fluentd tailプラグインの仕様について
ウィークリーFluentdユースケースエントリリレー #1の記事です。
fluentdを使う上で最も多くの人が使うであろう基本中の基本、tailプラグインの仕様を日本語にした内容＋以前教えてもらった内容をまとめてみます。
公式ドキュメント：http://fluentd.org/doc/plugin.html#tail
Github：https://github.com/fluent/fluentd/blob/master/lib/fluent/plugin/in_tail.rb
tailプラグインはLinuxコマンドで言う「tail -F」と同じような挙動を取る事により、ファイルに追記された情報をfluentd内に取り込む事が出来ます。追記されたかどうかはIOイベントを読み取って動作します。
簡単に説明すると
1)新規に設定されたファイルは終端から読む 2)ログローテーションされたら次のファイルを先頭から読む 3)再起動時には前回読み終わった位置から読み始める（位置はファイルに保存しておく）
という動きになります。その為、一時的にfluentdを停止してもファイルが失われていない or ローテートされていなければ処理は最後に読み込んだ所から問題無く再開されます。
読み込んだデータは指定したフォーマットに変換してfluentd内で扱う事が可能になります。例として
- 127.0.0.1 - - [06/Oct/2012:17:00:12 +0900] "GET /server-status?auto HTTP/1.0" 200 48 "-" "ApacheStats/0.4 wget/1.8" 221
という内容のログファイルを読み取り、tailプラグインが指定された正規表現に基づいたparseをする事で
2012-10-06T17:00:12+09:00 apache.access {"XFF-host":"-","host":"127.0.0.1","user":"-","method":"GET","path":"/server-status?auto","status":"200","size":"48","referer":"-","agent":"ApacheStats/0.4 wget/1.8","response_time":"221"}という構造のデータに変換します。これによりjson内での任意の項目を他のプラグインで処理する事が可能になります。（例えば、response_time項目だけを集計して中の値を計算したりなど。）
構文は以下の形になります。
<source> type tail path /var/log/httpd-access.log tag apache.access format apache </source>
それぞれの内容を以下に解説します。
path
path（必須）: tailする対象のファイルパスを指定します。これは必須です。「,」で区切って複数記述することが出来ます（今ドキュメント読んで気づいた・・・。）
tag
tag(必須) : tailしたデータのtagを指定します。これは必須です。
format
format : tailする対象のデータ形式をすでにあるテンプレート名か正規表現 ‘/’で記述します。
正規表現は、少なくとも一つの名前付き後方参照 (?
用意されているテンプレートは「apache」と「syslog」の二種類です。
apacheテンプレートは以下の正規表現をformatに記述した場合と同じ動作になります。host, user, time, method, path, code, size, referer, agentをfieldとしてfluentdに取り込みます。
format /^(?<host>[^ ]*) [^ ]* (?<user>[^ ]*) \[(?<time>[^\]]*)\] "(?<method>\S+)(?: +(?<path>[^ ]*) +\S*)?" (?<code>[^ ]*) (?<size>[^ ]*)(?: "(?<referer>[^\"]*)" "(?<agent>[^\"]*)")?$/ time_format %d/%b/%Y:%H:%M:%S %z
これはapacheのデフォルトログフォーマットを想定しているテンプレートなので、もしApacheログフォーマットに項目の追加や、区切り文字の変更等のフォーマット変更を行なっている場合は使えないでしょう。
syslog（/var/log/syslog等のsyslogが出しているログなどを想定）テンプレートは以下の正規表現と同じ動作になります。
time, host, ident, messageをfiledとしてfluentdに取り込みます。
format /^(?<time>[^ ]* [^ ]* [^ ]*) (?<host>[^ ]*) (?<ident>[a-zA-Z0-9_\/\.\-]*)(?:\[(?<pid>[0-9]+)\])?[^\:]*\: *(?<message>.*)$/ time_format %b %d %H:%M:%S
time_format
time_format（任意）: timeフィールドの形式。このパラメータは、'time'という項目がデータに含まれていて、それが自動的に解析できない場合にのみ必要です。詳細はTimeクラスを見ましょう。
逆に言うと「time項目の指定がデータ内に無い、もしくは指定されても解析が出来なかった場合、fluentdのログ時間には処理した時間が付与される」という事になります。
例えばそのログが11:59に出力されたにも関わらず、fluentdで読み込んだ時間が16:00だったら
2012-10-06T16:00:15+09:00 apache.access {"XFF-host":"-","host":"127.0.0.1","user":"-","method":"GET","path":"/server-status?auto","status":"200","size":"48","referer":"-","agent":"ApacheStats/0.4 wget/1.8","response_time":"246","time":1349506815}という日付が付与される事になります。
rotate_wait
rotate_wait（任意：デフォルト5秒） :
in_tail はログを取りこぼさないようにもしローテートでファイルが切り替わっても（fdを開きっぱなしにして）前に読んでいたファイルの監視をしばらく続ける。デフォルトで5秒後にファイルを閉じて次のファイルを読む。これはアプリケーションが実際にログファイルを開き直すまでに追記されるログを取りこぼさないようにする為。この間隔を調整できる項目になります。
pos_file
pos_file（任意：デフォルト：パス設定無し）: tailしているファイルのどこまでtailしたかという位置情報をファイルに保存する場合、そのファイルパスを記述します。
pos_file /var/log/td-agent/tmp/access.log.pos
と記述することで、/var/log/td-agent/tmp/access.log.pos内に以下のようなデータを保存します。
/var/log/httpd/access_log 00000000001c22fd 0032026b /tmp/access_log 00000000000025a8 00340008
これでもしもfluentdがダウンしても元の場所からtailが再開できます。もしこのデータに基づいて探索した際にファイル自体が無かったりした場合は、このデータは破棄して新しい位置情報を保存します。
ちなみに、このパラメータを設定しないと「this parameter is highly recommended to save the position to resume tailing.」というログが出ます。そこまで重要なファイルなので/tmp/とかにデフォルトで出してあげても良い気もします。
