Fluentdとは？設定ファイルの書き方とfluent-package v6移行の判断

アプリのログがサーバーごとに散らばっていて、障害のたびに各台へsshしてgrepしている。Fluentdはその状態を解くログ収集ミドルウェアです。入力・加工・出力をすべてプラグインとして差し替えられる点と、転送先が落ちてもバッファに貯めて再送する点が中核にあります。この記事では、2026年9月時点で最新のFluentd v1.19.3とパッケージ版fluent-package v6.0.4を前提に、tag・time・recordというイベント構造、source・match・filter・labelのタグ設計、Docker公式イメージでHTTP入力からファイル出力まで通す手順、ログ欠損の引き金になるバッファ既定値、サポートが切れたtd-agentとfluent-package v5からの移行、そしてFluent Bitやクラウド標準機能へ寄せるべき条件までを、実行できる設定例つきで扱います。

まとめ：Fluentd導入の判断基準とfluent-package v6移行の要点

Fluentdを入れる価値が最も大きいのは、出力先が2つ以上ある現場です。同じアクセスログをS3へ長期保管しつつElasticsearchへ検索用に流す、といった分岐をアプリ側のコードに書かずに済みます。出力先が1つだけなら、後述のとおりクラウド標準のログエージェントで足ります。

2026年9月時点の現行版は、本体がFluentd v1.19.3（2026年6月25日公開）、パッケージ版がfluent-package v6.0.4（2026年6月26日公開）です。注意すべきは旧版の状況で、Treasure Agent（td-agent）v4はすでに役目を終え、後継のfluent-package v5も公式告知どおり2025年末でサポートが終了しました。td-agentのまま止まっている環境は、セキュリティ修正が届かない状態で動いています。

設計で事故が起きる場所は、ほぼバッファに集中します。overflow_actionの既定値はthrow_exception、retry_timeoutの既定値は72時間です。転送先が丸3日落ちればチャンクは捨てられます。この2つを本番要件に合わせて明示的に書き換えたかどうかが、ログが欠けるかどうかを分けます。

Fluentdの構成要素｜Input・Filter・Buffer・Outputの処理の流れ

Fluentdは2016年11月8日にCNCFへIncubatingとして受け入れられ、2019年4月11日にGraduatedへ昇格したCNCFの卒業プロジェクトです。設計思想は一貫していて、あらゆるログを共通の内部表現に変換し、タグでルーティングします。

イベントを構成するtag・time・recordの3要素とルーティングの起点

Fluentdが扱う1件のログは、tag・time・recordの3つ組です。tagはドット区切りの文字列で、これが唯一のルーティング鍵になります。timeはイベント発生時刻、recordはJSONオブジェクト本体です。

つまりFluentdの設定作業とは、入口でtagを付け、そのtagを見て出口へ振り分けるという作業です。app.accessやapp.errorのように、あとで分岐させたい粒度でtagを設計しておくと、出力先を増やすときに入力側へ手を入れずに済みます。ログを貯めるだけでなくシステムの内部状態を説明できる状態にする議論は、オブザーバビリティと監視の違いの整理が前提になります。

プラグイン方式の分類とgemで追加インストールする際の判断基準

入力、パーサ、フィルタ、出力、フォーマッタ、バッファといった役割ごとにプラグインが分かれ、必要なものだけを足して組み立てます。同梱されているのはin_tailやout_fileなど基本的なものだけで、S3やElasticsearchへ送るには追加インストールが必要です。

判断基準は単純です。公式のプラグイン一覧に載っているものを第一候補にし、GitHubで直近1年以内にコミットがあるかを確認してから入れます。放置されたプラグインはFluentd本体のメジャー更新で動かなくなり、移行時にそこだけ足を引っ張ります。パッケージ版ではgemではなく同梱のfluent-gemを使う点にも注意が必要です。

Docker上でFluentdを起動しHTTP入力からファイル出力まで通す手順

挙動を確かめるだけなら、ホストにインストールせずコンテナで完結します。公式のDockerデプロイ手順はfluent/fluentd:edge-debianを推奨し、設定ファイルを/fluentd/etcへマウントして-cで指定する構成を示しています。

