規範化寬事件

規範的廣泛事件描述了一個已完成的工作單元以及解釋其結果所需的上下文。應用程式不是根據斷開連線的“開始”、“資料庫呼叫”和“完成”訊息重建請求，而是發出一個請求結果，其中包含其路由、帳戶、發布、持續時間、狀態和分類的故障上下文。

此模式也稱為規範日誌行、結構化事件或寬事件。 Stripe 將規範日誌行描述為一種在一個地方收集請求的重要上下文的方法。 Honeycomb 使用上下文豐富的結構化事件作為可觀測性的基礎。 OpenTelemetry 日誌資料模型 提供了可以將日誌與追蹤關聯起來的標準表示形式。名稱和傳輸方式不同，但有用的設計問題是相同的：一條記錄​​能否在不搜尋敘述的情況下解釋有意義的結果？

“廣”是指活動可以承載很多有目的的領域。這並不意味著複製記憶體中的每個物件。

從事件粒度開始

事件粒度是由一行表示的事物。在選擇欄位之前將其寫下來。有用的穀物包括：

• 一個 API 請求達到了最終結果
• 一項後台作業已完成或已耗盡重試次數
• 一次 Webhook 傳送已被處理、拒絕或重複資料刪除
• 一個代理執行已完成、失敗或達到安全限制
• 一個帳戶達到啟用、計費或保留里程碑
• 使用有界指紋完成一次資料庫操作

避免在一張桌子上混合穀物。如果一行有時意味著一次請求嘗試，有時意味著所有重試中的邏輯請求，則計數和速率就會變得不明確。當需要兩個檢視時，請使用單獨的 attempt_number 或單獨的嘗試事件。

在操作的生命週期中建置規範事件，並在知道最終結果時發出它：

const outcome = {
  request_id: requestId,
  route_template: "/api/projects/:id/sync",
  method: "POST",
  team_id: teamId,
  release: process.env.APP_RELEASE,
  environment: "production",
  started_at: new Date().toISOString(),
};

try {
  await syncProject();
  await telemetry.log("api_request_completed", {
    ...outcome,
    status: "success",
    status_code: 200,
    latency_ms: Math.round(performance.now() - startedAt),
  });
} catch (error) {
  await telemetry.log("api_request_completed", {
    ...outcome,
    status: "failed",
    status_code: statusFor(error),
    error_type: classifyError(error),
    latency_ms: Math.round(performance.now() - startedAt),
  });
  throw error;
}

儀器交付不應將成功的請求變成失敗的請求。使用有界超時，單獨觀察傳遞失敗，並明確決定哪些關鍵事件需要持久佇列。

使用欄位分類法

有用的規範事件通常來自六個欄位組：

對要分組的欄位使用受控類別。 error_type: "dependency_timeout" 比原始異常訊息更可靠。在名稱中使用明確的單位：_ms、_bytes、_usd 和 _count。使用規範化的路由範本而不是原始 URL。

請求 ID、帳戶 ID 和追蹤 ID 等識別符號是高基數。這通常是正確的：即使圖表維度較差，它們對於過濾和關聯也很有價值。僅當調查收益證明隱私、儲存和查詢成本合理時才保留它們。參見 高基數字段。

三種實用的活動形狀

API 請求事件應將分母和結果放在一起：

{
  "event_name": "api_request_completed",
  "request_id": "req_7d91",
  "route_template": "/api/projects/:id/sync",
  "method": "POST",
  "status_code": 503,
  "status": "failed",
  "error_type": "dependency_timeout",
  "latency_ms": 8420,
  "release": "2026.07.4",
  "schema_version": 2
}

後台作業事件應該使重試粒度明確：

{
  "event_name": "job_completed",
  "job_id": "job_82f1",
  "job_name": "sync_billing_account",
  "queue_name": "billing",
  "status": "failed",
  "terminal": true,
  "attempt_number": 4,
  "queue_wait_ms": 1820,
  "duration_ms": 9612,
  "error_type": "provider_timeout"
}

代理執行事件應將操作結果與敏感內容分開：

{
  "event_name": "agent_run_completed",
  "run_id": "run_28bd",
  "workflow": "support_resolution",
  "agent_name": "support_agent",
  "model": "approved_model_alias",
  "status": "success",
  "tool_call_count": 3,
  "retry_count": 1,
  "duration_ms": 4820,
  "accepted": true,
  "prompt_version": "support-v4"
}

