使用 OpenTelemetry 設定追蹤記錄收集作業

本文說明如何使用 OpenTelemetry 設定用戶端和端對端追蹤。如要啟用端對端追蹤，請先設定用戶端追蹤。詳情請參閱「追蹤記錄收集總覽」。

事前準備

• 為確保應用程式使用的服務帳戶具備設定追蹤記錄收集作業的必要權限，請要求管理員在專案中，將下列 IAM 角色授予應用程式使用的服務帳戶：

  重要事項：您必須將這些角色授予應用程式使用的服務帳戶，而非使用者帳戶。如果未將角色授予正確的主體，可能會導致權限錯誤。
  • 所有項目： Cloud 遙測資料追蹤記錄寫入者 (roles/telemetry.tracesWriter)

• 確認專案已啟用 Cloud Trace 和 Telemetry API。如要進一步瞭解如何啟用 API，請參閱「啟用 API」。

設定用戶端追蹤

如要使用 OpenTelemetry Protocol (OTLP) 匯出追蹤記錄，請設定應用程式。您可以將資料傳送至 OpenTelemetry Collector，也可以透過 Telemetry API 直接傳送至 Cloud Trace。這兩種方法使用相同的依附元件和設定。兩者唯一的差異在於匯出工具使用的 OTLP 端點。

使用 OpenTelemetry 通訊協定匯出追蹤記錄

如要使用 OpenTelemetry Protocol 匯出追蹤記錄，請設定 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),
   )

設定端對端追蹤

本節提供相關操作說明，協助您在 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={
   "tracer_provider": tracer_provider,
   "enable_end_to_end_tracing": True,
   }
   spanner = spanner.Client(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	參與交易的人數。詳情請參閱「Cloud Spanner 的讀取與寫入」。
gcp.spanner.isolation_level	屬性值是交易的隔離等級。 可能的值為 SERIALIZABLE 和 REPEATABLE_READ。詳情請參閱隔離等級總覽。

追蹤記錄樣本

端對端追蹤記錄可讓您查看下列詳細資料：

• 應用程式與 Spanner 之間的延遲時間。您可以計算網路延遲，確認是否有任何網路問題。
• 應用程式要求所使用的 Spanner API 前端雲端區域。您可以使用這項功能，檢查應用程式與 Spanner 之間的跨區域呼叫。

在下列範例中，您的應用程式要求是由 us-west1 區域的 Spanner API 前端提供服務，網路延遲時間為 8.542 毫秒 (55.47 毫秒 - 46.928 毫秒)。

後續步驟

• 如要進一步瞭解 OpenTelemetry，請參閱 OpenTelemetry 說明文件。