Surveiller les performances avec des traces côté client

Pour surveiller et déboguer les requêtes Firestore de bout en bout, vous pouvez activer les traces dans la bibliothèque cliente Java. Le traçage côté client peut fournir sur les performances de votre application des insights qui peuvent vous aider à résoudre les problèmes.

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

  • Intervalles avec des codes temporels indiquant le moment où le client a envoyé la requête RPC et le moment où 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 sa configuration
  • Journaux associés aux événements clés des périodes
  • Traces de la pile en cas de plantage dans le client

OpenTelementry

Les traces de la bibliothèque cliente Java sont instrumentées à l'aide des API OpenTelemetry. OpenTelemetry est un framework d'observabilité Open Source, conforme aux normes du secteur. OpenTelemetry offre une large gamme d'outils tels que les API d'instrumentation et SDK, collecteurs, exportateurs spécifiques au backend et options de configuration flexibles comme les commandes d'échantillonnage, les limites de segments, 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, tels que 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 s'occuper de la gestion supplémentaire, comme les nouvelles tentatives, le traitement par lot et le chiffrement. Un collecteur s'exécute à côté de votre application. Le collecteur reçoit les messages OTLP, les traite et les exporte vers votre backend d'observabilité.

Limites

Les traces côté client présentent les limites suivantes :

  • Les plages de traces sont disponibles pour la bibliothèque cliente Java.
  • La bibliothèque cliente ne génère pas de délais de trace pour les écouteurs en temps réel.

Facturation

Outre l'utilisation de Firestore, le traçage côté client peut entraîner frais.

La collecte de traces et l'utilisation d'OpenTelemetry sont gratuites. d'infrastructure.

L'ingestion de délais de trace dans le backend d'observabilité peut être facturée. Par exemple, si vous utilisez Cloud Trace comme backend, vous êtes facturé selon les 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 faible pourcentage de vos RPC) en fonction sur votre trafic.

Avant de commencer

Avant de commencer :

  • Veillez à configurer le compte de service avec lequel votre application écrit des traces à votre backend d'observabilité avec les identifiants Rôles Identity and Access Management:

    Opération de suivi Rôle IAM
    Lire les traces roles/cloudtrace.user
    Écrire des traces roles/cloudtrace.agent
    Traces de lecture/écriture 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 Firestore pour exporter des segments avec un ratio d'échantillonnage de 10% vers un collecteur OpenTelemetry.

Java (administrateur)

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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

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

Le code suivant configure la bibliothèque cliente Java pour exporter directement la trace à Cloud Trace avec un taux d'échantillonnage de 10 %. Vous pouvez utiliser d'autres fournisseurs de services d'observabilité exportateurs d'exportation directe vers backend. Si votre backend d'observabilité prend en charge l'ingestion OTLP, vous pouvez utiliser OpenTelemetry OtlpGrpcSpanExporter pour exporter vers votre backend plutôt qu'un exportateur personnalisé.

Java (administrateur)

// 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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

Exporter vers un collecteur avec des agents automatiques

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

Terminal

FIRESTORE_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 FIRESTORE_ENABLE_TRACING=ON, vous devez ajouter l'extension de l'agent Java OpenTelemetry pour votre backend spécifique. L'exemple suivant utilise l'extension Trace Exportateur et un taux d'échantillonnage de 10 %.

Terminal

FIRESTORE_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                                              \

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 valeurs possibles, consultez Tracer les attributs et les événements de segments

Exemple de délai de trace

Intervalle de trace affiché dans Cloud Trace

Exemple de journal des événements

Journal des événements d'une étendue de trace affiché dans Cloud Trace

Exemples de valeurs d'attribut

Valeurs d'attribut d'un délai de trace visualisées depuis Cloud Trace

Exemple de trace de la pile et d'événement d'exception

Trace de la pile affichée depuis Cloud Trace

Événement d'exception affiché dans Cloud Trace

Étape suivante