追蹤資料的儲存空間結構

本文說明追蹤記錄範圍的儲存格式。資料格式通常與OpenTelemetry OTLP 通訊協定定義的 proto 檔案一致。不過，欄位可能會先從 OpenTelemetry 專屬資料類型轉換為 JSON 資料類型，再進行儲存。

Telemetry API 使用 OpenTelemetry OTLP 通訊協定。這項通訊協定依賴 trace_service.proto 和 trace.proto 檔案。如要瞭解欄位限制，請參閱「Telemetry API 限制」。

Cloud Trace API 不會使用 OpenTelemetry OTLP 通訊協定，而是定義專屬的資料格式。透過這個 API 傳送至 Google Cloud 專案的追蹤資料，會轉換為本文所述的格式。不過，Cloud Trace API 仍有相關限制。

範圍儲存格式

欄位	說明
trace_id	string 追蹤記錄的全域專屬 ID。這個 ID 是以 16 位元組十六進位字串格式表示的 128 位元數值。例如： 382d4f4c6b7bb2f4a972559d9085001d。 如要進一步瞭解這個 ID，請參閱 W3C trace-id。 零值無效。 視覺化和分析工具會使用 trace_id 識別與追蹤記錄相關聯的範圍。因此，每個端對端作業都必須有專屬 ID。請勿重複使用追蹤 ID。
span_id	string 這是必要旗標， span 的 ID。 在追蹤記錄中不得重複。 這個 ID 是 64 位元的數值，格式為 8 位元組的十六進位字串。例如：9046a5b9f7c12500。 零值無效。
trace_state	string 這個欄位對應至 tracestate 標頭，如 W3C 追蹤內容所定義。這個標頭包含設定資訊，當應用程式經過檢測來收集追蹤記錄資料時，這些資訊會納入要求中。 舉例來說，應用程式可以指定機率取樣設定，也可以納入廠商專屬內容。 OpenTelemetry 程式庫會在產生範圍時，自動記錄 tracestate 標頭的值。
parent_span_id	string 選用。識別叫用這個範圍的作業。 「根」時距的父項時距 ID 設為空值。 跨度之間的父項子項關係，會用於建構樹狀結構。
name	string 這是必要旗標，執行的作業名稱。 這個名稱可以是方法名稱，也可以是其他每個呼叫的網站名稱。 對於相同的可執行檔和端點，使用一致的名稱可讓您更輕鬆地關聯跨追蹤範圍。如需最佳做法，請參閱「如何命名範圍」。 系統會清除跨度名稱，並顯示在 Google Cloud 控制台中。
kind	integer 指定系統中發生作業的位置。 這個值對應至 OpenTelemetry：Span Kind 列舉： 值 OpenTelemetry 列舉 0 SPAN_KIND_UNSPECIFIED 1 SPAN_KIND_INTERNAL 2 SPAN_KIND_SERVER 3 SPAN_KIND_CLIENT 4 SPAN_KIND_PRODUCER 5 SPAN_KIND_CONSUMER
start_time	Timestamp 這是必要旗標，時間範圍的開始時間，精確至奈秒。
start_time_unix_nano	integer 開始時間 (以奈秒為單位)，自 UNIX Epoch 紀元時間開始算起。
end_time	Timestamp 這是必要旗標，時間範圍的結束時間，精確至奈秒。
end_time_unix_nano	integer 結束時間 (以奈秒為單位)，根據 UNIX 紀元計算。
receive_time	Timestamp 這是必要旗標，接收時間範圍，精確度為奈秒。
receive_time_unix_nano	integer 結束時間 (以奈秒為單位)，自 UNIX 紀元開始算起。
duration_unix_nano	integer 時間長度 (以奈秒為單位)。
attributes	JSON type 每個屬性都是鍵/值組合。 可用的屬性取決於追蹤資料。屬性結構遵循 OpenTelemetry 標準。詳情請參閱「OpenTelemetry：屬性」。 OpenTelemetry 會指定屬性的語意慣例。如要瞭解這些慣例，請參閱「追蹤語意慣例」。 屬性範例如下： "yourcompany.your.own.key": "your own value" "network.protocol.name": "http" "network.protocol.version": "1.1" "http.response.status_code": "200" "network.peer.address": "REDACTED"
dropped_attributes_count	integer 遭捨棄的屬性數量。 屬性鍵過長或屬性過多，都可能導致屬性遭到捨棄。如果這個值為零，表示沒有任何屬性遭到捨棄。 這個值可能由用戶端檢測或應用程式設定。伺服器可以遞增這個值。
events	record，含有重複欄位 時間點事件。每個事件都包含下列欄位。 欄位 說明 time Timestamp time_unix_nano integer name string 這是必要旗標，活動名稱。 attributes JSON type 每個屬性都是鍵/值組合。 可用的屬性取決於追蹤資料。屬性結構遵循 OpenTelemetry 標準。詳情請參閱「OpenTelemetry：屬性」。 dropped_attributes_count integer 遭捨棄的屬性數量。 屬性鍵過長或屬性過多，都可能導致屬性遭到捨棄。如果這個值為零，表示沒有任何屬性遭到捨棄。 這個值可能由用戶端檢測或應用程式設定。伺服器可以遞增這個值。
dropped_events_count	integer 遭捨棄的事件數。如果事件過多，系統可能會捨棄部分事件。如果這個值為零，表示沒有任何事件遭到捨棄。
links	record，含有重複欄位 與範圍相關聯的連結。連結是從這個範圍參照到相同或不同追蹤記錄中的另一個範圍。 連結提供一種機制，可將一個追蹤記錄中的範圍與另一個追蹤記錄中的範圍建立關聯。舉例來說，假設某項作業導致發生非同步作業。在此情境中，有兩個追蹤記錄，一個用於原始作業，另一個用於非同步作業。您可以使用連結來關聯這些追蹤記錄中的範圍。 每個連結都包含下列欄位。 欄位 說明 trace_id string 必填。 span_id string 必填。 trace_state string attributes JSON type 每個屬性都是鍵/值組合。 可用的屬性取決於追蹤資料。屬性結構遵循 OpenTelemetry 標準。詳情請參閱「OpenTelemetry：屬性」。 dropped_attributes_count integer 遭捨棄的屬性數量。 屬性鍵過長或屬性過多，都可能導致屬性遭到捨棄。如果這個值為零，表示沒有任何屬性遭到捨棄。 這個值可能由用戶端檢測或應用程式設定。伺服器可以遞增這個值。
dropped_links_count	integer 遭捨棄的連結數量。連結過多時，系統可能會捨棄部分連結。如果這個值為零，表示沒有捨棄任何連結。
status	record (不含重複欄位) 這個欄位會記錄時間範圍的完成狀態。 code 子欄位的值對應至 OpenTelemetry：Span Status 列舉： 值 OpenTelemetry 列舉 說明 0 UNSET 順利完成作業。 1 OK 作業已由專人標示為無錯誤。 2 ERROR 作業完成，但發生錯誤。舉例來說，如果用戶端範圍的狀態為 400 (BAD REQUEST)，這個欄位就會設為 ERROR。 格式化字串的 message 子欄位包含錯誤資訊。
resource	record (不含重複欄位) 這個欄位會指出遙測資料的收集來源，或是遙測資料所指的基礎架構或主機系統。舉例來說，假設應用程式在 Google Kubernetes Engine 上執行，這項資源的屬性可能包括程序名稱和命名空間。 這個欄位包含下列子欄位： 欄位 說明 attributes JSON type 每個屬性都是鍵/值組合。 可用的屬性取決於追蹤資料。屬性結構遵循 OpenTelemetry 標準。詳情請參閱「OpenTelemetry：屬性」。 以下是資源屬性的範例： cloud.account.id: "my-project" cloud.platform: "gcp_kubernetes_engine" cloud.provider: "gcp" cloud.region: "us-central1" gcp.project_id: "my-project" host.id: "REDACTED" host.name: "gke-otel-demo" k8s.cluster.name: "otel-demo" k8s.deployment.name: "otel-demo-frontendproxy" dropped_attributes_count integer 遭捨棄的屬性數量。 屬性鍵過長或屬性過多，都可能導致屬性遭到捨棄。如果這個值為零，表示沒有任何屬性遭到捨棄。 這個值可能由用戶端檢測或應用程式設定。伺服器可以遞增這個值。 詳情請參閱 OpenTelemetry：資源。
instrumentation_scope	record (不含重複欄位) 這個欄位會識別收集遙測資料的指定 resource 程式庫或應用程式元件。跨度代表通過該範圍的特定作業，也就是通過資源內的程式庫或元件。 舉例來說，假設應用程式「結帳服務」已部署至 Cloud Run，這表示 resource 是特定的 Cloud Run 執行個體。此外，假設資源有多個檢測範圍，例如「request-authorization-library」和「payment-processor-library」。 用戶端範圍 (例如「WritePaymentInfoToStripe」) 可能是「payment-processor-library」回報的範圍，該範圍位於名為「checkout-service」的 Cloud Run 服務中。 這個欄位包含下列子欄位： 欄位 說明 name string version string attributes JSON type 每個屬性都是鍵/值組合。 可用的屬性取決於追蹤資料。屬性結構遵循 OpenTelemetry 標準。詳情請參閱「OpenTelemetry：屬性」。 dropped_attributes_count integer 遭捨棄的屬性數量。 屬性鍵過長或屬性過多，都可能導致屬性遭到捨棄。如果這個值為零，表示沒有任何屬性遭到捨棄。 這個值可能由用戶端檢測或應用程式設定。伺服器可以遞增這個值。 詳情請參閱「OpenTelemetry：檢測範圍」。
resource_schema_link	string 這些欄位必須是採字串格式的網址。 這些欄位包含可傳回資源結構定義檔案的網址。 結構定義檔案和資料的格式由 OpenTelemetry 定義。詳情請參閱「OpenTelemetry：結構定義」。 使用 Telemetry API 時，才能設定這些欄位。 該 API 不會驗證資料是否符合宣告的結構定義。
scope_schema_link	string 這些欄位必須是採字串格式的網址。 這些欄位包含的網址會傳回範圍的結構定義檔案。 結構定義檔案和資料的格式由 OpenTelemetry 定義。詳情請參閱「OpenTelemetry：結構定義」。 使用 Telemetry API 時，才能設定這些欄位。 該 API 不會驗證資料是否符合宣告的結構定義。
apphub	record (不含重複欄位) 如果追蹤範圍是由 App Hub 應用程式產生，且這些應用程式在支援的基礎架構上執行，或是已完成插碼，您就能使用應用程式專屬標籤。如要進一步瞭解 Application Monitoring 和這些標籤的適用時間，請參閱應用程式監控總覽。 這個欄位包含 application、service 和 workload 子欄位。 應用程式子欄位 說明 container string location string id string 服務/工作負載 子欄位 說明 id string environment_type string criticality_type string