追蹤記錄內容

追蹤記錄內容和內容傳播是作業和服務之間傳遞中繼資料的機制，Cloud Trace 可將個別時距連結在一起，形成完整的端對端分散式追蹤記錄。

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

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

Cloud 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 Cloud 服務新增內容傳播支援功能，請使用 Google Issue Tracker。

在應用程式中傳播脈絡

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

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

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

後續步驟