Ce document vous explique comment configurer le traçage de bout en bout et côté client à 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 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 nécessaires pour configurer la collecte de traces, demandez à votre administrateur d'accorder au compte de service utilisé par votre application le rôle IAM Agent Cloud Trace (
roles/cloudtrace.agent
) sur votre projet. Vérifiez que l'API Cloud Trace est activée pour votre projet. Pour en savoir plus sur l'activation des API, consultez Activer des API.
Configurer le traçage côté client
Pour configurer le traçage côté client, vous devez exporter les 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 OLTP :
Ajoutez les dépendances nécessaires à votre application à l'aide du code suivant :
Java
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
Node.js
"@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0", "@opentelemetry/sdk-trace-base": "^1.26.0", "@opentelemetry/sdk-trace-node": "^1.26.0",
Python
pip install opentelemetry-api opentelemetry-sdk pip install opentelemetry-exporter-otlp
Configurez l'objet OpenTelemetry et activez le traçage.
Java
Go
Node.js
Python
Exporter directement vers un backend d'observabilité à l'aide des API OpenTelemetry
Pour configurer les bibliothèques clientes Spanner afin d'exporter directement les étendues de trace vers Cloud Trace ou un autre backend de fournisseur de services d'observabilité, procédez comme suit :
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
Node.js
"@google-cloud/opentelemetry-cloud-trace-exporter": "^2.4.1", "@opentelemetry/sdk-trace-base": "^1.26.0", "@opentelemetry/sdk-trace-node": "^1.26.0",
Python
pip install opentelemetry-api opentelemetry-sdk pip install opentelemetry-exporter-gcp-trace
Configurez l'objet OpenTelemetry et activez le traçage.
Java
Go
Node.js
Python
Configurer le traçage de bout en bout
Cette section fournit des instructions pour configurer le traçage de bout en bout sur les bibliothèques clientes Spanner :
Ajoutez les dépendances nécessaires à votre application à l'aide du code suivant :
Java
Les dépendances de traçage côté client existantes suffisent pour configurer le traçage de bout en bout. Vous n'avez besoin d'aucune dépendance supplémentaire.
Go
En plus des dépendances dont vous avez besoin pour le traçage côté client, vous avez également besoin de la dépendance suivante :
go.opentelemetry.io/otel/propagation v1.28.0
Node.js
Les dépendances de traçage côté client existantes suffisent pour configurer le traçage de bout en bout. Vous n'avez besoin d'aucune dépendance supplémentaire.
Python
Les dépendances de traçage côté client existantes suffisent pour configurer le traçage de bout en bout. Vous n'avez besoin d'aucune dépendance supplémentaire.
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...)
Node.js
const spanner = new Spanner({ projectId: projectId, observabilityOptions: { tracerProvider: openTelemetryTracerProvider, enableEndToEndTracing: true, } })
Python
observability_options = dict( tracer_provider=tracer_provider, enable_end_to_end_tracing=True, ) spanner = spanner.NewClient(project_id, observability_options=observability_options)
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{})
Node.js
const {propagation} = require('@opentelemetry/api'); const {W3CTraceContextPropagator} = require('@opentelemetry/core'); propagation.setGlobalPropagator(new W3CTraceContextPropagator());
Python
from opentelemetry.propagate import set_global_textmap from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator set_global_textmap(TraceContextTextMapPropagator())
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.server.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.server.paxos.participantcount | Nombre de participants impliqués dans la transaction. Pour en savoir plus, consultez 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 :
- Latence entre votre application et Spanner. Vous pouvez calculer la latence du réseau pour vérifier si vous rencontrez des problèmes de réseau.
- Région Cloud de l'interface de l'API Spanner à partir de laquelle les requêtes de votre 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
. La latence réseau est de 8,542 ms (55,47 ms - 46,928 ms).
Étapes suivantes
- Pour en savoir plus sur OpenTelemetry, consultez la documentation OpenTelemetry.