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

このドキュメントでは、トレーススパンの保存形式について説明します。データの形式は、OpenTelemetry プロトコルで定義された proto ファイルと概ね一致しています。 ただし、フィールドは保存前に OpenTelemetry 固有のデータ型から JSON データ型に変換されることがあります。

Telemetry API は OpenTelemetry プロトコルを使用します。このプロトコルは、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 は、トレースに関連付けられたスパンを識別するために、可視化ツールと分析 ツールで使用されます。このため、 すべてのエンドツーエンド オペレーションに一意の識別子が必要です。トレース識別子を再利用しないでください。
span_id	string 必須。スパンの ID 。 トレース内で一意にする必要があります。 この識別子は、8 バイトの 16 進文字列としてフォーマットされた 64 ビットの数値です。 例: 9046a5b9f7c12500 数値 0 は無効です。
trace_state	string このフィールドは、 tracestate ヘッダーに対応しています。 W3C トレース コンテキストで定義されています。 このヘッダーには、トレースデータを収集するためにアプリケーションが計測されるときに リクエストに含まれる構成情報が含まれています。 たとえば、アプリケーションで 確率サンプリング 設定を指定したり、ベンダー固有のコンテンツを含めたりできます。 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: Attributes をご覧ください。 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: Attributes をご覧ください。 dropped_attributes_count integer 破棄された属性の数。 属性は、キーが長すぎるか、属性が多すぎるために破棄されることがあります。この値が 0 の場合、属性は破棄されませんでした。 この値は、クライアントサイドの計測またはアプリケーションによって設定される場合があります。この値はサーバーによって増やすことができます。
dropped_events_count	integer 破棄されたイベントの数。イベントが多すぎるために破棄されることがあります この値が 0 の場合、イベントは破棄されませんでした。
links	record 繰り返しフィールドを持つ スパンに関連付けられたリンク。リンクは、このスパン から同じトレースまたは別のトレース内の別のスパンへの参照です。 リンクは、1 つのトレースのスパンを別のトレースのスパンに関連付けるメカニズムを提供します。 たとえば、1 つのオペレーションによって 非同期オペレーションが発生するとします。このシナリオでは、元のオペレーションと非同期オペレーションの 2 つの トレースがあります。リンクを使用して、これらのトレースのスパンを関連付けることができます。 各リンクには次のフィールドが含まれます。 フィールド 説明 trace_id string 必須。 span_id string 必須。 trace_state string attributes JSON type 各属性は Key-Value ペアです。 使用できる属性はトレースデータによって異なります。属性の構造は OpenTelemetry 標準に準拠しています。詳細については、OpenTelemetry: Attributes をご覧ください。 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 で実行されているアプリケーションについて考えてみましょう。このリソースの属性 には、プロセス名や名前空間などがあります。 このフィールドには次のサブフィールドが含まれます。 フィールド 説明 attributes JSON type 各属性は Key-Value ペアです。 使用できる属性はトレースデータによって異なります。属性の構造は OpenTelemetry 標準に準拠しています。詳細については、OpenTelemetry: Attributes をご覧ください。 リソース属性の例を次に示します。 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: Resources をご覧ください。
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: Attributes をご覧ください。 dropped_attributes_count integer 破棄された属性の数。 属性は、キーが長すぎるか、属性が多すぎるために破棄されることがあります。この値が 0 の場合、属性は破棄されませんでした。 この値は、クライアントサイドの計測またはアプリケーションによって設定される場合があります。この値はサーバーによって増やすことができます。 詳細については、 OpenTelemetry: Instrumentation scope をご覧ください。
resource_schema_link	string これらのフィールドは、文字列としてフォーマットされた URL である必要があります。 これらのフィールドには、リソースのスキーマ ファイルを返す URL が含まれています。 スキーマ ファイルとデータの形式は OpenTelemetry によって定義されます。詳細については、OpenTelemetry: Schemas をご覧ください。 これらのフィールドは、Telemetry API を使用する場合にのみ設定できます。 この API は、データが宣言された スキーマに準拠していることを検証しません。
scope_schema_link	string これらのフィールドは、文字列としてフォーマットされた URL である必要があります。 これらのフィールドには、スコープのスキーマ ファイルを返す URL が含まれています。 スキーマ ファイルとデータの形式は OpenTelemetry によって定義されます。詳細については、OpenTelemetry: Schemas をご覧ください。 これらのフィールドは、Telemetry API を使用する場合にのみ設定できます。 この API は、データが宣言された スキーマに準拠していることを検証しません。
apphub	record 繰り返しフィールドのない アプリケーション固有のラベルは、App Hub アプリケーションによってトレーススパンが生成されるときに使用できます。これらのアプリケーションは、サポートされているインフラストラクチャで実行されるか、計測されています。アプリケーション モニタリングの詳細と、これらのラベルが使用できるタイミングについては、 アプリケーション モニタリングの概要をご覧ください。 このフィールドには、application、service、 および workload のサブフィールドが含まれています。 アプリケーション サブフィールド 説明 container string location string id string サービス/ワークロード サブフィールド 説明 id string environment_type string criticality_type string