Configurar a coleta de traces usando o OpenTelemetry

Neste documento, mostramos como configurar o rastreamento do lado do cliente e de ponta a ponta usando o OpenTelemetry. É necessário configurar o rastreamento do lado do cliente antes de ativar o rastreamento de ponta a ponta. Para mais informações, consulte Visão geral da coleta de traces.

Antes de começar

• Para garantir que a conta de serviço usada pelo aplicativo tenha as permissões necessárias para configurar a coleta de traces, peça ao administrador para conceder à conta de serviço usada pelo aplicativo o papel Agente do Cloud Trace (roles/cloudtrace.agent) do IAM no projeto.

• Verifique se a API Cloud Trace está ativada no seu projeto. Para mais informações sobre como ativar APIs, consulte Como ativar APIs.

Configurar o rastreamento do lado do cliente

Para configurar o rastreamento do lado do cliente, é necessário exportar traces. É possível exportar traces para um coletor ou diretamente para um back-end de observabilidade. É possível configurar o rastreamento usando as APIs OpenTelemetry.

Exportar traces para um coletor usando as APIs OpenTelemetry

Para exportar traces para um coletor usando APIs OpenTelemetry, configure o SDK do OpenTelemetry e o exportador OLTP:

1. Adicione as dependências necessárias ao aplicativo usando o seguinte código:

   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. Configure o objeto do OpenTelemetry e ative o rastreamento.

   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),
   )

Exportar diretamente para um back-end de observabilidade usando APIs OpenTelemetry

Para configurar as bibliotecas de cliente do Spanner para exportar diretamente períodos de trace para o Cloud Trace ou outro back-end de provedor de serviços de observabilidade, siga estas etapas:

1. Adicione as dependências necessárias ao aplicativo usando o seguinte código:

   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. Configure o objeto do OpenTelemetry e ative o rastreamento.

   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),
   )
   

Configurar o rastreamento de ponta a ponta

Nesta seção, você encontra instruções para configurar o rastreamento de ponta a ponta nas bibliotecas de cliente do Spanner:

1. Adicione as dependências necessárias ao aplicativo usando o seguinte código:

   Java

   As dependências de rastreamento do lado do cliente atuais são suficientes para configurar o rastreamento de ponta a ponta. Não são necessárias dependências extras.

   Go

   Além das dependências necessárias para o rastreamento do lado do cliente, você também precisa da seguinte dependência:

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

   Node.js

   As dependências de rastreamento do lado do cliente atuais são suficientes para configurar o rastreamento de ponta a ponta. Não são necessárias dependências extras.

   Python

   As dependências de rastreamento do lado do cliente atuais são suficientes para configurar o rastreamento de ponta a ponta. Não são necessárias dependências extras.

2. Ative o rastreamento de ponta a ponta.

   Java

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

   Go

   Use a opção EnableEndToEndTracing na configuração do cliente para ativar.

   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.Client(project_id, observability_options=observability_options)

3. Defina a propagação do contexto de trace no 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())

Atributos do rastreamento de ponta a ponta

Os traces de ponta a ponta podem incluir as seguintes informações:

Nome do atributo	Descrição
service.name	O valor do atributo é sempre spanner_api_frontend.
cloud.region	A região do Google Cloud cloud do front-end da API Spanner que atende à solicitação do aplicativo.
gcp.spanner.server.query.fingerprint	O valor do atributo é a impressão digital da consulta. Para depurar essa consulta, consulte a coluna TEXT_FINGERPRINT nas tabelas Estatísticas da consulta.
gcp.spanner.server.paxos.participantcount	O número de envolvidos na transação. Para mais informações, consulte Durabilidade das leituras e gravações do Spanner.
gcp.spanner.isolation_level	O valor do atributo é o nível de isolamento da transação. Os valores possíveis são SERIALIZABLE e REPEATABLE_READ. Para mais informações, consulte Visão geral dos níveis de isolamento.

Exemplo de trace

Um trace de ponta a ponta permite consultar os seguintes detalhes:

• A latência entre o aplicativo e o Spanner. Calcule a latência da rede para verificar se há problemas.
• A região do Cloud do front-end da API Spanner em que as solicitações do aplicativo são atendidas. Use isso para verificar chamadas entre regiões entre o aplicativo e o Spanner.

No exemplo a seguir, a solicitação do aplicativo é atendida pelo front-end da API Spanner na região us-west1 e a latência de rede é de 8,542 ms (55,47 ms - 46,928 ms).

A seguir

• Consulte a documentação do OpenTelemetry para mais informações.