Configurare la raccolta delle tracce utilizzando OpenTelemetry

Questo documento mostra come configurare il monitoraggio lato client e end-to-end utilizzando OpenTelemetry. Devi configurare il monitoraggio lato client prima di poter attivare il monitoraggio end-to-end. Per ulteriori informazioni, consulta la panoramica della raccolta dei traccianti.

Prima di iniziare

• Per assicurarti che l'account di servizio utilizzato dalla tua applicazione disponga delle autorizzazioni necessarie per configurare la raccolta dei tracciati, chiedi all'amministratore di concedere all'account di servizio utilizzato dalla tua applicazione il ruolo IAM Agente di monitoraggio Cloud (roles/cloudtrace.agent) nel tuo progetto.

• Verifica che l'API Cloud Trace sia abilitata nel tuo progetto. Per ulteriori informazioni sull'attivazione delle API, consulta Attivare le API.

Configurare il monitoraggio lato client

Per configurare il monitoraggio lato client, devi esportare le tracce. Puoi esportare le tracce in un collector o direttamente in un backend di osservabilità. Puoi configurare il monitoraggio utilizzando le API OpenTelemetry.

Esportare le tracce in un collector utilizzando le API OpenTelemetry

Per esportare le tracce in un raccoglitore utilizzando le API OpenTelemetry, configura l'SDK OpenTelemetry e l'esportatore OLTP:

1. Aggiungi le dipendenze necessarie all'applicazione utilizzando il seguente codice:

   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>

   Vai

   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 l'oggetto OpenTelemetry e abilita il monitoraggio.

   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();

   Vai

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

Esporta direttamente in un backend di osservabilità utilizzando le API OpenTelemetry

Per configurare le librerie client di Spanner in modo da esportare direttamente gli intervalli di traccia in Cloud Trace o in un altro backend del provider di servizi di osservabilità, segui questi passaggi:

1. Aggiungi le dipendenze necessarie all'applicazione utilizzando il seguente codice:

   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>

   Vai

   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 l'oggetto OpenTelemetry e abilita il monitoraggio.

   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();

   Vai

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

Configura il monitoraggio end-to-end

Questa sezione fornisce istruzioni per configurare il monitoraggio end-to-end (anteprima) nelle librerie client di Spanner:

1. Aggiungi le dipendenze necessarie all'applicazione utilizzando il seguente codice:

   Java

   Le dipendenze di monitoraggio lato client esistenti sono sufficienti per configurare il monitoraggio end-to-end. Non sono necessarie dipendenze aggiuntive.

   Vai

   Oltre alle dipendenze necessarie per il monitoraggio lato client, è necessaria anche la seguente dipendenza:

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

2. Attiva il monitoraggio end-to-end.

   Java

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

   Vai

   Utilizza l'opzione EnableEndToEndTracing nella configurazione del client per attivare la funzionalità.

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

3. Imposta la propagazione del contesto della traccia in OpenTelemetry.

   Java

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

   Vai

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

Attributi di monitoraggio end-to-end

Le tracce end-to-end possono includere le seguenti informazioni:

Nome dell'attributo	Descrizione
service.name	Il valore dell'attributo è sempre spanner_api_frontend.
cloud.region	La Google Cloud regione cloud del frontend dell'API Spanner che gestisce la richiesta dell'applicazione.
gcp.spanner.query.fingerprint	Il valore dell'attributo è l'impronta della query. Per eseguire ulteriormente il debug di questa query, consulta la colonna TEXT_FINGERPRINT nelle tabelle Statistiche sulle query.
gcp.spanner.participants.count	Il numero di partecipanti coinvolti nella transazione. Per ulteriori informazioni, consulta la sezione Durata di letture e scritture di Spanner.

Traccia di esempio

Una traccia end-to-end ti consente di visualizzare i seguenti dettagli:

• La latenza tra la tua applicazione e Spanner. Puoi calcolare la latenza della rete per verificare se ci sono problemi di rete.
• La regione cloud del frontend dell'API Spanner da cui vengono eseguite le richieste dell'applicazione. Puoi utilizzarlo per verificare la presenza di chiamate tra regioni tra la tua applicazione e Spanner.

Nell'esempio seguente, la richiesta dell'applicazione viene gestita dal frontend dell'API Spanner nella regione us-west1 e la latenza della rete è di 8,542 ms (55,47 ms - 46,928 ms).

Passaggi successivi

• Per ulteriori informazioni su OpenTelemetry, consulta la documentazione di OpenTelemetry.