Fluentd入門:ログ収集、ルーティング、プラグイン
Fluentdのタグによる振り分け、プラグイン、ファイルバッファーを解説。HTTP出力やForwardの再送と受信確認も整理します。
Fluentdの設定が検証を通っても、ログが意図した出力先に届くとは限りません。<match **>をNginxアクセスログ用のルールより先に置くと、先に広いルールへ流れます。送り先を切り替えるときは、URLとあわせてルールの順序を確認します。
FluentdはCNCFのGraduatedプロジェクトで、主にRubyで実装された拡張可能なログコレクターです。この記事ではNginxのアクセスログを入力から出力まで追い、ファイル出力をHTTPへ切り替えるときに何が変わるかを見ます。例はFluentd 1.xと受信側の公式資料に基づきます。CNCFプロジェクト(英語) · Fluentdソースコード(英語)
最初に押さえるポイント
- タグで経路を選びます。
<source>がイベントを出し、該当する<filter>が加工し、最初に一致した<match>が出力先を選びます。 - プラグインの要件を確認します。 外部プラグインを使う場合は、FluentdとRubyの対応バージョン、依存関係、出力先との互換性を確認します。
- 停止時にためられる量を見積もります。 ディスク上のデータが残っていれば、ファイルバッファーの未送信チャンクは再起動後に復元できます。停止が続けばキューとディスクの空きが減ります。
- 既知のイベントで送り先を確かめます。 本番の経路を変える前に、本文の形式、フィールド型、イベント時刻、再試行の挙動を照合します。
Nginxアクセスログをタグで振り分ける
<source>
@type tail
path /var/log/nginx/access.log
pos_file /var/log/fluentd/nginx.pos
tag access.nginx
<parse>
@type nginx
</parse>
</source>
<filter access.nginx>
@type record_transformer
<record>
hostname "#{Socket.gethostname}"
env "production"
</record>
</filter>
<match access.**>
@type file
path /var/log/aggregated/nginx
</match>
入力はNginxのファイルを読み、access.nginxタグでイベントを送ります。フィルターは収集側のホスト名と環境名を加え、access.**の出力ルールがファイルへ送ります。同じルーティング範囲では、最初に一致する出力にたどり着くまで、該当するフィルターが順に適用されます。具体的な出力を広いパターンより前に置き、その出力で使うフィルターも先に置きます。複数の出力先へ送るにはout_copyなどで分岐を明示します。設定とマッチ順(英語)
pos_fileは入力側の読み取り位置です。この状態が残っていれば再起動後も続きから読めます。起動時にすでにあるファイルに保存位置がない場合、既定では末尾から読みます。既存行も取り込むならread_from_head trueを指定します。入力ごとに位置ファイルを分け、実行ユーザーにログの読み取り権限と、位置ファイルや出力先への書き込み権限を与えます。読み取り位置とは別に、出力先に届いたかを確認します。tail入力(英語)
組み込みのnginxパーサーは、抽出した時刻をイベント時刻に使います。実際のlog_formatがパターンと異なる場合は、パーサーを合わせます。ファイル出力は既定で時刻の区間ごとにまとめて書くため、新しいファイルが現れるまで時間がかかることがあります。Nginxパーサー(英語) · file出力(英語)
入力・加工・出力のプラグインを選ぶ
| 段階 | 主なプラグイン |
|---|---|
| 入力 | in_tailはファイル、in_httpはHTTPリクエスト、in_syslogはUDP/TCPのsyslog、in_execは外部コマンドの出力を読み取ります。 |
| フィルター | record_transformerはフィールドを編集し、grepはパターンで絞り込み、parserはレコード内の文字列を解析します。外部のfluent-plugin-geoipはIPアドレスの地理情報を補います。 |
| 出力 | out_fileはファイル、out_httpはHTTP、out_forwardはForwardで送信します。外部のfluent-plugin-opensearchは@type opensearchとして設定します。 |
parserフィルターに届く時点で、イベントはすでに切り分けられています。スタックトレースを一つのイベントにまとめるなら、複数行の組み立てに対応した入力で処理します。外部プラグインはFluentdが実際に使うRuby環境へインストールし、依存関係も確認します。parserフィルター(英語) · プラグイン管理(英語) · GeoIPプラグイン(英語) · OpenSearchプラグイン(英語)
受信側が止まったときのバッファーを考える
同じタグをHTTPで送るには、最初のファイル出力を次のブロックに置き換えます。この例はJSONを1行に1レコードずつ送り、json_arrayを使えるFluentd 1.10.4以降が必要です。実際の受信側に合わせて本文と応答の扱いを決めます。
<match access.**>
@type http
endpoint https://logs.example.com/ingest
json_array false
retryable_response_codes [503]
<format>
@type json
</format>
<buffer>
@type file
path /var/log/fluentd/buffer/http
flush_mode interval
flush_interval 5s
total_limit_size 512m
overflow_action throw_exception
retry_max_interval 30s
retry_forever true
</buffer>
</match>
ファイルバッファーは未送信のチャンクをディスクに保持します。retry_foreverを使うと、再試行できる失敗に対する時間と回数の上限が外れます。この例ではHTTP 503を明示しており、本文が不正で400が返る場合は通常、形式の修正が先です。ディスクが残っていれば再起動後の復元に使えますが、停止が続くとキューは埋まります。512mはこのバッファーインスタンスの上限です。実際にためられる時間は入力の速さやキュー上限にも左右され、ファイルシステムにも余裕が必要です。HTTP出力(英語) · バッファー設定(英語)
out_forwardは重み付きで複数の受信ノードに分散し、障害時に送信先を切り替えられます。複製には別途分岐の設定が必要です。既定ではACKを待ちません。require_ack_response trueを指定すると相手のin_forwardからACKを待ち、その区間では少なくとも1回の配信方式になります。受信済みのチャンクのACKが失われると、再送で重複する場合があります。後段で永続化またはインデックス作成が終わったかは別に確認します。Forward出力(英語)
Fluent Bitとどう使い分けるか
特定のプラグインや変換が必要なパイプラインではFluentdが選択肢になります。Fluent Bitはリソースに制約のある場所での収集を想定したコレクターで、KubernetesではDaemonSetとして配置できます。各ノードのFluent BitからForwardでFluentdの集約層へ送る構成も、必要な加工と出力をノード側で済ませる構成も取れます。CPUやメモリーはプラグイン、バッファー、流量をそろえて見比べます。公式比較(英語) · Forwardの相互運用(英語)
Fluentdのログを別の受信側へ送る
入力とフィルターは残したまま、まず受信側が受け付ける形式を確認します。Guance DataKitのLog Streamingコレクターは/v1/write/logstreamingで受け付けます。導入形態に応じてコレクターを有効にし、到達可能なURLをFluentdの出力先に設定します。たとえば?source=nginx&service=webを付けます。既定のテキストモードには、json_array falseで1行に1件のJSONを送れます。キーをフィールドに展開する場合はPipelineまたはコレクターのjson_as_fieldsを使います。type=influxdbを選ぶ場合はInfluxDBの行プロトコルが必要です。DataKit Log Streaming(英語)
識別子が決まっているサンプルを使うと、双方で検索できるイベントを突き合わせられます。タグとイベント時刻はレコードから独立しているため、通常のJSON出力で残す値はフィールドとして明示し、受信先の形式に合わせます。イベント時刻、複数行のレコード、フィールド型、重複を確認します。隔離した環境で受信を一時的に止めれば、蓄積、復旧後の送信、再送による重複も見分けられます。その結果を確かめてから本番の経路を切り替えます。
よくある質問
タグとレコードのフィールドはどう違いますか?
タグは経路の選択に使うメタデータです。フィールドはレコードの内容です。出力先でタグを検索したい場合は、record_transformerで${tag}をフィールドとして加えます。record_transformer(英語)
バッファーディレクトリがいっぱいになるとどうなりますか?
設定上のバッファー上限と、ファイルシステムに空きがない状態は別です。overflow_actionには例外を出すthrow_exception、待機するblock、最古のチャンクを破棄するdrop_oldest_chunkがあります。ディスク容量は別途管理します。in_tailがBufferOverflowErrorを受けると、解消されるまで読み取りと位置ファイルの更新を止めます。その間にローテーションしたファイルが削除されると、未読ログを回収できない場合があります。バッファー上限(英語) · tailのオーバーフロー処理(英語)
Fluentdの処理能力を決めるのは何ですか?
解析とフィルターのCPU、バッファー用ディスクのI/O、ネットワーク、受信側がチャンクを受け取れる速度を切り分けます。1台あたりの処理上限は構成で変わります。対応プラグインならworkerを増やしたり、複数インスタンスへ入力を分散したりできます。イベントの大きさ、解析ルール、負荷、ACK条件をそろえて比較します。複数worker(英語)
設定変更を反映するには?
実行環境でfluentd --dry-run -c fluent.confを使い、設定とプラグインを読み込めるか確認します。Linuxのfluent-packageの標準的な設定ファイルは/etc/fluent/fluentd.confです。旧パッケージtd-agentはサポートを終了しています。systemctl reload fluentdが使えるかは、導入済みのサービスユニット次第です。UnixではsupervisorにSIGHUPを送るとworkerが再起動し、設定が反映されます。そのときメモリーバッファーの送信に失敗しても再試行されないため、事前にプラグインとバッファーの挙動を確認します。設定ファイルの場所(英語) · コマンドの選択肢(英語) · シグナルの動作(英語)
関連記事
資料確認日:2026年11月6日。
