トレースデータのストレージ スキーマ

このドキュメントでは、トレース スパンが保存される形式について説明します。データの形式は、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 トレースのグローバル一意識別子。この識別子は、16 バイトの 16 進数文字列としてフォーマットされた 128 ビットの数値です。例: 382d4f4c6b7bb2f4a972559d9085001dこの識別子の詳細については、W3C trace-id をご覧ください。 数値の 0 は無効です。 trace_id は、トレースに関連付けられたスパンを特定するために、可視化ツールと分析ツールで使用されます。そのため、すべてのエンドツーエンド オペレーションに一意の識別子が必要です。トレース ID を再利用しないでください。
span_id	string 必須。スパンの識別子。トレース内で一意である必要があります。この識別子は、8 バイトの 16 進数文字列としてフォーマットされた 64 ビットの数値です。例: 9046a5b9f7c12500 数値の 0 は無効です。
trace_state	string このフィールドは、W3C トレース コンテキストで定義されている tracestate ヘッダーに対応しています。このヘッダーには、トレースデータを収集するようにアプリケーションが計測されたときにリクエストに含まれる構成情報が含まれています。たとえば、アプリケーションで確率サンプリングの設定を指定したり、ベンダー固有のコンテンツを含めたりできます。 OpenTelemetry ライブラリは、スパンを生成するときに tracestate ヘッダーの値を自動的に記録します。
parent_span_id	string 省略可。このスパンを呼び出したオペレーションを特定します。「ルート」スパンには null に設定されている親スパン 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 エポックからのナノ秒単位の開始時刻。
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 各属性は Key-Value ペアです。使用できる属性は、トレースデータによって異なります。属性の構造は 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 破棄された属性の数。キーが長すぎるか、属性が多すぎるため、属性が破棄されることがあります。この値が 0 の場合、破棄された属性はありません。 この値は、クライアントサイドの計測機能またはアプリによって設定される場合があります。この値はサーバーによって増分できます。
events	繰り返しフィールドを含む record 特定の時点のイベント。各イベントには次のフィールドが含まれます。 フィールド 説明 time Timestamp time_unix_nano integer name string 必須。イベントの名前。 attributes JSON type 各属性は Key-Value ペアです。使用できる属性は、トレースデータによって異なります。属性の構造は OpenTelemetry 標準に準拠しています。詳細については、OpenTelemetry: 属性をご覧ください。 dropped_attributes_count integer 破棄された属性の数。キーが長すぎるか、属性が多すぎるため、属性が破棄されることがあります。この値が 0 の場合、破棄された属性はありません。 この値は、クライアントサイドの計測機能またはアプリによって設定される場合があります。この値はサーバーによって増分できます。
dropped_events_count	integer 破棄されたイベントの数。イベントが多すぎるため、イベントが破棄されることがあります。この値が 0 の場合、破棄されたイベントはありません。
links	繰り返しフィールドを含む record スパンに関連付けられたリンク。リンクは、このスパンから同じトレースまたは別のトレース内の別のスパンへの参照です。 リンクは、1 つのトレースのスパンを別のトレースのスパンに関連付けるメカニズムを提供します。たとえば、あるオペレーションによって非同期オペレーションが発生するとします。このシナリオでは、元のオペレーションと非同期オペレーションの 2 つのトレースがあります。リンクを使用すると、これらのトレース内のスパンを関連付けることができます。 各リンクには次のフィールドが含まれます。 フィールド 説明 trace_id string 必須。 span_id string 必須。 trace_state string attributes JSON type 各属性は Key-Value ペアです。使用できる属性は、トレースデータによって異なります。属性の構造は OpenTelemetry 標準に準拠しています。詳細については、OpenTelemetry: 属性をご覧ください。 dropped_attributes_count integer 破棄された属性の数。キーが長すぎるか、属性が多すぎるため、属性が破棄されることがあります。この値が 0 の場合、破棄された属性はありません。 この値は、クライアントサイドの計測機能またはアプリによって設定される場合があります。この値はサーバーによって増分できます。
dropped_links_count	integer 破棄されたリンクの数。リンクが多すぎるため、リンクが破棄されることがあります。この値が 0 の場合、リンクは破棄されませんでした。
status	繰り返しフィールドのない record このフィールドには、スパンの完了ステータスが記録されます。code サブフィールドの値は、OpenTelemetry: Span Status 列挙型に対応しています。 値 OpenTelemetry 列挙型 説明 0 UNSET 処理は正常に完了しました。 1 OK オペレーションがエラーなしとして手動でマークされました。 2 ERROR 操作は完了しましたが、エラーが発生しました。たとえば、クライアント スパンのステータスが 400（BAD REQUEST）の場合、このフィールドは ERROR に設定されます。 message サブフィールド（文字列としてフォーマット）には、エラー情報が含まれます。
resource	繰り返しフィールドのない record このフィールドは、テレメトリーが収集されたインフラストラクチャまたはホスティング システム、またはテレメトリーが対象とするインフラストラクチャまたはホスティング システムを識別します。たとえば、Google Kubernetes Engine で実行されているアプリケーションを考えてみましょう。このリソースの属性には、プロセス名や Namespace などがあります。 このフィールドには次のサブフィールドが含まれます。 フィールド 説明 attributes JSON type 各属性は Key-Value ペアです。使用できる属性は、トレースデータによって異なります。属性の構造は 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 破棄された属性の数。キーが長すぎるか、属性が多すぎるため、属性が破棄されることがあります。この値が 0 の場合、破棄された属性はありません。 この値は、クライアントサイドの計測機能またはアプリによって設定される場合があります。この値はサーバーによって増分できます。 詳細については、OpenTelemetry: リソースをご覧ください。
instrumentation_scope	繰り返しフィールドのない record このフィールドは、テレメトリーを収集している指定された resource のライブラリまたはアプリケーション コンポーネントを識別します。スパンは、そのスコープ（リソース内のライブラリまたはコンポーネント）を通過する特定のオペレーションを表します。 たとえば、アプリケーション「checkout-service」が Cloud Run にデプロイされている場合、resource は特定の Cloud Run インスタンスになります。また、リソースには「request-authorization-library」や「payment-processor-library」などの計測スコープが複数あるとします。 クライアント スパン（「WritePaymentInfoToStripe」など）は、「checkout-service」という名前の Cloud Run サービス内にある「payment-processor-library」によって報告されるスパンである可能性があります。 このフィールドには次のサブフィールドが含まれます。 フィールド 説明 name string version string attributes JSON type 各属性は Key-Value ペアです。使用できる属性は、トレースデータによって異なります。属性の構造は OpenTelemetry 標準に準拠しています。詳細については、OpenTelemetry: 属性をご覧ください。 dropped_attributes_count integer 破棄された属性の数。キーが長すぎるか、属性が多すぎるため、属性が破棄されることがあります。この値が 0 の場合、破棄された属性はありません。 この値は、クライアントサイドの計測機能またはアプリによって設定される場合があります。この値はサーバーによって増分できます。 詳細については、OpenTelemetry: 計測スコープをご覧ください。
resource_schema_link	string これらのフィールドは、文字列としてフォーマットされた URL である必要があります。 これらのフィールドには、リソースのスキーマ ファイルを返す URL が含まれています。スキーマ ファイルとデータの形式は OpenTelemetry によって定義されます。詳細については、OpenTelemetry: スキーマをご覧ください。 これらのフィールドは、Telemetry API を使用する場合にのみ設定できます。この API は、データが宣言されたスキーマに準拠していることを検証しません。
scope_schema_link	string これらのフィールドは、文字列としてフォーマットされた URL である必要があります。 これらのフィールドには、スコープのスキーマ ファイルを返す URL が含まれています。スキーマ ファイルとデータの形式は OpenTelemetry によって定義されます。詳細については、OpenTelemetry: スキーマをご覧ください。 これらのフィールドは、Telemetry API を使用する場合にのみ設定できます。この API は、データが宣言されたスキーマに準拠していることを検証しません。
apphub	繰り返しフィールドのない record アプリケーション固有のラベルは、App Hub アプリケーションによってトレース スパンが生成され、そのアプリケーションがサポートされているインフラストラクチャで実行されているか、計測されている場合に利用できます。アプリケーション モニタリングとこれらのラベルが使用可能になるタイミングの詳細については、アプリケーション モニタリングの概要をご覧ください。 このフィールドには、application、service、workload のサブフィールドが含まれます。 アプリケーション サブフィールド 説明 container string location string id string Service/workload サブフィールド 説明 id string environment_type string criticality_type string