今天來用實際案例介紹如何在 Graylog 配置 Linux 服務的日誌監控。
以 Python FastAPI 應用程式為例，建立完整的日誌收集與分析流程。

架構設計

我們將建立一個基於 Graylog Sidecar + Filebeat 的日誌收集架構。在這個架構中，FastAPI 服務將產生 JSON 格式的日誌檔案，透過 Filebeat 收集並傳送至 Graylog，最後利用 Pipeline 規則處理時間戳記覆蓋。

架構流程：

• FastAPI 服務 → JSON 日誌檔案 → Filebeat → Graylog Sidecar → Graylog Server

FastAPI 服務日誌設定

首先，設定 FastAPI 應用程式的日誌輸出格式。以下是一個簡化的 FastAPI 服務範例：

from fastapi import FastAPI, Field
import logging
import json
from datetime import datetime

app = FastAPI()

@app.post("/log")
async def write_log(timestamp: float | None = Field(default=None), msg: str):
    log_data = {
        "_timestamp": timestamp if timestamp is not None else datetime.now().timestamp(),
        "message": msg,
    }
    
    # 寫入日誌檔案
    with open("/var/log/fastapi-app.log", "a") as f:
        f.write(json.dumps(log_data) + "\n")
    
    return {"status": "logged"}

Graylog Sidecar 安裝與配置

安裝 Graylog Sidecar

在 Ubuntu 系統上安裝 Graylog Sidecar：

# 下載並安裝 Sidecar 套件庫
wget https://packages.graylog2.org/repo/packages/graylog-sidecar-repository_1-5_all.deb
sudo dpkg -i graylog-sidecar-repository_1-5_all.deb

# 更新套件列表並安裝 Sidecar
sudo apt update && sudo apt install graylog-sidecar

配置 Sidecar

編輯 Sidecar 配置檔案：

sudo vi /etc/graylog/sidecar/sidecar.yml

關鍵配置項目：

server_url: "http://your-graylog-server:9000/api"
server_api_token: "your-api-token-here"
collector_binaries_accesslist:
  - "/usr/share/filebeat/bin/filebeat"

collector_binaries_accesslist 中添加 filebeat 執行檔路徑避免 graylog-sidecar 無法正確的使用 filebeat。

啟動 Sidecar 服務：

sudo graylog-sidecar -service install
sudo systemctl enable graylog-sidecar
sudo systemctl start graylog-sidecar

Graylog 輸入源配置

在 Graylog Web 介面中建立 Beats 輸入源：

1. 進入 System → Inputs
2. 選擇 Beats 輸入類型
3. 設定埠號為 5044（預設）
4. 勾選 Global 選項以允許所有節點接收資料

Filebeat 配置

透過 Graylog Web 介面配置 Filebeat 收集器：

1. 進入 System → Sidecars → Configuration
2. 建立新的配置，名稱為 "FastAPI Log Collection"
3. 選擇 filebeat 收集器
4. 輸入以下配置：

   # Graylog 必需欄位
   fields_under_root: true
   fields.collector_node_id: ${sidecar.nodeName}
   fields.gl2_source_collector: ${sidecar.nodeId}
   
   filebeat.inputs:
   - type: filestream
   enabled: true
   paths:
       - you-path-to-log/<log-name>.log
   
   output.logstash:
   hosts: ["your-graylog-server:5044"]
   
   path:
   data: /var/lib/graylog-sidecar/collectors/filebeat/data
   logs: /var/lib/graylog-sidecar/collectors/filebeat/log
   

5. 在 Administration 頁簽中找到對應的 collector，並將上面設定的配置 assign 給它

Pipeline 規則配置

為了使用日誌中的 _timestamp 欄位覆蓋 Graylog 預設的接收時間戳，需要建立 Pipeline 規則。

建立 Pipeline 規則

1. 進入 System → Pipelines
2. 建立新的 Pipeline，名稱為 "FastAPI Timestamp Override"
3. 建立新的 Rule，名稱為 "Override Timestamp"

Pipeline 規則內容

rule "Override FastAPI Timestamp"
when
  has_field("_timestamp")
then
  // 將毫秒時間戳轉換為日期對象
  let timestamp_ms = to_long($message._timestamp);
  let new_timestamp = to_date(timestamp_ms);
  
  // 覆蓋預設的 timestamp 欄位
  set_field("timestamp", new_timestamp);
  
  // 可選：移除原始的 _timestamp 欄位以避免混淆
  remove_field("_timestamp");
end

重要說明：

• has_field("_timestamp") 檢查是否存在 _timestamp 欄位
• to_long() 將字串轉換為長整數格式
• to_date() 將毫秒時間戳轉換為日期對象
• set_field("timestamp", new_timestamp) 覆蓋 Graylog 的預設時間戳

連接 Pipeline 到 Stream

1. 建立 Pipeline 後，進入 Pipeline 設定
2. 將 Pipeline 連接到 "All messages" Stream
3. 設定 Stage 為 Stage 0，確保在其他處理之前執行

測試與驗證

完成配置後，測試日誌收集是否正常運作：

# 呼叫 FastAPI 端點產生日誌
curl -X POST "http://localhost:8000/log" \
     -H "Content-Type: application/json" \
     -d '{"msg": "Test log message", "timestamp": 1697123456.789}'

在 Graylog Web 介面中檢查：

1. System → Nodes 確認 Sidecar 狀態為 Running
2. Search 頁面搜尋日誌訊息
3. 確認時間戳欄位顯示正確的日誌產生時間，而非接收時間

故障排除

Sidecar 連線問題：

• 檢查 API Token 是否正確
• 確認網路連通性和防火牆設定
• 查看 Sidecar 日誌：sudo journalctl -u graylog-sidecar

Pipeline 規則不生效：

• 確認 Pipeline 已正確連接至 Stream
• 檢查 Processing failure stream 是否有錯誤訊息
• 驗證欄位名稱是否正確匹配

Filebeat 無法讀取檔案：

• 檢查檔案路徑和權限設定
• 確認 JSON 格式是否正確