Surveiller les performances avec des traces côté client

Pour surveiller et déboguer les requêtes Firestore en mode Datastore (Datastore) de bout en bout, vous pouvez activer les traces dans la bibliothèque cliente Java. Le traçage côté client peut fournir un signal sur les performances telles qu'elles sont perçues par votre application, ainsi que des informations qui peuvent vous aider à déboguer les problèmes.

Les traces côté client, qui sont collectées en exécutant des RPC à partir du client, fournissent les informations suivantes :

  • Des segments avec des codes temporels indiquant quand le client a envoyé la requête RPC et quand il a reçu la réponse RPC, y compris la latence introduite par le réseau et le système client
  • Des attributs (paires clé/valeur) qui fournissent des informations sur le client et sa configuration.
  • Des journaux associés aux événements clés des segments.
  • Des traces de pile en cas de plantage sur le client.

OpenTelemetry

Les traces de la bibliothèque cliente Java sont instrumentées à l'aide de OpenTelemetry API. OpenTelemetry est un framework d'observabilité Open Source standard du secteur. OpenTelemetry propose un large éventail d'outils tels que des API et des SDK d'instrumentation, des collecteurs, des exportateurs spécifiques au backend et des options de configuration flexibles telles que des contrôles d'échantillonnage, des limites de segment, etc.

Exporter des traces avec des exportateurs et des collecteurs

Dans le cadre de vos configurations, vous pouvez exporter vos traces vers un backend d'observabilité. La plupart des fournisseurs de services d'observabilité proposent des exportateurs que vous pouvez utiliser, comme Cloud Trace.

En plus d'un exportateur, OpenTelemetry recommande de configurer un collecteur. Un collecteur permet à votre service de décharger rapidement les données et de gérer des tâches supplémentaires telles que les nouvelles tentatives, le traitement par lot et le chiffrement. Un collecteur s'exécute en parallèle de votre application. Il reçoit les messages du protocole OpenTelemetry (OTLP), les traite et les exporte vers votre backend d'observabilité.

Limites

Les segments de trace ne sont disponibles que pour la bibliothèque cliente Java.

Facturation

En plus de l'utilisation de Datastore, le traçage côté client peut entraîner des frais.

La collecte de traces ou l'utilisation du framework OpenTelemetry n'entraînent aucun frais.

L'ingestion de segments de trace dans votre backend d'observabilité peut être facturable. Par exemple, si vous utilisez Cloud Trace comme backend, vous êtes facturé en fonction des tarifs de Cloud Trace. Si vous utilisez un autre fournisseur de services d'observabilité, renseignez-vous sur son modèle de facturation et les coûts associés.

Pour mieux comprendre la facturation, commencez par un faible taux d'échantillonnage de trace (tracez un petit pourcentage de vos RPC) en fonction de votre trafic.

Avant de commencer

Avant de commencer :

  • Assurez-vous de configurer le compte de service sous lequel votre application écrit des traces dans votre backend d'observabilité avec les rôles Identity and Access Management nécessaires :

    Opération de trace Rôle IAM
    Lire les traces roles/cloudtrace.user
    Écrire des traces roles/cloudtrace.agent
    Lire/écrire des traces roles/cloudtrace.admin

  • Vérifiez que l'API Trace est activée pour ce projet.

Configurer des traces côté client

Cette section fournit des exemples de configurations pour les traces côté client. Vous pouvez exporter vers un collecteur ou directement vers un backend d'observabilité. Vous disposez également des options suivantes pour configurer les traces côté client :

Exporter des traces vers un collecteur avec les API OpenTelemetry

Le code suivant configure la bibliothèque cliente Java Datastore pour exporter des segments avec un taux d'échantillonnage de 10 % vers un collecteur OpenTelemetry.

Java

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
  OtlpGrpcSpanExporter
  .builder()
  .setEndpoint("http://localhost:4317") // 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();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

Exporter directement vers un backend d'observabilité avec les API OpenTelemetry

Le code suivant configure la bibliothèque cliente Java pour exporter directement des segments de trace vers Cloud Trace avec un taux d'échantillonnage de trace de 10 %. Vous pouvez utiliser les exportateurs d'autres fournisseurs de services d'observabilité pour exporter directement vers leur backend. Si votre backend d'observabilité est compatible avec l'ingestion OTLP, vous pouvez utiliser OtlpGrpcSpanExporter d'OpenTelemetry pour exporter vers votre backend au lieu d'utiliser un exportateur personnalisé.

Java

// TraceExporter needed for this use case
import com.google.cloud.opentelemetry.trace.TraceExporter;

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
SpanExporter gcpTraceExporter = TraceExporter.createWithDefaultConfiguration();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
SpanProcessor gcpBatchSpanProcessor =
  BatchSpanProcessor.builder(gcpTraceExporter).build();

// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

Exporter vers un collecteur avec des agents automatiques

Exécutez votre collecteur OpenTelemetry avec les récepteurs gRPC OTLP activés. Définissez l'exportateur de l'agent sur otlp et spécifiez le point de terminaison vers lequel l'agent doit exporter les données. L'exemple suivant utilise un taux d'échantillonnage de 10 % et envoie des traces au collecteur qui écoute sur le port localhost 4317.

Terminal

DATASTORE_ENABLE_TRACING=ON                            \
java                                                   \
-javaagent:path/to/opentelemetry-javaagent.jar         \
-Dotel.traces.exporter=otlp                            \
-Dotel.exporter.otlp.endpoint="http://localhost:4317"  \
-Dotel.traces.sampler=traceidratio                     \
-Dotel.traces.sampler.arg=0.1                          \
-Dotel.service.name="My App"                           \
-jar myapp.jar

Exporter directement vers un backend d'observabilité avec des agents automatiques

En plus de définir la variable d'environnement DATASTORE_ENABLE_TRACING=ON, vous devez ajouter l'extension de l'agent Java OpenTelemetry pour votre backend spécifique. L'exemple suivant utilise l'extension de l'exportateur Trace et un taux d'échantillonnage de trace de 10 %.

Terminal

DATASTORE_ENABLE_TRACING=ON                                                \
java                                                                       \
-javaagent:path/to/opentelemetry-javaagent.jar                             \
-Dotel.javaagent.extensions=/path/to/exporter-auto-0.26.0-alpha-shaded.jar \
-Dotel.traces.exporter=google_cloud_trace                                  \
-Dotel.traces.sampler=traceidratio                                         \
-Dotel.traces.sampler.arg=0.1                                              \
-Dotel.service.name="My Application"                                       \
-jar myapp.jar

Exemple de trace

Les exemples suivants montrent comment les informations de trace s'affichent dans Cloud Trace. Pour en savoir plus sur les attributs et les valeurs possibles, consultez la section Attributs et événements des segments de trace.

Exemple de segment de trace

Segment de trace affiché dans Cloud Trace.

Exemple de journal d'événements

Journal des événements d'une portée de trace affiché dans Cloud Trace.

Exemples de valeurs d'attribut

Valeurs d'attribut d'un délai de trace affiché dans Cloud Trace.

Étape suivante