[ADP-607] 事件追蹤

概述

本 ADP 旨在定義使用 W3C TraceContext 和 CloudEvents 分布式追蹤擴展來實現事件追蹤的標準方法。

指導原則

當想要實作事件追蹤時：

1. 必須(MUST)使用 W3C TraceContext 標準來實現跨服務的分布式追蹤。

2. 應該(SHOULD)使用 CloudEvents 分布式追蹤擴展來在事件中包含追蹤資訊。

3. 事件生產者必須(MUST)在生成事件時添加追蹤上下文。

4. 事件消費者必須(MUST)在處理事件時傳播追蹤上下文。

5. 追蹤實現應該(SHOULD)對應用程序代碼透明，盡量減少侵入性。

W3C TraceContext

W3C TraceContext 定義了兩個 HTTP 標頭:

1. traceparent: 包含追蹤標識符和父級標識符
2. tracestate: 包含供應商特定的追蹤資訊

示例:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01
tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

CloudEvents 分布式追蹤擴展

CloudEvents 定義了兩個擴展屬性來支持分布式追蹤:

1. traceparent: 對應 W3C TraceContext 的 traceparent
2. tracestate: 對應 W3C TraceContext 的 tracestate

示例 CloudEvent:

{
    "specversion" : "1.0",
    "type" : "com.example.someevent",
    "source" : "/mycontext",
    "id" : "C234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "traceparent" : "00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01",
    "tracestate" : "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE",
    "data" : {
        "message" : "Hello, World!"
    }
}

實施建議

1. 使用支持 W3C TraceContext 的追蹤庫或框架。

2. 在服務間傳遞事件時，確保正確傳播 traceparent 和 tracestate。

3. 在日誌記錄中包含追蹤 ID，以便於關聯日誌和追蹤。

4. 考慮實施採樣策略，以控制追蹤數據的數量。

5. 使用分布式追蹤可視化工具來分析和展示追蹤數據。

安全考慮

1. 確保追蹤資訊不包含敏感數據。

2. 實施適當的訪問控制，限制對追蹤數據的訪問。

3. 考慮在生產環境中使用採樣來減少追蹤數據的數量，從而降低潛在的安全風險。

相關 ADP

• ADP-602 CloudEvents
• ADP-606 事件測試標記

參考資料

• W3C Trace Context
• CloudEvents 分布式追蹤擴展