Fluentd 詳解:日誌收集、路由與外掛

說明 Fluentd 的 tag 比對、外掛與檔案緩衝,以及 HTTP 和 Forward 輸出的重試與接收確認。

最佳實務
事件記錄與日誌資料分析插畫

Fluentd 設定通過檢查,日誌仍可能送錯地方。把 <match **> 放在 Nginx 存取日誌的專用規則之前,範圍較廣的規則就會先接走事件。更換接收端時,除了地址,也要看規則排在哪裡。

Fluentd 是 CNCF 畢業專案,也是以 Ruby 為主、可透過外掛擴充的日誌收集器。本文從一筆 Nginx 日誌走過輸入、加工和輸出,再說明把檔案輸出改成 HTTP 時需要核對的條件。範例依 Fluentd 1.x 與接收端的官方文件整理。CNCF 專案(英文) · Fluentd 原始碼(英文)

先掌握這幾件事

  • 依 tag 選擇路由。 <source> 產生事件,符合條件的 <filter> 加工事件,第一條命中的 <match> 選擇輸出。
  • 核對外掛要求。 外部外掛需要相容的 Fluentd、Ruby 環境和依賴套件,部分外掛也有接收端版本要求。
  • 估算故障期間能積壓多少。 磁碟資料仍在時,檔案緩衝區可在重新啟動後恢復待送出的區塊。故障持續時,佇列和磁碟空間會被逐步用掉。
  • 用已知事件驗證接收端。 切換正式路由前,核對請求本文、欄位型別、事件時間和重試行為。

依 tag 路由 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 tag 的事件。過濾器補上收集器的主機名稱和環境欄位,接著由 access.** 的規則寫入檔案。在同一路由範圍中,Fluentd 依序套用符合的過濾器,直到首條命中的輸出。把較精確的輸出規則排在廣泛規則前,也把需要的過濾器放在相應輸出之前。要送往多個接收端,可以用 out_copy 等方式明確分流。設定與比對順序(英文)

pos_file 保存輸入的讀取位置。位置資料仍在時,重新啟動後可接續讀取。啟動時已存在的檔案如果沒有儲存位置,預設從檔案尾端開始。若要讀取現有內容,使用 read_from_head true。每個 tail 輸入應使用自己的位置檔,服務帳號需要日誌的讀取權限,以及位置檔和輸出目錄的寫入權限。接收端是否已寫入,要另外確認。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 傳送同一個 tag 範圍的事件,用下列區塊取代先前的檔案輸出。此例每行傳一筆 JSON,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 遺失,重送就可能產生重複。下游是否持久保存或已建立索引,需要另外核對。Forward 輸出(英文)

Fluent Bit 適合放在哪裡?

管線若依賴特定外掛或加工規則,可以考慮 Fluentd。Fluent Bit 的設計適合資源受限的收集環境,也能在 Kubernetes 以 DaemonSet 執行。一種做法是用 Fluent Bit 在節點收集,經 Forward 送到 Fluentd 彙整層。節點端具備所需加工及輸出時,也可以直接送到接收端。比較 CPU 和記憶體用量時,應採相同外掛需求、緩衝策略與流量條件。Fluent Bit 官方比較(英文) · Forward 互通(英文)

將現有 Fluentd 日誌送到另一個接收端

保留輸入和過濾鏈,先驗證接收端接受的格式。觀測雲 DataKit 的 Log Streaming 收集器使用 /v1/write/logstreaming。按部署方式啟用收集器,讓 Fluentd 的 HTTP 輸出指向能連線的地址,例如加上 ?source=nginx&service=web。預設文字模式可以接收 json_array false 送出的逐行 JSON。如需把 JSON 鍵值解析成欄位,可使用 Pipeline 或收集器的 json_as_fields 設定。type=influxdb 則須傳 InfluxDB 行協定資料。DataKit Log Streaming(簡體中文)

用帶固定識別碼的樣本事件比對兩端的查詢結果。Fluentd 的 tag 和事件時間是獨立中繼資料,普通 JSON 輸出要先把需要保留的值寫成欄位,接收端再依規則對應。檢查事件時間、多行日誌、欄位型別與重複資料。在隔離環境短暫中斷接收,也能觀察積壓、復原後補送及重複。等這些行為符合預期,再切換正式路由。

常見問題

Fluentd 的 tag 和記錄欄位有何不同?

tag 是路由用的中繼資料,欄位則是記錄本身的內容。若要在讀取 JSON 欄位的接收端查詢 tag,可用 record_transformer 將 ${tag} 寫入一個明確的欄位。record_transformer(英文)

緩衝區目錄滿了會怎樣?

達到 Fluentd 設定的緩衝上限,與檔案系統沒有寫入空間,是不同的故障。overflow_action 可設成拋出例外的 throw_exception、等待空間的 block,或丟棄最舊區塊的 drop_oldest_chunk。磁碟容量仍要另外管理。in_tail 遇到 BufferOverflowError 時會暫停讀取及更新位置檔,錯誤解除後繼續。如果輪替後的來源檔案在此期間被移除,未讀日誌可能無法補收。緩衝區上限(英文) · tail 的溢出行為(英文)

哪些因素會限制 Fluentd 吞吐量?

先分辨是解析和過濾用掉 CPU、緩衝磁碟 I/O 跟不上,還是網路及接收端拖慢送出。單一執行個體的處理上限視配置和負載而定。外掛支援時可以增加 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 日。


取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

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

立即開始

选择观测云版本

代码托管平台