結構化記錄指南

結構化記錄將事件記錄為命名欄位，而不是將每個詳細資訊放在句子中。諸如 checkout failed for account 42 after 812 ms 之類的訊息是可讀的，但 SQL 必須先解析它，然後才能對故障進行分組或計算延遲。結構化事件分別儲存event_name、account_id、status、error_type和latency_ms。

從一個問題開始

在選擇欄位之前寫下操作或產品問題。 “哪個結帳步驟最常失敗？”意味著穩定的步驟名稱、狀態、錯誤類別和時間戳。 “哪些客戶受到影響？”還需要一個安全的帳戶識別符號。沒有可能的過濾器、分組、計算或除錯用途的領域可能是噪音。

優先選擇有意義的邊界內的一個事件：請求完成、作業用盡重試、Webhook 進行重複資料刪除或使用者達到啟用里程碑。避免為同一工作流程的每個分支發出不同的資料表。一致的 status 場使成功和失敗具有可比性。

await telemetry.log("checkout_completed", {
  checkout_version: "v2",
  account_id: account.id,
  status: "failed",
  error_type: "payment_declined",
  latency_ms: 812,
  attempt: 1,
});

保持合約穩定

使用 snake_case 名稱、顯式單位（例如 _ms 和 _bytes）以及 UTC 時間戳。當您需要可靠的分組維度時，請儲存 payment_declined 等類別，而不是完整的例外文字。保持事件中的識別符號一致，以便可以透過系統追蹤請求、帳戶、發布或作業。

不要默默地將欄位從數字更改為字串。如果其含義發生變化，請新增版本欄位或新的事件契約。 事件架構設計指南 更詳細地解釋了命名、所有權和演變。

保護敏感資料

將每個新欄位視為可能出現在查詢結果、儀表板或匯出中的資料。請勿傳送憑據、cookie、授權標頭、完整請求正文、付款詳細資訊或原始提示。與電子郵件和自由格式的使用者內容相比，更喜歡內部識別符號和受控類別。在活動施工邊界應用許可名單；攝入後的脫敏是一種後備措施，而不是主要控制措施。

驗證事件

使用合成資料練習成功、失敗、超時和重試分支。檢查結果資料表，確認欄位型別，並執行引發事件的查詢。然後，僅在結果與業務定義匹配後才建立視覺化或警示。

繼續使用 結構化日誌管理指南、典型的廣泛事件、結構化事件與文字日誌，或從 SQL配方庫 複製完整查詢。