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 de traces.

Avant de commencer

  • Pour vous assurer que le compte de service utilisé par votre application dispose des autorisations nécessaires pour configurer la collecte des traces, demandez à votre administrateur d'accorder au compte de service utilisé par votre application le rôle IAM Agent de suivi Cloud (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 vers un backend d'observabilité. Vous pouvez configurer le traçage à l'aide des 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. Configurez l'objet OpenTelemetry et activez 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 afin d'exporter directement des périodes 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. Configurez l'objet OpenTelemetry et activez 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 (Preview) 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

    Pour activer cette fonctionnalité, utilisez l'option EnableEndToEndTracing dans la configuration du client. 

    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 La région cloud Google Cloud du front-end 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 impliqués dans 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 rencontrez des problèmes de réseau.
  • Région cloud de l'interface de l'API Spanner à partir de laquelle vos requêtes d'application sont traitées. Vous pouvez l'utiliser pour vérifier les appels interrégionaux entre votre application et Spanner.

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

Afficher une trace de bout en bout

Étape suivante