Docker公式イメージを1コマンドで起動する最小構成と動作確認

まず設定ファイルを1枚用意します。HTTPで受けてファイルへ落とすだけの、動作確認用の最小構成です。

# ./etc/fluentd.conf
<source>
  @type http
  port 9880
  bind 0.0.0.0
</source>

<match app.**>
  @type file
  path /fluentd/log/app
  append true
  <buffer>
    @type file
    path /fluentd/buf/app
    flush_interval 5s
  </buffer>
</match>

ホスト側に3つのディレクトリを作り、そのまま起動します。-vを付けると起動時に読み込んだ設定が標準出力へ出るため、書き間違いをその場で拾えます。

mkdir -p ./etc ./log ./buf

docker run --rm -p 9880:9880 \
  -v "$(pwd)/etc:/fluentd/etc" \
  -v "$(pwd)/log:/fluentd/log" \
  -v "$(pwd)/buf:/fluentd/buf" \
  fluent/fluentd:edge-debian \
  -c /fluentd/etc/fluentd.conf -v

HTTPで投入したログがファイルに落ちるまでのcurl検証手順

起動したら、URLのパス部分がそのままtagになる点を使って投入します。/app.accessへPOSTすればapp.accessというtagが付き、先ほどのmatch app.**に拾われます。

# tag は URL のパスで決まる
curl -X POST -d 'json={"user":"alice","action":"login"}' \
  http://localhost:9880/app.access

# flush_interval で指定した5秒後にファイルが現れる
sleep 6 && ls -l ./log
cat ./log/app.*.log

ここで何も出ない場合、原因は3つに絞られます。tagがmatchのパターンに掛かっていないか、バッファ用ディレクトリの書き込み権限がないか、flush_intervalの経過を待てていないかです。コンテナの標準出力に[warn]の行が出ていれば、そこに理由が書かれています。

設定ファイルの書き方｜source・match・filter・labelのタグ設計

公式の設定ファイル構文で定義されているディレクティブは、source、match、filter、system、label、worker、@includeの7種類です。実務で書くのは前半の5つに集中します。

sourceとmatchの最小構成とタグのアスタリスク記法の使い分け

tagのマッチには4種類の書き方があります。*は単一のパートだけに一致し、a.*はa.bに当たりますがa.b.cには当たりません。**は0個以上のパートに一致するため、a.**はaもa.b.cも拾います。複数候補を並べるなら{X,Y,Z}、それでも足りない場合はスラッシュで囲んだ正規表現を使います。

設計で効くのは「広いパターンを後に置く」という評価順のルールです。公式ドキュメントも明記していますが、match **を先頭に書くと以降のmatchは一切評価されません。ログが1箇所へ吸い込まれて出てこない事象の大半は、この順序です。

labelで経路を分離しmatchの記述順による取りこぼしを防ぐ設計

設定が数十行を超えたら、評価順に頼る書き方をやめてlabelへ移します。sourceに@labelを指定すると、そのイベントは通常のルーティングから外れ、指定したlabelブロックの中だけで処理されます。経路が物理的に分かれるので、他の章を書き換えても影響しません。

