OpenTelemetry を使用してトレースのコレクションを設定する

このドキュメントでは、OpenTelemetry を使用してクライアントサイドとエンドツーエンドのトレースを設定する方法について説明します。エンドツーエンド トレースを有効にするには、クライアントサイド トレースを設定する必要があります。詳細については、トレース コレクションの概要をご覧ください。

始める前に

  • アプリケーションで使用するサービス アカウントにトレース コレクションの設定に必要な権限が付与されるように、プロジェクトのアプリケーションで使用するサービス アカウントに Cloud Trace エージェント （roles/cloudtrace.agent）IAM ロールを付与するよう管理者に依頼してください。

クライアントサイド トレースを構成する

クライアントサイド トレースを構成するには、トレースをエクスポートする必要があります。トレースはコレクタにエクスポートすることも、オブザーバビリティ バックエンドに直接エクスポートすることもできます。トレースは OpenTelemetry API を使用して構成できます。

OpenTelemetry API を使用してコレクタにトレースをエクスポートする

OpenTelemetry API を使用してコレクタにトレースをエクスポートするには、OpenTelemetry SDK と OTLP エクスポータを構成します。

  1. 次のコードを使用して、必要な依存関係をアプリケーションに追加します。

    Java

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

    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

  2. OpenTelemetry オブジェクトを構成して、トレースを有効にします。

    Java

    Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
    OtlpGrpcSpanExporter
        .builder()
        .setEndpoint(otlpEndpoint) // Replace with your OTLP endpoint
        .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register as GlobalOpenTelemetry.
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

    Go

    
// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING
// to the case-insensitive value "opentelemetry" before loading the client library.

ctx := context.Background()

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new OTLP exporter.
defaultOtlpEndpoint := "http://localhost:4317" // Replace with the endpoint on which OTLP collector is running
traceExporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithEndpoint(defaultOtlpEndpoint))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(traceExporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

OpenTelemetry API を使用してオブザーバビリティ バックエンドに直接エクスポートする

トレーススパンを Cloud Trace または別のオブザーバビリティ サービス プロバイダのバックエンドに直接エクスポートするように Spanner クライアント ライブラリを構成する手順は次のとおりです。

  1. 次のコードを使用して、必要な依存関係をアプリケーションに追加します。

    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

  2. OpenTelemetry オブジェクトを構成して、トレースを有効にします。

    Java

    Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

SpanExporter traceExporter = TraceExporter.createWithConfiguration(
    TraceConfiguration.builder().setProjectId(projectId).build()
);

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(traceExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register it as global object.
// To register as the global OpenTelemetry object,
// use "OpenTelemetrySdk.builder()....buildAndRegisterGlobal()".
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

    Go

    
// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING
// to the case-insensitive value "opentelemetry" before loading the client library.

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new cloud trace exporter
exporter, err := traceExporter.New(traceExporter.WithProjectID(projectID))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(exporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

エンドツーエンドのトレースを構成する

このセクションでは、Spanner クライアント ライブラリでエンドツーエンドのトレース（プレビュー）を構成する手順について説明します。

  1. 次のコードを使用して、必要な依存関係をアプリケーションに追加します。

    Java

    エンドツーエンドのトレースを構成するには、既存のクライアントサイド トレースの依存関係で十分です。追加の依存関係は必要ありません。

    Go

    クライアントサイド トレースに必要な依存関係に加えて、次の依存関係も必要です。

    go.opentelemetry.io/otel/propagation v1.28.0

  2. エンドツーエンドのトレースを有効にします。

    Java

    SpannerOptions options = SpannerOptions.newBuilder()
  .setOpenTelemetry(openTelemetry)
  .setEnableEndToEndTracing(/* enableEndtoEndTracing= */ true)
  .build();

    Go

    有効にするには、クライアント構成で EnableEndToEndSideTracing オプションを使用します。

    client, _ := spanner.NewClientWithConfig(ctx, "projects/test-project/instances/test-instance/databases/test-db", spanner.ClientConfig{
SessionPoolConfig: spanner.DefaultSessionPoolConfig,
EnableEndToEndTracing:      true,
}, clientOptions...)

  3. OpenTelemetry でトレース コンテキストの伝播を設定します。

    Java

    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
  .setTracerProvider(sdkTracerProvider)
  .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
  .buildAndRegisterGlobal();

    Go

    // Register the TraceContext propagator globally.
otel.SetTextMapPropagator(propagation.TraceContext{})

エンドツーエンドのトレース属性

エンドツーエンドのトレースには、次の情報が含まれます。

属性名 説明
service.name 属性値は常に spanner_api_frontend です。
cloud.region アプリケーション リクエストを処理する Spanner API フロントエンドの Google Cloud クラウド リージョン。
gcp.spanner.query.fingerprint 属性値はクエリ フィンガープリントです。このクエリをさらにデバッグするには、クエリ統計テーブルの TEXT_FINGERPRINT 列をご覧ください。
gcp.spanner.participants.count トランザクションに関与する参加者数。詳細については、Spanner の読み取りと書き込みのライフサイクルをご覧ください。

サンプル トレース

エンドツーエンドのトレースでは、次の詳細を確認できます。

  • アプリケーションと Spanner 間のレイテンシ。ネットワーク レイテンシを計算して、ネットワークに問題があるかどうかを確認できます。
  • アプリケーション リクエストが処理される Spanner API フロントエンド クラウド リージョン。これを使用して、アプリケーションと Spanner 間のクロスリージョン呼び出しを確認できます。

次の例では、アプリケーション リクエストは us-west1 リージョンの Spanner API フロントエンドによって処理され、ネットワーク レイテンシは 8.542 ミリ秒（55.47 ミリ秒 ～ 46.928 ミリ秒）です。

エンドツーエンドのトレースを表示します。

次のステップ