預設情況下，不記錄原始提示、完成、工具參數或檢索的文件。結果事件可以回答數量、可靠性、成本和接受度問題，而無需保留客戶內容。

縮小隱私邊界

將每個欄位視為可能出現在查詢結果、儀表板、匯出或支援工作流程中的資料。在活動建置時使用許可名單。請勿包含授權標頭、cookie、憑據、連線字串、請求或回應正文、webhook 負載、付款詳細資訊或不受限制的客戶內容。

優先使用內部帳戶識別符號而非電子郵件地址，優先使用路由範本而非完整 URL，優先選擇受控錯誤類別而非異常文字。對個人資料進行雜湊處理並不會自動使其安全；穩定的雜湊值仍然可以是可連結的識別符號。 事件追蹤計劃 中的文件所有權、目的、保留和刪除期望。

關聯而不是重複

規範的廣泛事件補充了指標、追蹤和詳細的診斷日誌。它不需要複製它們。

• 指標對於聚合服務執行狀況和基礎設施警示仍然有效。
• 痕跡顯示跨跨度的時間和因果關係。
• 診斷日誌保留本地詳細資訊，例如堆疊追蹤。
• 規範事件保留已完成的應用程式或業務成果。

當更深入的證據存在於其他地方時，請附上經批准的 trace_id 或相關 ID。回應者可以從失敗的結果行移動到其追蹤，而無需將跨度瀑布或堆疊追蹤複製到事件中。 日誌、指標和追蹤指南 更詳細地涵蓋了邊界。

在啟動前規劃架構演變

為該事件提供一個所有者和一個 schema_version。在將可選欄位設定為必填欄位之前新增它們。切勿默默地將數字欄位更改為字串或重複使用欄位名稱以實現不同的含義。在遷移期間，支援 SQL 中的兩個架構版本，直到生產者和歷史視窗收斂。

保持受控類別的界限。如果出現新的錯誤類別，請檢查它是否更改了儀表板、警示或 Runbook。如果應用程式升級重新命名路由或工作流程，請與實現名稱分開保留穩定的分析名稱。

模式演化指南 和 資料型別和可空性 解釋了這些推出選擇。

基於決策而不是方便的樣本

不要抽取罕見故障、終端作業結果、計費更改、安全操作或用於精確協調的事件。大批次成功請求可能是確定性或基於速率取樣的候選者，但如果下游分析需要估計總數，則保留取樣決策和權重。

將儲存的儲存空間與丟失的問題進行比較。取樣可以保留延遲分佈，同時使精確的帳戶影響計數變得不可能。 事件取樣指南描述了安全和不安全的情況。

使用 SQL 驗證事件

當事件以可防禦的 SQL 回答其預期問題時，而不是當它包含最多欄位時，事件就完成了。在非生產環境中演練成功、失敗、重試、超時、重複傳遞、空欄位和遲到路徑。在建置儀表板之前檢查儲存的架構。

對於 API 結果事件，從計數和分母開始：

SELECT
  route_template,
  COUNT(*) AS requests,
  SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failures,
  100.0 * SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS failure_rate_pct,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  AND environment = 'production'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY failure_rate_pct DESC;

將數量與速率放在一起，在比較期間時排除不完整的時間段，並說明重試是嘗試還是邏輯結果。為操作上變得重要的查詢儲存確定性裝置和預期結果。 CI 指南中的儀器測試 展示瞭如何防止合約漂移。

一次遷移一個工作流程

不要替換整個日誌流。選擇一個重複決策，在現有遙測資料旁邊發出其規範事件，並在同一個關閉的 UTC 視窗中雙重執行新舊答案。研究重試處理、路由規範化、時間戳、空值和排除方面的差異。僅在其所有者接受語義後，才將新查詢提升到儀表板或警示。

實際路徑是：

1. 定義事件粒度和決策。
2. 編寫允許的現場合約。
3. 儀器終端結果。
4. 驗證交付和架構。
5. 使用裝置測試查詢。
6. 雙執行報告或警示。
7. 僅退休多餘的消費者。

繼續使用 結構化日誌管理指南、結構化事件與文字日誌 或完整的 遷移指南。