<source>
  @type tail
  @label @APP
  path /var/log/app/*.log
  pos_file /var/log/fluentd/app.log.pos
  tag app.access
  <parse>
    @type json
  </parse>
</source>

<label @APP>
  <filter app.**>
    @type record_transformer
    <record>
      hostname "#{Socket.gethostname}"
    </record>
  </filter>
  <match app.**>
    @type stdout
  </match>
</label>

in_tailを使うときはpos_fileの指定を省かないでください。読み取り位置を記録するファイルで、これが無いと再起動のたびに読み直しや取りこぼしが起きます。誰がいつ何をしたかを追える形にログを設計する話は、Fluentdを用いた監査ログシステムの設計で扱っています。

ログ欠損を防ぐバッファ設計｜file bufferの既定値とリトライの上限

Fluentdは受け取ったイベントをチャンク単位でバッファに貯め、まとめて出力します。バッファセクションの公式ドキュメントに既定値が並んでいますが、本番要件のまま使える値は多くありません。

memoryとfileでバッファ既定値が異なる点とディスク容量の見積もり

まず押さえるのは、@type memoryと@type fileで既定値が大きく違うことです。

fileバッファのtotal_limit_sizeは既定で64GBあります。ログ量の多いホストで転送先が長時間落ちると、既定のまま放置したディスクが先に埋まります。見積もりは「1時間あたりのログ量 × 許容したい停止時間」で出し、その値を明示的に書いてください。file bufferのドキュメントによればpathに既定値はなく指定必須で、チャンクファイルの拡張子はpath_suffixの既定値.logが付きます。

retry_timeoutの既定72時間とoverflow_actionで起きる欠損

再送の挙動も既定値のままでは危険です。retry_typeの既定はexponential_backoff、retry_waitは1秒から始まり、retry_timeoutの72時間で打ち切られます。そしてoverflow_actionの既定はthrow_exceptionで、バッファが満杯になると例外を投げて入力側を止めます。

<match app.**>
  @type forward
  <buffer>
    @type file
    path /var/log/fluentd/buf/app
    chunk_limit_size 32MB
    total_limit_size 8GB
    flush_interval 10s
    flush_thread_count 4
    retry_type exponential_backoff
    retry_timeout 24h
    retry_max_interval 5m
    overflow_action drop_oldest_chunk
    compress zstd
  </buffer>
  <server>
    host 10.0.1.20
    port 24224
  </server>
</match>

どちらを選ぶかを決める基準は、ログの性質です。アクセス解析用ならdrop_oldest_chunkで古い分を捨て、アプリの稼働を優先します。課金や監査に使うログなら捨ててはいけないので、total_limit_sizeを十分に取ったうえでblockを選び、バッファ使用率のアラートを先に鳴らします。既定のまま運用するという選択肢は、この2つのどちらにも当てはまりません。

本番投入前に上げるファイルディスクリプタ上限65536とNTP設定

設定ファイル以前の前提条件がインストール前のドキュメントにまとまっています。見落とすと、負荷が上がった時点で唐突に転送が止まります。

• ulimit -nが1024のままなら不足。推奨値は65536で、limits.confかsystemdのLimitNOFILE=65536で引き上げる
• 集約ノードを置くならnet.core.somaxconnを1024、net.ipv4.tcp_max_syn_backlogを8096へ。forward用の24224番はnet.ipv4.ip_local_reserved_portsで予約する
• chronyなどのNTPデーモンを入れる。時刻がずれた複数ホストのログは、集約した時点で時系列が崩れて調査に使えなくなる

優先順位を付けるなら、まずファイルディスクリプタとNTPの2つです。カーネルパラメータの調整が効いてくるのは、1ノードへ数千接続が集まる集約構成に育ってからで構いません。

td-agentからfluent-package v6へ移行する手順とv5のEOL対応

日本語の入門記事の多くはtd-agent前提で書かれており、そのまま読むと現在では通らない手順に出会います。パッケージの系譜はTreasure Agent v3・v4、fluent-package v5、fluent-package v6の順で、公式リリースを実測すると最新はv6.0.4（2026年6月26日）です。

td-agent v4とfluent-package v5のEOLで残る運用リスク

v6.0.0のリリース告知は「The current LTS version, Fluent Package v5 LTS, will reach end of support at the end of 2025.」と明記しています。2026年9月時点でv5もv4も期限を過ぎており、脆弱性が見つかっても修正版は降ってきません。

まず現状を数字で押さえます。以下のコマンドで、どのパッケージが入っていて同梱のFluentd本体が何版かを確認できます。

# RHEL系で入っているパッケージを確認する
rpm -qa | grep -E 'td-agent|fluent-package'

# Debian/Ubuntu系の場合
dpkg -l | grep -E 'td-agent|fluent-package'

# 同梱されている Fluentd 本体の版を見る
/opt/fluent/bin/fluentd --version

# 設定を読み込まずに構文だけ検証する（移行前後で必ず実行）
/opt/fluent/bin/fluentd -c /etc/fluent/fluentd.conf --dry-run

td-agent時代の設定ファイルは/etc/td-agent/td-agent.conf、fluent-package以降は/etc/fluent/fluentd.confに置かれます。実行ファイルの場所も/opt/td-agentから/opt/fluentへ移っているため、監視スクリプトやデプロイ用のAnsibleにパスを直書きしている場合はそこも書き換え対象です。

v6で切られたDebian 11・Ubuntu 20.04と移行前に確認する項目

v6.0.0で同梱のRubyがv3.2からv3.4へ上がり、対応OSも入れ替わりました。移行の可否は、まずOS側で決まります。

Debian 11やUbuntu 20.04で動いているなら、Fluentdの移行はOS更改とセットになります。順序を逆にすると、パッケージだけ入れ替えて依存で詰まります。合わせて確認すべきは追加プラグインの対応状況で、Ruby 3.4でビルドできないgemが混じっていれば、そこが移行のボトルネックです。fluent-gem listで一覧を取り、各プラグインのリポジトリで対応版を先に調べてください。移行の設計と実施、その後の運用までまとめて外に出したい場合は、保守運用・内製化支援で引き受けています。

v1.19で追加されたzstd圧縮・バッファ退避・OpenTelemetry対応の使い所

本体のリリース履歴を見ると、v1.19.0が2025年7月30日、最新のv1.19.3が2026年6月25日です。v1.16系も2025年12月10日のv1.16.11まで保守が続きましたが、新機能はv1.19系にしか入りません。

zstd圧縮とバッファ退避で転送量と再送失敗を同時に抑える設定

v1.19.0の告知で追加されたcompress zstdは、buffer・out_file・out_forwardで使えます。拠点間をまたぐ転送では帯域とディスクの両方に効きます。

ただし条件が1つあります。告知に「You cannot use it with Fluent Bit or Fluentd versions older than v1.19.0」と書かれているとおり、受け側がFluent Bitだったり、v1.19.0未満のFluentdだったりすると相互接続できません。混在環境ではgzipのままにしてください。もう1つのバッファ退避は、リトライ上限を超えたチャンクを捨てずに退避ディレクトリへ逃がす動きで、buf_fileとbuf_file_singleが対象です。捨ててはいけないログを扱う集約ノードほど、入れる価値があります。

OpenTelemetry連携とゼロダウンタイム再起動を入れる判断条件

fluent-package v6ではHTTP経由のOpenTelemetryデータ転送と、設定再読み込み・再起動をダウンタイムなしで行う機能が入りました。後者はWindowsが対象外です。

OpenTelemetryへ寄せるべきかは、扱う信号の数で判断します。ログだけを運んでいるならFluentdの既存プラグインで足り、乗り換える理由はありません。メトリクスやトレースも同じ経路へ集めたいなら、収集側の標準を揃える意味でOpenTelemetry対応を使う価値が出ます。ゼロダウンタイム再起動のほうは判断が簡単で、設定変更のたびに数秒のログ欠損を許容できない集約ノードなら入れる、それ以外は急ぎません。

Fluentdを採用しない判断｜Fluent Bitとクラウド標準機能に寄せる条件

ここは立場を明確にします。Fluentdは万能ではなく、むしろ入れないほうがよい構成が2つあります。

Fluent Bitへ寄せる条件とFluentdを残す条件の切り分け

各ノードに常駐させるエージェント側は、Fluent Bitを選んでください。Rubyランタイムを抱えるFluentdに対し、C実装のFluent Bitはメモリ使用量が一桁小さく、Kubernetesのように1ノードあたりのリソース枠が決まっている環境では差が効きます。実務で定着している形は、各Podのログ収集をFluent Bitが担い、集約ノードのFluentdが加工と分岐を担う2段構成です。

逆にFluentdを残すのは、加工が複雑な集約層です。1つの入力を条件で3方向へ分け、途中でマスキングと項目追加をかける、といった処理はプラグインの豊富さがそのまま効きます。各実装の違いとAWSコンテナ環境での構成パターンはFluent Bitの仕組みとFluentdとの比較に整理しています。Kubernetes側の構成から確かめるなら、kindでのクラスタ構築手順から試すのが早い経路です。

CloudWatch LogsやDatadog標準エージェントで足りる小規模構成

サーバーが数台、出力先が1つ、ログ量が1日数GB以下。この条件に当てはまるなら、Fluentdは過剰です。CloudWatch Agentやクラウド標準のログ収集機能を入れれば、バッファ設計もパッケージのEOL追跡も自分で抱えずに済みます。Fluentdを入れた瞬間、設定ファイル・プラグインの版・バッファ用ディスクという3つの運用対象が増えることを忘れないでください。

判断の分かれ目は、出力先の数と加工の有無です。「1つの入力を2つ以上の出力へ分ける」または「送る前に項目の追加や除去をする」のどちらかが要件に入った時点で、Fluentdの出番になります。どちらも無いうちは入れる必要がありません。SaaS側へ寄せる場合の選定軸と課金モデルはオブザーバビリティツールの比較にまとめてあります。

よくある質問

Fluentdの導入検討でよく挙がる質問を、一次情報の実測値とともに整理します。

FluentdとFluent Bitはどちらを選べばよいですか？

1つのプロセスで両方の役割を賄おうとせず、層で分けるのが定石です。各ノードに常駐させる収集エージェントはメモリ使用量の小さいFluent Bit、複雑な加工と分岐を担う集約ノードはプラグインの豊富なFluentd、という2段構成になります。ただしv1.19.0で追加されたzstd圧縮はFluent Bitとの間では使えないため、2段構成にするなら圧縮はgzipのままにしてください。

td-agentはもう使えないのですか？

動作はしますが、サポートは終わっています。td-agent v4の後継であるfluent-package v5も、公式告知どおり2025年末でサポートが終了しました。2026年9月時点の現行版はfluent-package v6.0.4です。脆弱性の修正が届かない状態なので、稼働中の環境はOS側の対応状況を確認したうえで移行計画を立ててください。

Fluentdの設定ファイルはどこに置かれますか？

パッケージ版では/etc/fluent/fluentd.confです。td-agent時代の/etc/td-agent/td-agent.confから変わっているため、移行時は監視スクリプトやプロビジョニングコードに書かれたパスも合わせて直します。Docker公式イメージの場合は/fluentd/etcへマウントし、起動時に-cで明示します。

Fluentdでログが欠ける原因は何ですか？

最も多いのはバッファ関連の既定値です。retry_timeoutの既定は72時間で、転送先の停止がこれを超えるとチャンクは破棄されます。overflow_actionの既定はthrow_exceptionのため、バッファ満杯時には入力側で例外が発生します。次に多いのがmatchの記述順で、広いパターンを先に書いたせいで後続が評価されていないケースです。

Fluentdの学習で最初に触るべき設定はどれですか？

Docker公式イメージでin_httpとout_fileだけを書き、curlでPOSTしてファイルに落ちるところまでを通してください。所要時間は10分程度です。ここでtagがmatchのパターンに掛かる感覚を掴んでから、in_tailとpos_file、続いてlabelによる経路分離へ進むと、設定ファイルが大きくなっても迷いません。

関連記事

• Mackerelでサーバーを監視する手順｜agent導入から料金試算と採用判断まで：ログ収集の隣にあるメトリクス監視をSaaSで賄う場合の導入手順と費用感を扱っています。
• 外形監視とは？内部監視との違いと監視項目・実装、導入判断を実装目線で解説：ログでは拾えない「利用者から見た停止」を検知する側の設計です。
• インシデント管理とは？ITIL準拠のプロセスと監視・オンコールの実装を運用目線で解説：集めたログを障害対応のプロセスへつなぐ工程を整理しています。
• オブザーバビリティ（可観測性）とは？監視・モニタリング・APMとの違いと使い分けを解説：ログ・メトリクス・トレースの役割分担を概念から確認できます。