Promtail¶

概述¶

Promtail 是 Grafana Labs 開發的開源日誌收集代理（log collector agent），主要用途是將主機或容器產生的日誌檔案收集、加入標籤，再推送至 Loki 日誌聚合系統。作為 Loki 官方推薦的客戶端，Promtail 特別擅長處理 Kubernetes、Docker 等動態環境的日誌收集，透過自動發現機制，可以在毋須改動應用程式的情況下捕捉標準輸出（stdout/stderr）。專案以 Apache 2.0 許可證發布，是 Grafana 可觀測性堆疊（Observability Stack）的關鍵組成部分。

架構¶

Promtail 採用客戶端-伺服器模型：Loki 作為伺服器端，Promtail 作為客戶端。其架構核心包含三部分：

日誌發現（Discovery）：支援檔案路徑、journald、syslog、Windows Event Log 等來源。
處理管道（Pipeline）：借鑑 Prometheus 的標籤模型，將原始日誌行轉化為帶有標籤的 entries。
推送機制：透過 HTTP/gRPC 將 entries 批量發送至 Loki 的 distributor 組件。

典型管道由 scrape_configs、pipeline_stages（如 regex、json、timestamp 解析）及 positions 檔案組成，後者記錄每個日誌檔案的讀取位置。

部署¶

在本機（香港數據中心主機）環境中，Promtail 通常以 Docker 容器方式運行。真實 Docker Compose 選段如下：

image: "grafana/promtail:3.6.11"

因原始 Compose 檔案缺失，實際參數可通過 docker container inspect 還原。本機部署實況：

鏡像：grafana/promtail:3.6.11，Grafana 官方 Linux amd64 構建，約 90MB。
容器名稱：promtail
網絡：連接 cf_network bridge 網絡（與 Cloudflare Tunnel 同網段），容器 IP 172.18.0.7/16。
掛載：主機 /var/log 以唯讀方式掛載至容器；配置檔案對應 /etc/promtail/config.yml。
重啟策略：unless-stopped，確保 Docker daemon 啟動時自動運行。

此配置令 Promtail 可持續收集主機 /var/log 及 Docker stdout/stderr 日誌。

配置¶

Promtail 以 YAML 配置。基本範例：

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: system
    static_configs:
      - targets:
          - localhost
        labels:
          job: varlogs
          __path__: /var/log/*log

positions.yaml 記錄讀取偏移量，避免重複推送。多租戶場景可設定 X-Scope-OrgID header；3.6.11 亦支援 relabel_configs、pipeline_stages 中的 loki 處理器，以及透過 tls_config 啟用 TLS 加密傳輸。

維運與監控¶

Promtail 提供 HTTP 端點 /metrics 及 /ready，可接入 Prometheus 或 Grafana 以檢視收集速率、推送失敗次數等指標。常用操作：

健康檢查：curl http://localhost:9080/ready
重載配置：向容器發送 SIGHUP 訊號
故障排除：docker logs promtail 查看代理本身的日誌

香港高流量網絡環境下，需特別留意對外流量。若 Loki 部署在遠端機房，建議保持 gzip 壓縮（預設啟用）以節省頻寬；同時確保日誌檔案權限正確，否則會出現 permission denied。監控層面應注意 BytesReceived、LinesReceived 等 Prometheus 計數器的趨勢。

常見問題¶

Promtail 收到日誌但 Loki 查不到？ 檢查 clients.url 是否指向正確的 Loki 地址及端口，並確認標籤組合未被 Loki 拒絕。
/var/log 權限不足？ 容器內 root 與主機檔案 UID 不一致所致，設定 user: root 或調整掛載權限。
positions 檔案衝突？ 多個實例共享同一 positions 檔案會互相覆蓋，應為每個實例分配獨立檔案路徑。
日誌延遲高？ 預設 batch_wait 為 1 秒，可調低 batch_size 或 batch_wait 減少緩衝時間。
如何過濾敏感資料？ 在 pipeline_stages 中使用 regex 或 replace 操作，於本地端遮蓋金鑰或 token 後才推送。

來源¶

自動生成（2026-08-19 容器覆蓋率補完第二批）

Promtail¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