Fluent Bit入門:Tail、パーサー、SQLによるログ処理

Fluent Bitの入力・フィルター・出力をつなぎ、パーサー登録、Kubernetesメタデータ、Tailの位置管理、ウィンドウ付きSQLタスクの設定を解説します。

ベストプラクティス
ログの収集と処理の流れを表すイラスト

Fluent Bitは、Fluentdのエコシステムに属する軽量なログ・テレメトリープロセッサーです。主にCで実装され、ホスト、Kubernetesのノード、エッジ環境などで使えます。ただし、軽量という設計方針と、稼働時のメモリ使用量が一定であることは別です。ファイル数、解析、メタデータのキャッシュ、送信待ちデータによって必要なリソースは増えます。依存関係もビルドとプラグインに左右されます。

この記事のクラシック設定とSQLはFluent Bit 3.2の公式文書に基づきます。3.2を最新版として推奨するものではありません。ログをどう読み、構造化し、転送するかを、設定と結び付けて見ていきます。

最初に押さえるポイント

  • 軽量でもリソースの見積もりは必要です。 各ノードへ配置する際は、ログ量、ファイル数、フィルター、滞留の影響を考えます。
  • 処理段階を分けて設定します。 [INPUT]、[FILTER]、[OUTPUT]で収集、加工、転送を定義します。YAMLも使えますが、利用バージョンの仕様を確認します。
  • Kubernetesの情報は前提条件をそろえて関連付けます。 tagやファイル名で対象を特定し、キャッシュやAPI Server、Kubeletへのアクセスから追加情報を得ます。

1. 設定とデータの流れ

次の内容を/etc/fluent-bit/fluent-bit.confに保存します。参照するパーサーファイルは第3節で定義します。ディレクトリは事前に用意し、実行アカウントにはログ・設定の読み取りと、/var/lib/fluent-bit/内のDBへの書き込み権限が必要です。

[SERVICE]
    Flush        1
    Log_Level    info
    Parsers_File /etc/fluent-bit/parsers-app.conf

