追蹤記錄內容

追蹤記錄相關資訊和結構定義傳播功能可讓分散式應用程式在標頭或中繼資料中，跨服務傳遞要求 ID。Cloud Trace 會使用這個共用內容，將個別 span 連結至完整的分散式追蹤記錄、重建執行階層，以及評估是否對要求進行取樣。

脈絡傳播的運作方式

應用程式處理要求並呼叫下游服務時，會使用要求標頭或中繼資料傳遞 ID (例如追蹤 ID、父項時距 ID 和取樣狀態)。子項作業會使用這個內容，在新的範圍中填入下列欄位：

  • 時距 ID：子項作業的專屬 ID。如果作業執行多次，每次叫用都會產生具有不同時距 ID 的時距。
  • 追蹤 ID：整體端對端要求的專屬 ID，由父項提供。
  • 父項時距 ID：叫用父項時距的專屬 ID。這個欄位null適用於根範圍。

Trace 會使用這些共用 ID 重建執行階層，並測量所有參與服務的延遲時間。背景資訊也可以包含其他狀態資訊，例如要求是否經過取樣。

情境傳播通訊協定

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

HTTP 要求

對於 HTTP 要求，內容傳播通常是透過 HTTP 標頭 (例如 traceparent 和 tracestate 標頭) 完成，這些標頭已由 W3C 標準化。traceparent 標頭包含可專屬識別要求的 ID。相較之下，tracestate 標頭為選用項目，內含供應商專屬中繼資料。

traceparent 標頭的格式如下：

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

traceparent 標頭的欄位定義如下：

  • VERSION 是標頭版本。必須為 00。
  • TRACE_ID 是一個表示 128 位元數的 32 字元十六進位值。
  • PARENT_SPAN_ID 是 16 個字元的十六進位值，用於識別父項範圍。
  • TRACE_FLAGS 是 2 個字元的十六進位值，用於識別父項的取樣決策。如果父項對範圍進行取樣，則值為 01。

Google Cloud 支援追蹤記錄相關資訊傳播的服務通常會同時支援 traceparent 和舊版 X-Cloud-Trace-Context 標頭。

請盡可能在應用程式中使用 traceparent 標頭。如果應用程式僅支援 X-Cloud-Trace-Context 標頭，建議您更新應用程式，支援並優先使用 traceparent 標頭。您的應用程式可以繼續使用 X-Cloud-Trace-Context 標頭做為備用解決方案。

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

屬性 traceparent
標頭		 X-Cloud-Trace-Context
標頭
分隔符 連字號 (-) 正斜線 (/) 和半形分號 (;)
時距 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 Issue Tracker。 Google Cloud

在應用程式中傳播脈絡

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

如果您使用開放原始碼程式庫，請判斷是否提供脈絡傳播功能，以及是否需要設定。舉例來說，如果您使用 OpenTelemetry 檢測 Go 應用程式，應用程式就應呼叫 SetTextMapPropagator，將環境設定為使用 W3C traceparent 格式。如需範例，請參閱「Go 檢測點範例」。

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

後續步驟