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 les bibliothèques clientes. 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 depuis le client, fournissent les informations suivantes :

  • Plages 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
  • Attributs (paires clé/valeur) qui fournissent des informations sur le client et sa configuration
  • Journaux associés aux événements clés dans les spans
  • Traces de pile en cas de plantage dans le client

OpenTelementry

Les traces des bibliothèques clientes sont instrumentées à l'aide des API OpenTelemetry. OpenTelemetry est un framework d'observabilité Open Source conforme aux normes 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 et des limites de portée.

Exporter des traces avec des exportateurs et des collecteurs

Dans 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, 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 gérer d'autres tâches telles que 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 étendues de trace sont disponibles pour les bibliothèques clientes Java et Node.js.
  • La bibliothèque cliente ne produit pas de spans de trace pour les écouteurs en temps réel.

Facturation

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

La collecte de traces et l'utilisation du framework OpenTelemetry sont gratuites.

L'ingestion de délais de trace dans votre backend d'observabilité peut être facturable. Par exemple, si vous utilisez Cloud Trace comme backend, vous serez 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 des traces (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
    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 les données 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 pour exporter les spans avec un taux 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();
Node.js (administrateur)

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
import pkg3 from "@opentelemetry/exporter-trace-otlp-grpc";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const { OTLPTraceExporter } =  pkg3;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limit
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// Add app code here

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});

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

Si votre fournisseur de services d'observabilité accepte l'ingestion OTLP, vous pouvez utiliser son exportateur OpenTelemetry pour exporter les traces directement vers son backend. Le code suivant configure la bibliothèque cliente pour exporter directement les spans de trace vers Cloud Trace avec un taux d'échantillonnage de trace de 10 %.

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();
Node.js (administrateur)

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limits
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new TraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// ...

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});

Instrumentation sans code

Suivez les instructions ci-dessous pour configurer les traces sans modifier le code :

Java (administrateur)
Vous pouvez configurer des traces sans modifier le code à l'aide d'agents automatiques. Vous devez définir la variable d'environnement FIRESTORE_ENABLE_TRACING=ON. Vous devez également définir d'autres paramètres de configuration, comme décrit dans Configuration de l'agent. Consultez les exemples suivants.

Exporter vers un collecteur avec des agents automatiques

Exécutez votre collecteur OpenTelemetry avec les récepteurs OTLP gRPC 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 le port localhost 4317. 


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 les 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 Exporter et un taux d'échantillonnage de trace de 10 %. 


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                                              \
Node.js (administrateur)

Pour configurer l'instrumentation sans code, suivez les instructions OpenTelemetry pour l'instrumentation JavaScript. L'extrait de code suivant active l'instrumentation et envoie des traces à un collecteur OpenTelemetry :


npm install @opentelemetry/api
npm install @opentelemetry/auto-instrumentations-node


env \
FIRESTORE_ENABLE_TRACING=ON \
OTEL_TRACES_EXPORTER=otlp \
OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,grpc" \
OTEL_NODE_RESOURCE_DETECTORS="none" \
node --require @opentelemetry/auto-instrumentations-node/register my_app.js

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 Attributs et événements de portée Trace.

Exemple de span de trace

Segment de trace affiché dans Cloud Trace

Exemple de journal des événements

Journal des événements d'un segment de trace affiché dans Cloud Trace

Exemples de valeurs d'attribut

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

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

Trace de pile affichée dans Cloud Trace

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

Étapes suivantes