このドキュメントでは、OpenTelemetry を使用してクライアントサイドとエンドツーエンドのトレースを設定する方法について説明します。エンドツーエンド トレースを有効にするには、まずクライアントサイド トレースを設定する必要があります。詳細については、トレースの収集の概要をご覧ください。
始める前に
-
アプリケーションで使用するサービス アカウントにトレース コレクションの設定に必要な権限が付与されるように、プロジェクトのアプリケーションで使用するサービス アカウントに Cloud Trace エージェント(
roles/cloudtrace.agent
)IAM ロールを付与するよう管理者に依頼してください。 プロジェクトで Cloud Trace API が有効になっていることを確認します。API の有効化の詳細については、API の有効化に関する記事をご覧ください。
クライアントサイド トレースを構成する
クライアントサイド トレースを構成するには、トレースをエクスポートする必要があります。トレースはコレクタにエクスポートすることも、オブザーバビリティ バックエンドに直接エクスポートすることもできます。トレースは OpenTelemetry API を使用して構成できます。
OpenTelemetry API を使用してトレースをコレクタにエクスポートする
OpenTelemetry API を使用してコレクタにトレースをエクスポートするには、OpenTelemetry SDK と OTLP エクスポータを構成します。
次のコードを使用して、必要な依存関係をアプリケーションに追加します。
Java
Go
go.opentelemetry.io/otel v1.28.0 go.opentelemetry.io/otel/sdk v1.28.0 go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.28.0
Node.js
"@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0", "@opentelemetry/sdk-trace-base": "^1.26.0", "@opentelemetry/sdk-trace-node": "^1.26.0",
Python
pip install opentelemetry-api opentelemetry-sdk pip install opentelemetry-exporter-otlp
OpenTelemetry オブジェクトを構成して、トレースを有効にします。
Java
Go
Node.js
Python
OpenTelemetry API を使用してオブザーバビリティ バックエンドに直接エクスポートする
トレーススパンを Cloud Trace または別のオブザーバビリティ サービス プロバイダのバックエンドに直接エクスポートするように Spanner クライアント ライブラリを構成する手順は次のとおりです。
次のコードを使用して、必要な依存関係をアプリケーションに追加します。
Java
<dependency> <groupId>com.google.cloud</groupId> <artifactId>google-cloud-spanner</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-sdk</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-sdk-common</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-sdk-trace</artifactId> </dependency> <dependency> <groupId>com.google.cloud.opentelemetry</groupId> <artifactId>exporter-trace</artifactId> <version>0.30.0</version> </dependency>
Go
go.opentelemetry.io/otel v1.28.0 go.opentelemetry.io/otel/sdk v1.28.0 github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace v1.24.1
Node.js
"@google-cloud/opentelemetry-cloud-trace-exporter": "^2.4.1", "@opentelemetry/sdk-trace-base": "^1.26.0", "@opentelemetry/sdk-trace-node": "^1.26.0",
Python
pip install opentelemetry-api opentelemetry-sdk pip install opentelemetry-exporter-gcp-trace
OpenTelemetry オブジェクトを構成して、トレースを有効にします。
Java
Go
Node.js
Python
エンドツーエンドのトレースを構成する
このセクションでは、Spanner クライアント ライブラリでエンドツーエンドのトレースを構成する手順について説明します。
次のコードを使用して、必要な依存関係をアプリケーションに追加します。
Java
エンドツーエンドのトレースを構成するには、既存のクライアントサイド トレース依存関係で十分です。追加の依存関係は必要ありません。
Go
クライアントサイド トレース用に必要な依存関係に加えて、次の依存関係も必要です。
go.opentelemetry.io/otel/propagation v1.28.0
Node.js
エンドツーエンドのトレースを構成するには、既存のクライアントサイド トレース依存関係で十分です。追加の依存関係は必要ありません。
Python
エンドツーエンドのトレースを構成するには、既存のクライアントサイド トレース依存関係で十分です。追加の依存関係は必要ありません。
エンドツーエンドのトレースを有効にします。
Java
SpannerOptions options = SpannerOptions.newBuilder() .setOpenTelemetry(openTelemetry) .setEnableEndToEndTracing(/* enableEndtoEndTracing= */ true) .build();
Go
有効にするには、クライアント構成で
EnableEndToEndTracing
オプションを使用します。client, _ := spanner.NewClientWithConfig(ctx, "projects/test-project/instances/test-instance/databases/test-db", spanner.ClientConfig{ SessionPoolConfig: spanner.DefaultSessionPoolConfig, EnableEndToEndTracing: true, }, clientOptions...)
Node.js
const spanner = new Spanner({ projectId: projectId, observabilityOptions: { tracerProvider: openTelemetryTracerProvider, enableEndToEndTracing: true, } })
Python
observability_options = dict( tracer_provider=tracer_provider, enable_end_to_end_tracing=True, ) spanner = spanner.NewClient(project_id, observability_options=observability_options)
OpenTelemetry でトレース コンテキストの伝播を設定する。
Java
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() .setTracerProvider(sdkTracerProvider) .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance())) .buildAndRegisterGlobal();
Go
// Register the TraceContext propagator globally. otel.SetTextMapPropagator(propagation.TraceContext{})
Node.js
const {propagation} = require('@opentelemetry/api'); const {W3CTraceContextPropagator} = require('@opentelemetry/core'); propagation.setGlobalPropagator(new W3CTraceContextPropagator());
Python
from opentelemetry.propagate import set_global_textmap from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator set_global_textmap(TraceContextTextMapPropagator())
エンドツーエンドのトレース属性
エンドツーエンドのトレースには、次の情報を設定できます。
属性名 | 説明 |
---|---|
service.name | 属性値は常に spanner_api_frontend です。 |
cloud.region | アプリケーション リクエストを処理する Spanner API フロントエンドの Google Cloud クラウド リージョン。 |
gcp.spanner.server.query.fingerprint | 属性値はクエリ フィンガープリントです。このクエリをさらにデバッグするには、クエリ統計情報テーブルの TEXT_FINGERPRINT 列をご覧ください。 |
gcp.spanner.server.paxos.participantcount | トランザクションに関与する参加者数。詳細については、Spanner の読み取りと書き込みのライフサイクルをご覧ください。 |
サンプル トレース
エンドツーエンドのトレースでは、次の詳細情報を確認できます。
- アプリケーションと Spanner の間のレイテンシ。ネットワーク レイテンシを計算して、ネットワークに問題があるかどうかを確認できます。
- アプリケーション リクエストが処理される Spanner API フロントエンド クラウド リージョン。これを使用して、アプリケーションと Spanner の間のクロスリージョン呼び出しを確認できます。
次の例では、アプリケーション リクエストは us-west1
リージョンの Spanner API フロントエンドによって処理され、ネットワーク レイテンシは 8.542 ミリ秒(55.47 ミリ秒~46.928 ミリ秒)です。
次のステップ
- OpenTelemetry の詳細について、OpenTelemetry のドキュメントで確認する。