Fluent Bit 詳解:Tail、日誌解析器與 SQL 串流處理

從 Fluent Bit 的 INPUT/FILTER/OUTPUT 設定,理解 Tail 讀取位置、日誌解析器註冊、Kubernetes 中繼資料與 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 才是引擎嘗試送出資料的節奏。設定一秒不代表後端一定在一秒內收到。${HOSTNAME} 也需要執行環境確實提供該變數。Tail 設定(英文)

HTTP 輸出換接後端前,要用已知樣本確認端點、認證、訊息格式與回應的意義,不能只改 Host 和 URI 就算遷移完成。這份設定使用記憶體緩衝,達到 Mem_Buf_Limit 時可能暫停輸入。Tail DB 儲存的是讀取位置,不是尚未送出紀錄的持久佇列。緩衝與儲存(英文)

若要將這些檔案接入觀測雲,也可以用 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、命名空間與容器,再使用快取,或按設定存取 API Server/Kubelet 取得標籤等資料。它不是直接從容器執行環境自動取得所有欄位。

收集 /var/log/containers/*.log 時,主機日誌掛載、tag 與 Kube_Tag_Prefix、Docker/CRI 格式及解析器必須對應。API 存取也需要服務帳號、RBAC 與網路條件。前節的 app.* 是一般檔案範例,不能直接視為完整 Kubernetes 設定。

補上中繼資料與解析應用本文是兩件事。Merge_Log On 可嘗試解析 log 內的 JSON,或使用指定解析器再合併欄位。Keep_Log 預設保留原欄位,因此出現 log 並不代表解析失敗。Kubernetes 篩選器與 Merge_Log(英文)

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 適用於以下每行一個 JSON 物件的日誌:

{"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 對應第二個時間格式。正規表示式把請求路徑與 HTTP 協定分開,並將 code 轉成整數。

Fluent Bit 使用 Onigmo 的 Ruby 模式與具名擷取群組,並非所有正規表示式方言都相容;多行堆疊也需要額外的 multiline 設定。JSON 是解析格式,名為 json 的解析器是否存在,取決於實際載入的定義,不能當作永遠可用的零設定名稱。解析器註冊(英文) · 正規表示式與時間解析(英文)

4. 明確指定 SQL 來源與聚合視窗

串流處理器可以篩選與聚合正在流動的紀錄。以下依頂層 pod_name,計算每個五秒固定視窗內的錯誤數:

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.*。

未指定視窗時,聚合會針對目前收到的紀錄緩衝區執行,不能把結果解讀成穩定的「每五秒計數」。

將任務儲存為 /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 是什麼關係?

兩者同屬 Fluentd 生態,但屬於可獨立運作、也可搭配的不同處理器,不是必須依序升級的兩代。Fluent Bit 主要使用 C,Fluentd 使用 Ruby 與 C。節點側採用 Fluent Bit、中央使用 Fluentd 並透過 Forward 協定連接,是常見架構;但兩者都能依外掛與部署擔任轉送或彙聚角色。官方專案關係說明(英文)

如何除錯設定?

先把 OUTPUT 改為 stdout,確認實際紀錄與 tag,再用 Log_Level debug 查看解析器載入、解析與路由。log 可能來自輸入本身、應用 JSON 的合法欄位,或 Keep_Log 保留的內容,不能單憑這個欄位判定失敗。應使用已知樣本,核對期望欄位、型別與事件時間。

Tail 會重複收集嗎?

有可能。DB 保存追蹤檔案與位移,但復原仍要正確持久化狀態,並處理檔案識別、輪替、截斷與讀取起點。啟動時找到、且沒有已存位移的檔案,預設從末尾讀取;若要讀取既有內容,需明確評估 Read_from_Head。Rotate_Wait 控制輪替後繼續觀察舊檔案的時間,Ignore_Older 依檔案年齡排除舊檔,兩者都不是去重開關。

DB 位移不代表後端已確認保存。記憶體緩衝遺失、輸入暫停時檔案輪替或刪除、輸出重試與次數限制,都可能造成遺漏或重複。檔案系統緩衝可改善復原能力,但不能只憑 Tail DB 宣稱 exactly-once。來源檔案保留、緩衝、重試及接收端語義都要一起核對。Tail 狀態與輪替(英文) · 輸出重試(英文)

什麼時候使用 Lua 篩選器?

內建篩選器不足以表達欄位遮罩或計算時,可以使用 Lua。它仍受篩選器回呼介面、執行環境、型別與時間精度影響,並非什麼都能做。耗時或阻塞邏輯會拖慢處理,腳本例外與欄位變動也需要以樣本確認。既有篩選器能表達時,優先採用簡單設定。Lua 回呼與限制(英文)

延伸閱讀

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

在线开通,按量计费,真正的云服务!

立即開始

选择观测云版本

代码托管平台