結構化日誌是什麼?欄位設計、事件時間與查詢

定義日誌欄位的型別和事件時間,將舊格式正規化,再依服務篩選及彙總錯誤。

最佳實務
將不同記錄分送到各條軌道的鐵路調度場插圖

結帳錯誤變多時,搜尋「connection refused」可能會找到好幾個服務的訊息。接下來要知道的是哪個服務寫下這筆日誌、錯誤代碼是否相同,以及操作經過多久才失敗。

結構化日誌把這些資訊各自放進欄位。訊息仍然可讀,後端解析並對應欄位後,也能依服務分組或依耗時篩選。JSON 是常見的編碼格式。若只是把一整行文字包進 JSON,其他細節還是得從訊息中擷取。

先做一筆可以查詢的事件

以下是正規化後的示範資料,代表一次結帳失敗。

{
  "time": "2026-08-25T08:55:01Z",
  "status": "error",
  "message": "database connection failed",
  "service": "order",
  "event": "checkout.failed",
  "error_code": "DB_CONNECT_ERROR",
  "duration_ms": 1200,
  "trace_id": "00000000000000000000000000000001"
}

訊息讓人了解發生了什麼事,穩定的 event 和 error_code 則讓查詢不受文字修改影響。duration_ms 是數值。若來源送出字串 "1200",應先在接收時確認或轉換型別,再用 duration_ms > 900 這類數值條件。欄位規格要定義意義、型別、單位和缺值處理。保留缺值,就能與實際量到零區分開來。

事件發生時間和收集器觀察到事件的時間要分開。若緩衝使資料晚兩分鐘才送達,只要原本的發生時間有效,仍可查到故障當下的記錄。想追查接收延遲,可以另外保留觀察時間。OpenTelemetry 分別稱這兩個欄位為 Timestamp 和 ObservedTimestamp。 OpenTelemetry 日誌資料模型(英文)

在來源端輸出結構化記錄

選擇收集器能穩定解析的編碼,再設定日誌程式庫。JSON 能表達不同型別和巢狀資料;只有簡單鍵值對時,Logfmt 也是一種選擇。開發與正式環境若採不同格式,要驗證兩條收集路徑。

以下用 Go 1.21 以上版本的標準程式庫示範。儲存成 log.go,執行 go run log.go。

package main

import (
	"log/slog"
	"os"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	logger.Error("database connection failed",
		"service", "order",
		"event", "checkout.failed",
		"error_code", "DB_CONNECT_ERROR",
		"duration_ms", 1200,
	)
}

JSON handler 會在同一行記錄中輸出 time、level、msg 和事件欄位。時間取自實際執行時刻,這支獨立程式也沒有作用中的追蹤。若要對齊第一筆資料的欄位,接收時可將 level 和 msg 對應到 status 和 message,並統一等級值。 Go slog 文件(英文)

基礎設施元件也要確認相同的條件。PostgreSQL 15 以上可以在 log_destination 指定 jsonlog,前提是啟用在伺服器啟動時生效的 logging_collector。切換格式前,先核對檔案位置、輪替方式及收集設定。 PostgreSQL 日誌設定(英文)

接收時整理仍在使用的舊格式

難以修改的服務如果仍輸出固定格式的文字,可用觀測雲 Pipeline(簡體中文)擷取事件時間、等級和業務欄位。拿正常、缺欄位及格式錯誤的記錄各試一次。在資料政策允許的範圍保留調查所需的原文,並留下可辨識的解析失敗狀態。設定作用於通過 Pipeline 的資料。已儲存的記錄需要另行遷移,或用兼顧兩種格式的查詢。

先統一需要一起排障的服務所用的欄位與型別。檢視器能展開巢狀 JSON,不代表其中每個欄位都可直接聚合,可能仍需擷取或對應。透過日誌索引規則管理資料的去向和保留期。 觀測雲日誌索引(簡體中文)

用正規化欄位查詢

以下 DQL 假設收集器已設定 source=checkout,將正規化日誌送入 default 索引,並把 time 解析為事件發生時間。

L("default")::checkout:(count(*) AS error_events)
{ `status` = "error" AND `event` = "checkout.failed" }
[1787648100000:1787648400000] BY service

此處查詢 2026 年 8 月 25 日 08:55 至 09:00 UTC。實際執行時,要換成自己設定的來源、索引和時間區間。若只有前面的示範記錄符合條件,order 的結果就是 1。一次請求重試可能留下多筆日誌,也可能有失敗請求沒寫出這類事件,因此結果是錯誤日誌筆數。要算請求錯誤率,須使用具有明確請求總數的量測。 觀測雲 DQL 文件(簡體中文)

在觀測雲日誌檢視器(簡體中文)核對擷取出的欄位,用索引支援的欄位縮小範圍。群集分析可把所選範圍內相似的訊息歸為一組,方便挑出要細查的記錄。若要看總數或趨勢,請明確限定範圍再計數;告警則由監控器設定。

保留能把資料串起來的欄位

請求有作用中的追蹤上下文時,記錄實際的追蹤 ID。需要區分特定操作時,再一起保留 span ID。應用程式的請求 ID 和追蹤 ID 是不同的識別碼。觀測雲追蹤詳情(簡體中文)預設用 trace_id 找整條追蹤的關聯日誌,並用 service、env、version 等欄位協助選取日誌索引。追蹤和日誌都要已收集、仍在保留期限內,且有權查閱。

讓訊息保持可讀,只加上確實要用於調查的資訊,憑證與不必要的個人資料留在日誌之外。擴大欄位規格前,在實際負載下衡量序列化、解析和儲存開銷。先驗證同一個故障能否在正確的發生時段,依欄位找到需要比對的服務記錄。

日誌、指標與追蹤的差異 · 使用 Go slog 輸出結構化日誌(英文)

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

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

立即開始

选择观测云版本

代码托管平台