OpenTelemetry 上下文傳播與 traceparent
了解 traceparent、tracestate 和 Baggage 的作用,並檢查 HTTP、gRPC 與訊息佇列在哪一段失去追蹤關聯。
結帳服務的 Span 看得到,庫存請求卻出現在另一個 Trace ID 下。即使兩個服務都能正常匯出 Span,也會遇到這種情況。先確認庫存服務是否從結帳服務送來的請求取出了正確的上下文。
OpenTelemetry 上下文傳播會將追蹤識別資訊帶過服務邊界。接收端在建立 Span 前擷取上下文,發送端則在下一次呼叫前注入當前 Span 的上下文。兩端配合,事後才能沿著父子關係查找問題。
跨服務傳的是哪些資訊
SpanContext 包含 Trace ID、目前的 Span ID、追蹤旗標和追蹤狀態。接收端從遠端上下文建立子 Span 時,會沿用 Trace ID,取得新的 Span ID,並將發送端的 Span 記為父節點。開始與結束時間各自記在 Span 內。SDK 會為擷取到的 Span 上下文加上遠端標記,這個標記留在 SDK 的上下文中。OpenTelemetry SpanContext API(英文)
Baggage 由獨立的傳播器處理,可攜帶應用程式自訂的鍵值。這些值不會自動成為 Span 屬性。例如需要按發布批次查詢時,可以在應用程式內明確把允許送出的批次值複製到 Span 屬性。
讀懂 traceparent 標頭
W3C Trace Context Level 1 建議標準(英文)定義版本 00 的格式為 version-trace-id-parent-id-trace-flags。以下是一個收到的 HTTP 標頭。
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
| 欄位 | 接收端如何解讀 |
|---|---|
00 |
格式版本。ff 無效。遇到更新版本時,Level 1 的做法是嘗試讀取可辨識的前綴。 |
4bf92f3577b34da6a3ce929d0e0e4736 |
Trace ID。由 32 個小寫十六進位字元組成,不可全為零。 |
00f067aa0ba902b7 |
發送端傳來的 Span ID。由 16 個小寫十六進位字元組成,不可全為零。 |
01 |
一個位元組的旗標。最低位元 0x01 是取樣旗標,可供下游判斷。資料最後能否查到,還取決於匯出和保存等環節。 |
選用的 tracestate 標頭可隨有效的 traceparent 傳送有順序的廠商鍵值。檢查兩端是否使用相容的傳播器。支援 OTEL_PROPAGATORS 的實作,其規格預設值是 tracecontext,baggage。手動整合 SDK 時,請明確設定要使用的傳播器。OpenTelemetry 傳播器 API(英文) · SDK 環境變數(英文)
HTTP、gRPC 和訊息佇列怎麼傳
HTTP。 用戶端的埋點將上下文注入請求標頭,伺服器中介軟體則在建立伺服器 Span 前擷取上下文。建立 Span 後,把傳回的新上下文帶到下一次呼叫。如果沿用較早的上下文,標頭格式即使正確,也可能指到錯誤的父節點。
gRPC。 用戶端與伺服器的埋點使用 RPC 中繼資料,其傳輸走 HTTP/2 標頭。呼叫經過攔截器或代理時,要在接收端檢查中繼資料。gRPC 中繼資料指南(英文)
訊息佇列。 生產者把建立訊息時的上下文放進載體,例如 Kafka 記錄的標頭。消費者可逐筆擷取批次訊息的上下文,再用處理 Span 連結到各筆訊息。每個 Span 只有一個父節點,選定其中一筆訊息的建立 Span 為父節點,便無法表達與其他訊息的關係。OpenTelemetry 的訊息語意慣例預設採用 Span Link。處理單筆訊息時,埋點實作也可採用該訊息的建立上下文作為父節點。如果處理流程已在 HTTP 處理常式等現有 Span 之下,可保留當前 Span 為父節點,再連結到建立訊息的上下文。OpenTelemetry 訊息 Span 語意慣例(英文)
自訂協定。 將訊息欄位接成傳播器可讀寫的載體,使用注入和擷取操作。接收端用傳回的上下文建立 Span。
找出斷在哪一段
送出一筆測試請求。每經過一次同步呼叫,對照送出的 traceparent 和下一個服務擷取到的上下文,檢查接收端的伺服器 Span 是否沿用同一個 Trace ID,並指向發送端的 Span。經過佇列時,除了父節點也要看 Link。以 Link 關聯的消費端可以屬於另一條 Trace。
若 ID 在預期外改變,檢查閘道器是否移除標頭、用戶端是否有埋點,以及非同步工作是否丟了上下文。對外入口也可能基於信任邊界的設定刻意新建 Trace。若 ID 都對得上卻仍少了一個 Span,再檢查記錄、取樣、匯出,以及後端查詢的時間區間和篩選條件。
在觀測雲核對追蹤與日誌
經由 DataKit OTLP 接收端(簡體中文)送出 Span 後,找出測試用的 Trace,確認同步呼叫的父 Span ID。非同步處理的 Link 則可在埋點輸出裡核對。
若要查看同一請求的日誌,應讓應用程式寫入目前的 Trace ID,再設定 APM 關聯日誌(簡體中文)。若日誌已經有 Trace ID,卻查不到對應的 Span,可以從那段呼叫的取樣和匯出查起。
限制 Baggage 的傳送範圍
確認各條外送路徑會執行哪些傳播器。已埋點的用戶端呼叫第三方時,Baggage 可能跟著送到組織之外。只放行需要傳送的鍵值,排除憑證和個人資料,並驗證接收的值。存取權限應由服務身分驗證和應用程式授權來決定。W3C Baggage(英文)
延伸閱讀 · 什麼是 OpenTelemetry? · OpenTelemetry 取樣(英文)
