追蹤記錄內容

本文將簡要說明「結構定義」(指的是狀態) 和「結構定義傳播」(指的是將狀態資訊傳遞至子項作業)。對於分散式追蹤，必須將追蹤 ID 和正在處理的跨度的 ID 傳遞至子操作。

子項作業會建立時距並設定下列欄位：

  • 跨度 ID：子作業的專屬 ID。如果執行相同的作業多次，則該作業會有多個跨度，每個跨度都有專屬 ID。
  • 追蹤 ID：發生這項特定整體作業的端對端作業專屬 ID。這個欄位的值由父項提供。
  • 父項時距 ID：父項時距的專屬 ID。這個欄位的值由父項提供。根區段的 ID 為 null。

追蹤 ID、跨度 ID 和父項跨度 ID 欄位的值可讓分散式追蹤系統正確連結跨度，形成追蹤記錄。舉例來說，Cloud Trace 會將時距儲存在存放區中，並使用這些 ID 欄位來識別哪些時距組成追蹤記錄。

脈絡可能包含其他狀態資訊，這些資訊可用於分散式追蹤。舉例來說，全球資訊網協會 (W3C) 標準會提供父項範圍是否已取樣的相關資訊。

用於傳播情境的通訊協定

以下各節將說明特定要求通訊協定如何傳播內容。

HTTP 要求

針對 HTTP 要求，通常會透過 traceparent 和 tracestate 等 HTTP 標頭來完成內容傳播作業，這些標頭已由 W3C 標準化。支援追蹤內容傳播作業的Google Cloud 服務通常會同時支援 traceparent 和舊版 X-Cloud-Trace-Context 標頭。

建議您盡可能在應用程式中使用 traceparent 標頭。應用程式可能需要使用舊版 X-Cloud-Trace-Context 標頭，或可能需要支援以其他格式接收追蹤記錄結構。

如果您的應用程式只支援 X-Cloud-Trace-Context 標頭，建議您更新應用程式，以便支援 traceparent 標頭並將其設為優先。應用程式可以繼續使用 X-Cloud-Trace-Context 標頭做為備用解決方案。

下表摘要列出這兩個標頭之間的一些重要差異：

屬性 traceparent
標題		 X-Cloud-Trace-Context
header
分隔符 連字號 (-) 正斜線 (/) 和分號 (;)
時距 ID
表示法		 十六進位數 小數

舊版 X-Cloud-Trace-Context 標頭

Google Cloud 使用的 X-Cloud-Trace-Context 標頭早於 W3C 規格。為了回溯相容性，某些 Google Cloud 服務會繼續接受、產生及傳播 X-Cloud-Trace-Context 標頭。不過，這些系統可能也會支援 traceparent 標頭。

X-Cloud-Trace-Context 標頭的格式如下：

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

標頭欄位的定義如下：

  • TRACE_ID 是一個表示 128 位元數的 32 字元十六進位值。
  • SPAN_ID 是無號時距 ID 的 64 位元十進制表示法。
  • OPTIONS 支援 0 (未取樣父項) 和 1 (已取樣父項)。

gRPC 要求

針對 gRPC 要求，您可以使用 gRPC 中繼資料來完成情境傳播作業，這項作業會在 HTTP 標頭上實作。gRPC 應用程式可能會使用 traceparent 標頭或名為 grpc-trace-bin 的中繼資料情境鍵。

對於您擁有的元件，建議您使用 traceparent 標頭。

Google Cloud 服務的內容傳播

Google Cloud 服務可能會在要求處理程序中擔任發起端或中介。舉例來說，下列服務已知會參與處理要求：

追蹤記錄內容啟動和傳播功能的支援情形，取決於特定 Google Cloud 服務。如要要求 Google Cloud 服務新增對內容傳播功能的支援，請使用 Google Issue Tracker。

應用程式中的情境傳播

部分檢測程式庫 (例如 OpenTelemetry) 可以傳播 context 物件，其中包含追蹤所需的資料。如需支援追蹤的 OpenTelemetry 程式庫清單，請參閱「語言 API 與 SDK」。

如果您使用開放原始碼程式庫，請判斷是否可使用內容傳播功能，以及是否需要設定。舉例來說，如果您使用 OpenTelemetry 檢測 Go 應用程式，則應用程式應呼叫 SetTextMapPropagator，以便設定使用 W3C traceparent 格式的內容。如需範例，請參閱 Go 檢測範例。

如果沒有合適的檢測程式庫，您必須確保應用程式會將追蹤內容傳播至子項作業。

後續步驟