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

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

始める前に

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

• プロジェクトで Cloud Trace API が有効になっていることを確認します。API の有効化の詳細については、API の有効化に関する記事をご覧ください。

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

クライアントサイド トレースを構成するには、トレースをエクスポートする必要があります。トレースはコレクタにエクスポートすることも、オブザーバビリティ バックエンドに直接エクスポートすることもできます。トレースは 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

   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

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)

   Node.js

   const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
   const {
     OTLPTraceExporter,
   } = require('@opentelemetry/exporter-trace-otlp-grpc');
   const {
     BatchSpanProcessor,
     TraceIdRatioBasedSampler,
   } = require('@opentelemetry/sdk-trace-base');
   const {Resource} = require('@opentelemetry/resources');
   const {Spanner} = require('@google-cloud/spanner');
   
   // Define a Resource with service metadata
   const resource = new Resource({
     'service.name': 'my-service',
     'service.version': '1.0.0',
   });
   
   // Create an OTLP gRPC trace exporter
   const traceExporter = new OTLPTraceExporter({
     url: 'http://localhost:4317', // Default OTLP gRPC endpoint
   });
   
   // Create a provider with a custom sampler
   const provider = new NodeTracerProvider({
     sampler: new TraceIdRatioBasedSampler(1.0), // Sample 100% of traces
     resource,
     spanProcessors: [new BatchSpanProcessor(traceExporter)],
   });
   
   // Uncomment following line to register tracerProvider globally or pass it in Spanner object
   // provider.register();
   
   // Create the Cloud Spanner Client.
   const spanner = new Spanner({
     projectId: projectId,
     observabilityOptions: {
       tracerProvider: provider,
       enableExtendedTracing: true,
       enableEndToEndTracing: true,
     },
   });
   

   Python

   # Setup OpenTelemetry, trace and OTLP exporter.
   tracer_provider = TracerProvider(sampler=ALWAYS_ON)
   otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")
   tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
   
   # Setup the Cloud Spanner Client.
   spanner_client = spanner.Client(
       project_id,
       observability_options=dict(tracer_provider=tracer_provider, enable_extended_tracing=True, enable_end_to_end_tracing=True),
   )

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

   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

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)

   Node.js

   
   const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
   const {
     TraceExporter,
   } = require('@google-cloud/opentelemetry-cloud-trace-exporter');
   const {
     BatchSpanProcessor,
     TraceIdRatioBasedSampler,
   } = require('@opentelemetry/sdk-trace-base');
   const {Spanner} = require('@google-cloud/spanner');
   
   const traceExporter = new TraceExporter();
   
   // Create a provider with a custom sampler
   const provider = new NodeTracerProvider({
     sampler: new TraceIdRatioBasedSampler(1.0), // Sample 100% of traces
     spanProcessors: [new BatchSpanProcessor(traceExporter)],
   });
   
   // Uncomment following line to register tracerProvider globally or pass it in Spanner object
   // provider.register();
   
   // Set global propagator to propogate the trace context for end to end tracing.
   const {propagation} = require('@opentelemetry/api');
   const {W3CTraceContextPropagator} = require('@opentelemetry/core');
   propagation.setGlobalPropagator(new W3CTraceContextPropagator());
   
   const spanner = new Spanner({
     projectId: projectId,
     observabilityOptions: {
       tracerProvider: provider,
       // Enable extended tracing to allow your SQL statements to be annotated.
       enableExtendedTracing: true,
       // Enable end to end tracing.
       enableEndToEndTracing: true,
     },
   });
   

   Python

   # Setup OpenTelemetry, trace and Cloud Trace exporter.
   tracer_provider = TracerProvider(sampler=ALWAYS_ON)
   trace_exporter = CloudTraceSpanExporter(project_id=project_id)
   tracer_provider.add_span_processor(BatchSpanProcessor(trace_exporter))
   
   # Setup the Cloud Spanner Client.
   spanner_client = spanner.Client(
       project_id,
       observability_options=dict(tracer_provider=tracer_provider, enable_extended_tracing=True, enable_end_to_end_tracing=True),
   )
   

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

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

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

   Java

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

   Go

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

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

   Node.js

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

   Python

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

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

   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)

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{})

   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 のドキュメントで確認する。