[INPUT]
    Name         tail
    Path         /var/log/app/*.log
    Tag          app.*
    Parser       app_json
    DB           /var/lib/fluent-bit/tail-app.db
    Mem_Buf_Limit 10MB
    Refresh_Interval 5

[FILTER]
    Name         record_modifier
    Match        app.*
    Record       hostname ${HOSTNAME}
    Record       env production

[OUTPUT]
    Name         http
    Match        app.*
    Host         logs.example.com
    Port         443
    URI          /ingest
    Format       json
    tls          On

INPUTがレコードを読み、tagを付けます。FILTERとOUTPUTはMatchで対象を選びます。TailのTag app.*では、*が読み取るファイルの絶対パスに展開され、スラッシュはドットへ置き換わります。すべてのレコードに同じ文字列が付くわけではありません。

Refresh_Intervalはファイルを検出する間隔、Flushはエンジンがデータをフラッシュする間隔です。1秒の設定でバックエンドまで1秒以内に届くと保証されるわけではありません。${HOSTNAME}も、実行環境が変数を提供していることが前提です。Tailの設定(英語)

HTTPの転送先を変えるときは、エンドポイント、認証、ペイロード形式、レスポンスの扱いを既知のサンプルで確認します。HostとURIの変更だけでは移行は完了しません。この例はメモリバッファを使い、Mem_Buf_Limitへの到達で入力が一時停止することがあります。TailのDBが保存するのは読み取り位置であり、未送信データの永続キューではありません。バッファとストレージ(英語)

同じファイルをGuanceへ取り込むなら、DataKitのログコレクター(英語)でアクセス可能なlogfilesを指定し、source、Pipeline、イベント時刻の扱いを設定する方法もあります。別の収集経路なので、Fluent BitのTail DB、パーサー定義、SQLタスクは引き継ぎません。読み取り開始位置、フィールド、二重収集の扱いも改めてそろえます。

2. 主要なプラグイン

段階 よく使うプラグイン
入力 ファイル用のtail、journal用のsystemd、syslog、http、opentelemetry
フィルター 抽出・除外のgrep、フィールド追加のrecord_modifier、条件付き変更のmodify、メタデータ用のkubernetes、スクリプト用のlua、構造変更のnest
出力 http、file、Fluentdなどへ送るforward、kafka、es/opensearch、s3

利用できるプラグインはバージョン、プラットフォーム、ビルドによって変わります。すべてのパッケージに表の全機能が含まれるとは限りません。

Kubernetesフィルターは、tagなどからPod、Namespace、コンテナを特定し、キャッシュや、設定されたAPI Server/Kubeletへのアクセスで追加情報を取得します。コンテナランタイムから全項目を自動取得する仕組みではありません。

/var/log/containers/*.logを読む場合は、ホストログのマウント、tagとKube_Tag_Prefix、Docker/CRIの形式とパーサーを合わせます。APIへ接続するには、サービスアカウント、RBAC、ネットワークの条件も必要です。第1節のapp.*は通常のファイル収集例であり、そのままKubernetesの設定にはなりません。

メタデータの付与とアプリケーション本文の解析も別です。Merge_Log Onはlog内のJSON、または指定したパーサーで解析した内容をマージできます。Keep_Logの既定動作では元のフィールドを残すため、logがあるだけで解析失敗とは判断できません。Kubernetesフィルター(英語)

3. パーサーを登録してから入力で参照する

ログパーサー(log parser)は、定義を起動時に読み込んだうえで使います。以下を/etc/fluent-bit/parsers-app.confへ保存します。第1節のParsers_Fileがこのファイルを読み込みます。

[PARSER]
    Name        app_json
    Format      json
    Time_Key    time
    Time_Format %Y-%m-%dT%H:%M:%S%z
    Time_Keep   On

[PARSER]
    Name        nginx
    Format      regex
    Regex       ^(?<remote>\S+) \S+ \S+ \[(?<time>[^\]]+)\] "(?<method>\S+) (?<path>\S+) \S+" (?<code>\d{3})(?:\s|$)
    Time_Key    time
    Time_Format %d/%b/%Y:%H:%M:%S %z
    Time_Keep   On
    Types       code:integer

Tail入力のParser app_jsonは、次のような1行1JSONオブジェクトを対象とします。

{"time":"2026-11-05T10:00:00+0800","level":"error","pod_name":"checkout-7d8f","message":"upstream timeout"}

+0800は%zに対応します。時刻形式が変わるなら、キー名だけでなくTime_Formatも合わせます。Time_Keep Onは解析後も元の時刻フィールドを残します。

Nginxのアクセスログには、該当INPUTでParser nginxを指定します。05/Nov/2026:10:00:00 +0800は2つ目の時刻形式に対応します。正規表現はリクエストのパスとHTTPプロトコルを分け、codeを整数へ変換します。

Fluent Bitの正規表現はOnigmoのRubyモードで、名前付きキャプチャを使います。他の正規表現エンジンの構文がすべて通るわけではありません。複数行のスタックトレースにはmultilineの設定も必要です。JSONは解析形式であり、jsonという名前のパーサーが使えるかどうかは、読み込んだ定義次第です。パーサーの登録(英語) · 正規表現と時刻解析(英語)

4. SQLの入力と集計ウィンドウを明示する

ストリームプロセッサーでは、流れてくるレコードを抽出・集計できます。以下はトップレベルのpod_nameでグループ化し、5秒ごとのタンブリングウィンドウでエラー件数を数えます。

SELECT pod_name, COUNT(*) AS errors
FROM TAG:'app.*'
WINDOW TUMBLING (5 SECOND)
WHERE level = 'error'
GROUP BY pod_name;

TAG:'app.*'はtagのパターンで対象を選びます。STREAM:名前は入力ストリーム名を参照し、既定名はtail.0のような形式です。INPUTのAliasで名前を付けることもできます。tagのワイルドカードをそのままSTREAM:app.*とは書けません。

ウィンドウを省くと、集計対象はその時点のレコードバッファになります。一定の5秒間を数えた結果として扱うことはできません。

タスクを/etc/fluent-bit/streams.confに保存します。

[STREAM_TASK]
    Name pod_errors
    Exec SELECT pod_name, COUNT(*) AS errors FROM TAG:'app.*' WINDOW TUMBLING (5 SECOND) WHERE level = 'error' GROUP BY pod_name;

既存の[SERVICE]にStreams_File /etc/fluent-bit/streams.confを追加し、fluent-bit -c /etc/fluent-bit/fluent-bit.confなどで主設定を読み込みます。SERVICEセクションをもう一つ作らないようにします。

この例では、入力レコードが先ほどのJSONと同じトップレベルのpod_nameとlevelを持つことが前提です。通常のTail入力はPod情報を付与しません。Kubernetesフィルターが作るネストしたフィールドも、このトップレベルのキーと同一ではありません。

単独のSELECTは結果を標準出力へ送ります。元のログの出力を置き換えたり、送信量を減らしたりはしません。派生レコードをパイプラインへ戻すには、CREATE STREAM ... WITH (tag='new-tag') AS SELECT ...を使い、新しいtagをルーティングします。同じタスクへ再び入らない条件も必要です。この集計は各インスタンスが処理したレコードの件数であり、ノード間集計やバックエンドのアラート移行まで自動で行うものではありません。SQLとウィンドウ(英語) · ストリームとtag(英語)

よくある疑問

Fluent BitとFluentdはどういう関係ですか。

同じエコシステムに属する別のプロセッサーです。順番に更新していく2世代の製品ではありません。Fluent Bitは主にC、FluentdはRubyとCで実装されています。ノード側のFluent Bitから中央のFluentdへForwardプロトコルで送る構成はよく使われますが、どちらも構成次第で転送・集約を担当でき、単独でも使えます。公式の関係説明(英語)

設定はどうデバッグしますか。

まずOUTPUTをstdoutに変え、レコードとtagを確認します。次にLog_Level debugでパーサーの読み込み、解析、ルーティングを調べます。logは入力由来のフィールド、アプリケーションが持つ正当なフィールド、Keep_Logで残した値の場合もあります。既知のサンプルで、必要なキー、型、イベント時刻が得られたかを確かめます。

Tailは重複収集しませんか。

重複する可能性はあります。DBは追跡するファイルとオフセットを保存しますが、その状態の永続化、ファイルの識別、ローテーション、切り詰め、読み取り位置を適切に扱う必要があります。起動時に検出し、保存済みオフセットのないファイルは、既定では末尾から読みます。既存内容を読む場合はRead_from_Headを明示的に検討します。Rotate_Waitはローテーション後に旧ファイルを監視する時間、Ignore_Olderは古いファイルを除外する条件であり、重複排除のスイッチではありません。

読み取り位置の保存は、バックエンドでの保存完了を意味しません。メモリバッファの消失、入力停止中のローテーションや削除、出力のリトライと上限により、欠落や重複が生じ得ます。ファイルシステムバッファは復旧を助けますが、Tail DBだけでexactly-onceを保証することはできません。元ファイルの保持、バッファ、リトライ、受信側の扱いを併せて確認します。Tailの状態管理(英語) · 出力のリトライ(英語)

Luaフィルターを使うのはどんなときですか。

組み込みフィルターだけでは表せないマスキングや計算に使います。ただし、フィルターのコールバック、利用できるランタイム、型と時刻の精度には制約があります。何でもできるわけではありません。遅い処理やブロッキング処理は処理速度に影響するため、例外やフィールド変化もサンプルで確認します。既存フィルターで表せるなら、単純な設定を優先します。Luaのコールバックと制約(英語)

関連記事

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