このドキュメントでは、ログエントリをトレースにリンクする方法について説明します。ログエントリのフィールドを設定して、リンクを実行します。LogEntry 構造のトレース フィールド（spanId、trace、traceSampled）を使用すると、ログとトレースを関連付けて、分散トラブルシューティングを改善できます。
ログエントリをトレースまたはスパンに関連付ける
Cloud Logging API を使用してログデータを書き込むか、構造化ログデータを書き込むと、ログエントリをトレースまたはスパンに関連付けることができます。ログエントリは、トレースがサンプリングされたかどうかも記録できます。Ops エージェントが構造化ログデータを LogEntry 内のフィールドに変換する方法については、構造化ペイロードの特殊フィールドをご覧ください。
ログエントリをトレースに関連付けるには、LogEntry オブジェクトの trace フィールドを設定します。
- 推奨される形式:
TRACE_ID - 以前の形式:
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 リクエストが存在する場合、トレース フィールドは HTTP リクエストの W3C traceparent フィールドまたは 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 ロールによって提供されます。