Configura la recopilación de seguimientos con OpenTelemetry

En este documento, se muestra cómo configurar el seguimiento del cliente y de extremo a extremo con OpenTelemetry. Debes configurar el seguimiento del cliente antes de habilitar el seguimiento de extremo a extremo. Para obtener más información, consulta Descripción general de la recopilación de Trace.

Antes de comenzar

• Para asegurarte de que la cuenta de servicio que usa tu aplicación tenga los permisos necesarios para configurar la recopilación de registros, pídele a tu administrador que le otorgue a la cuenta de servicio que usa tu aplicación el rol de IAM Agente de seguimiento de Cloud (roles/cloudtrace.agent) en tu proyecto.

Configura el seguimiento del cliente

Para configurar el seguimiento del cliente, debes exportar los seguimientos. Puedes exportar seguimientos a un recopilador o directamente a un backend de observabilidad. Puedes configurar el seguimiento con las APIs de OpenTelemetry.

Exporta seguimientos a un recopilador con las APIs de OpenTelemetry

Para exportar seguimientos a un recopilador con las APIs de OpenTelemetry, configura el SDK de OpenTelemetry y el exportador de OLTP:

1. Agrega las dependencias necesarias a tu aplicación con el siguiente 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

2. Configura el objeto OpenTelemetry y habilita el seguimiento.

   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)

Exporta directamente a un backend de observabilidad con las APIs de OpenTelemetry

Para configurar las bibliotecas cliente de Spanner de modo que exporten directamente los intervalos de seguimiento a Cloud Trace o a otro backend de proveedor de servicios de observabilidad, sigue estos pasos:

1. Agrega las dependencias necesarias a tu aplicación con el siguiente 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

2. Configura el objeto OpenTelemetry y habilita el seguimiento.

   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)

Cómo configurar el registro de extremo a extremo

En esta sección, se proporcionan instrucciones para configurar el seguimiento de extremo a extremo (versión preliminar) en las bibliotecas cliente de Spanner:

1. Agrega las dependencias necesarias a tu aplicación con el siguiente código:

   Java

   Las dependencias de seguimiento existentes del cliente son suficientes para configurar el seguimiento de extremo a extremo. No necesitas dependencias adicionales.

   Go

   Además de las dependencias que necesitas para el seguimiento del cliente, también necesitas la siguiente dependencia:

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

2. Habilita el seguimiento de extremo a extremo.

   Java

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

   Go

   Usa la opción EnableEndToEndTracing en la configuración del cliente para habilitarla.

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

3. Establece la propagación del contexto de seguimiento en OpenTelemetry.

   Java

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

   Go

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

Atributos de seguimiento de extremo a extremo

Los seguimientos de extremo a extremo pueden incluir la siguiente información:

Nombre del atributo	Descripción
service.name	El valor del atributo siempre es spanner_api_frontend.
cloud.region	La región de nube de Google Cloud del frontend de la API de Spanner que entrega la solicitud de tu aplicación
gcp.spanner.query.fingerprint	El valor del atributo es la huella digital de la consulta. Para depurar esta consulta en más detalle, consulta la columna TEXT_FINGERPRINT en las tablas de estadísticas de consultas.
gcp.spanner.participants.count	Es la cantidad de participantes involucrados en la transacción. Para obtener más información, consulta Ciclo de vida de las operaciones de lectura y escritura de Spanner.

Seguimiento de muestra

Un seguimiento de extremo a extremo te permite ver los siguientes detalles:

• La latencia entre tu aplicación y Spanner. Puedes calcular la latencia de red para ver si tienes algún problema de red.
• La región de nube del frontend de la API de Spanner desde la que se entregan las solicitudes de tu aplicación Puedes usar esto para verificar si hay llamadas entre regiones entre tu aplicación y Spanner.

En el siguiente ejemplo, el frontend de la API de Spanner entrega la solicitud de tu aplicación en la región us-west1 y la latencia de red es de 8.542 ms (55.47 ms - 46.928 ms).

¿Qué sigue?

• Para obtener más información sobre OpenTelemetry, consulta la documentación de OpenTelemetry.