Configurer la collecte de traces à l'aide d'OpenTelemetry

Ce document explique comment configurer le traçage côté client et de bout en bout. à l'aide d'OpenTelemetry. Vous devez configurer le traçage côté client avant de pouvoir activer le traçage de bout en bout. Pour en savoir plus, consultez la section Présentation de la collecte des traces.

Avant de commencer

• Pour vous assurer que le compte de service utilisé par votre application dispose des autorisations les autorisations permettant de configurer la collecte de traces, demandez à votre administrateur d'accorder au compte de service que votre application utilise le Agent Cloud Trace (roles/cloudtrace.agent) sur votre projet.

Configurer le traçage côté client

Pour configurer le traçage côté client, vous devez exporter des traces. Vous pouvez exporter des traces vers un collecteur ou directement à un backend d'observabilité. Vous pouvez configurer le traçage API OpenTelemetry.

Exporter des traces vers un collecteur à l'aide des API OpenTelemetry

Pour exporter des traces vers un collecteur à l'aide des API OpenTelemetry, configurez le SDK OpenTelemetry et l'exportateur OTLP :

1. Ajoutez les dépendances nécessaires à votre application à l'aide du code suivant :

   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. Configurer l'objet OpenTelemetry et activer le traçage

   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)

Exporter directement vers un backend d'observabilité à l'aide des API OpenTelemetry

Pour configurer les bibliothèques clientes Spanner de manière à exporter des segments de trace vers Cloud Trace ou un autre backend de fournisseur de services d'observabilité ; procédez comme suit:

1. Ajoutez les dépendances nécessaires à votre application à l'aide du code suivant:

   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. Configurer l'objet OpenTelemetry et activer le traçage

   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)

Configurer le traçage de bout en bout

Cette section fournit des instructions pour configurer le traçage de bout en bout (Aperçu) sur les bibliothèques clientes Spanner:

1. Ajoutez les dépendances nécessaires à votre application à l'aide du code suivant :

   Java

   Les dépendances de traçage côté client existantes sont suffisantes pour configurer le traçage de bout en bout. Vous n'avez pas besoin de dépendances supplémentaires.

   Go

   En plus des dépendances requises pour le traçage côté client, vous devez également disposer de la dépendance suivante :

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

2. Activez le traçage de bout en bout.

   Java

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

   Go

   Utilisez l'option EnableEndToEndTracing dans la configuration du client pour l'activer.

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

3. Définissez la propagation du contexte de trace dans OpenTelemetry.

   Java

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

   Go

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

Attributs de traçage de bout en bout

Les traces de bout en bout peuvent inclure les informations suivantes:

Nom de l'attribut	Description
service.name	La valeur de l'attribut est toujours spanner_api_frontend.
cloud.region	Région cloud Google Cloud de l'interface de l'API Spanner qui traite la requête de votre application.
gcp.spanner.query.fingerprint	La valeur de l'attribut correspond à l'empreinte de la requête. Pour déboguer davantage cette requête, consultez la colonne TEXT_FINGERPRINT dans les tables de statistiques sur les requêtes.
gcp.spanner.participants.count	Nombre de participants à la transaction. Pour en savoir plus, consultez la page Déroulement des opérations de lecture et d'écriture Spanner.

Exemple de trace

Une trace de bout en bout vous permet d'afficher les informations suivantes :

• La latence entre votre application et Spanner. Vous pouvez calculer la latence du réseau pour voir si vous avez des problèmes de réseau.
• Région cloud de l'interface de l'API Spanner dans laquelle votre application des requêtes sont traitées. Vous pouvez l'utiliser pour rechercher entre votre application et Spanner.

Dans l'exemple suivant, votre requête d'application est diffusée par l'interface de l'API Spanner dans la région us-west1 et la latence du réseau est de 8,542 ms (entre 55,47 ms et 46,928 ms).

Étape suivante

• Pour en savoir plus sur OpenTelemetry, consultez la documentation OpenTelemetry.