このドキュメントでは、トレースを Cloud Logging ログエントリに関連付ける方法について説明します。LogEntry 構造のトレース フィールド（spanId、trace、traceSampled）を使用すると、ログとトレースを関連付けて、分散トラブルシューティングを効率化できます。
ログエントリをトレースまたはスパンに関連付ける
Cloud Logging API を使用してログデータを書き込むか、構造化ログデータを書き込むと、ログエントリをトレースまたはスパンに関連付けることができます。ログエントリは、トレースがサンプリングされたかどうかも記録できます。Ops エージェントが構造化ログデータを LogEntry 内のフィールドに変換する方法については、構造化ペイロードの特殊フィールドをご覧ください。
LogEntry オブジェクトの trace フィールドを設定して、ログエントリをトレースに関連付けるtrace フィールドは、次の形式の文字列に設定する必要があります。
projects/PROJECT_ID/traces/TRACE_ID
PROJECT_ID は Google Cloud プロジェクト ID、TRACE_ID はトレース ID です。
Cloud Logging API の使用時にログエントリをスパンに関連付けるには、LogEntry オブジェクトの spanId フィールドをスパン ID の 16 文字 16 進数エンコードに設定します。たとえば、ログエントリを ID 74 というスパンに関連付けるには、スパン ID を 000000000000004a に設定します。
トレース サンプリングを使用していて、ログエントリの書き込み時にストレージにトレースがサンプリングされたことを示すには、LogEntry オブジェクトの traceSampled フィールドを設定します。トレース サンプリングを使用すると、トレース自体がキャプチャされていないときにログエントリが作成される可能性があります。
ログエントリをトレースまたはスパンに自動的に関連付ける
Cloud Logging クライアント ライブラリを使用すると、ログエントリのトレースのフィールドが自動的に設定される場合があります。自動的に設定された値よりも、手動で設定された値が優先されます。
たとえば、OpenTelemetry を使用してアクティブな OpenTelemetry スパンからロギングしている場合、ログエントリのトレース フィールドは OpenTelemetry Context から入力されます。
また、HTTP リクエストがある場合は、W3C traceparent フィールドまたは HTTP リクエストの X-Cloud-Trace-Context 値からトレース フィールドを設定できます。
ログエントリのトレース フィールドの自動挿入について詳しくは、次の言語固有のクライアント ライブラリのドキュメントをご覧ください。
ログの表示
トレースのログエントリは、ウォーターフォール グラフの横またはログ エクスプローラに表示できます。ログ エクスプローラを使用した場合は、自動的にトレースのタイムスタンプ範囲に制限されます。表示するログエントリがない場合は、ログ エクスプローラに「No entries found matching current filter」というメッセージが表示されます。
[トレースの詳細] ペインで、トレースのログエントリを表示するには、次のいずれかを行います。
ウォーターフォールのグラフの横にトレース ログエントリを表示するには、ウォーターフォールのグラフに移動して [ログを表示] をクリックします。 [ログを表示] が表示されていない場合、ログエントリはありません。
ログ エクスプローラにログエントリを表示するには、[詳細] セクションの [ログ] というラベルの横にある [表示] をクリックします。Cloud Load Balancing トレースがある場合は、[VM Log] ラベルの横にある [表示] をクリックします。
Cloud Logging のログエントリの表示について詳しくは、ログ エクスプローラの使用をご覧ください。
ログの表示に関する権限
ログエントリを表示するには、プロジェクトで logging.logEntries.list 権限が必要です。この権限は、ログ閲覧者とプロジェクト閲覧者の Identity and Access Management（IAM）ロールによって提供されます。
VM インスタンスのログを表示するには、プロジェクトで compute.instances.get 権限が必要です。この権限は、Compute Engine ネットワーク閲覧者とプロジェクト閲覧者の IAM ロールによって提供されます。