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 para poder habilitar la opción un seguimiento de extremo a extremo. Para obtener más información, consulta Descripción general de la recopilación de seguimientos.

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 Cloud Trace (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 registros a un recopilador con las APIs de OpenTelemetry

Para exportar registros a un recopilador con las APIs de OpenTelemetry, sigue estos pasos: 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 (Vista previa) 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 del cliente existentes 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 habilitar esta opción. 

    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 Es la región de la 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 aún más esta consulta, revisa la columna TEXT_FINGERPRINT en las tablas de estadísticas de las consultas.
gcp.spanner.participants.count Indica la cantidad de participantes que participan 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 problemas.
  • Es la región de la nube de frontend de la API de Spanner en la que tu aplicación de las solicitudes de servicio. Puedes usar esto para verificar el tráfico entre regiones llamadas 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 la red es de 8.542 ms (55.47 ms - 46.928 ms).

Consulta un seguimiento de extremo a extremo.

¿Qué sigue?