Monitorare il rendimento con le tracce lato client

Per monitorare e eseguire il debug delle richieste Firestore end-to-end, puoi attivare le tracce nelle librerie client. Il monitoraggio lato client può fornire un indicazione sulle prestazioni registrate dalla tua applicazione, nonché approfondimenti che possono essere utili per la risoluzione dei problemi di debug.

Le tracce lato client, che vengono raccolte eseguendo RPC dal client, forniscono le seguenti informazioni:

  • Intervalli con timestamp del momento in cui il client ha inviato la richiesta RPC e del momento in cui il client ha ricevuto la risposta RPC, inclusa la latenza introdotta dalla rete e dal sistema client
  • Attributi (coppie chiave/valore) che mostrano informazioni sul cliente e sulla sua configurazione
  • Log associati agli eventi chiave negli intervalli
  • Tracce dello stack se si verifica un arresto anomalo nel client

OpenTelemetry

Le tracce per le librerie client vengono instrumentate utilizzando le API OpenTelemetry. OpenTelemetry è un framework di osservabilità open source standard di settore. OpenTelemetry offre una vasta gamma di strumenti, come API di misurazione e SDK, collector, esportatori specifici per il backend e opzioni di configurazione flessibili come controlli di campionamento e limiti di intervallo.

Esportare le tracce con gli esportatori e i collector

Nell'ambito delle configurazioni, puoi esportare le tracce in un backend di osservabilità. La maggior parte dei provider di servizi di osservabilità offre esportatori da utilizzare, ad esempio Cloud Trace.

Oltre a un esportatore, OpenTelemetry consiglia di configurare un raccoglitore. Un raccoglitore consente al tuo servizio di scaricare rapidamente i dati e di occuparsi di ulteriori operazioni di gestione come i tentativi di nuovo invio, l'aggregazione e la crittografia. Un Collector viene eseguito insieme alla tua applicazione. Il collector riceve i messaggi OTLP, li elabora e li esporta nel backend di observability.

Limitazioni

Le tracce lato client presentano le seguenti limitazioni:

  • Gli span di traccia sono disponibili per le librerie client Java e Node.js.
  • La libreria client non produce intervalli di traccia per gli ascoltatori in tempo reale.

Fatturazione

Oltre all'utilizzo di Firestore, il monitoraggio lato client può comportare costi.

Non sono previsti costi per la raccolta delle tracce o l'utilizzo del framework OpenTelemetry.

L'importazione degli intervalli di traccia nel backend di observability potrebbe essere fatturabile. Ad esempio, se utilizzi Cloud Trace come backend, ti viene addebitato in base ai prezzi di Cloud Trace. Se utilizzi un altro fornitore di servizi di osservabilità, scopri il suo modello di fatturazione e i costi associati.

Per comprendere meglio la fatturazione, inizia con un rapporto di campionamento delle tracce ridotto (traccia una piccola percentuale delle RPC) in base al tuo traffico.

Prima di iniziare

Prima di iniziare:

  • Assicurati di configurare l'account di servizio in cui la tua app scrive le tracce nel backend di observability con i ruoli di Identity and Access Management necessari:

    Operazione di Trace Ruolo IAM
    Leggere le tracce roles/cloudtrace.user
    Scrivere tracce roles/cloudtrace.agent
    Tracce di lettura/scrittura roles/cloudtrace.admin
  • Verifica che l'API Trace sia abilitata in questo progetto.

Configura le tracce lato client

Questa sezione fornisce configurazioni di esempio per le tracce lato client. Puoi eseguire l'esportazione in un Collector o direttamente in un backend di osservabilità. Inoltre, hai a disposizione le seguenti opzioni per configurare le tracce lato client:

Esportare le tracce in un Collector con le API OpenTelemetry

Il seguente codice configura la libreria client per esportare gli span con una frequenza di campionamento del 10% in un OpenTelemetry Collector.

Java (amministratore)

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 (amministratore)

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));
});
    

Esporta direttamente in un backend di osservabilità con le API OpenTelemetry

Se il tuo fornitore di servizi di osservabilità supporta l'importazione di OTLP, puoi utilizzare il suo esportatore OpenTelemetry per esportare le tracce direttamente nel suo backend. Il seguente codice configura la libreria client per esportare direttamente gli intervalli di traccia in Cloud Trace con un rapporto di campionamento delle tracce del 10%.

Java (amministratore)

// 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 (amministratore)

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));
});
    

Strumentazione senza codice

Per configurare le tracce senza modifiche al codice, segui le istruzioni riportate di seguito:

Java (amministratore)
Puoi configurare le tracce senza modifiche al codice utilizzando gli agenti automatici. Devi impostare la variabile di ambiente FIRESTORE_ENABLE_TRACING=ON. Inoltre, devi impostare altre impostazioni di configurazione come descritto in Configurazione dell'agente. Vedi i seguenti esempi.

Esportare in un raccoglitore con agenti automatici

Esegui OpenTelemetry Collector con i ricevitori gRPC OTLP abilitati. Imposta l'esportatore dell'agente su otlp e specifica l'endpoint in cui l'agente deve esportare i dati. L'esempio seguente utilizza un rapporto di campionamento del 10% e invia le tracce al Collector in ascolto sulla porta 4317 di localhost.


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

Esporta direttamente in un backend di observability con gli agenti automatici

Oltre a impostare la variabile di ambiente FIRESTORE_ENABLE_TRACING=ON, devi aggiungere l'estensione dell'agente Java OpenTelemetry per il tuo backend specifico. L'esempio seguente utilizza l'estensione Esportatore di trace e un rapporto di campionamento delle tracce del 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 (amministratore)

Per configurare la misurazione senza codice, segui le istruzioni di OpenTelemetry per la misurazione di JavaScript. Il seguente snippet di codice di esempio attiva la strumentazione e invia le tracce a un collettore OpenTelemetry:


npm install --save @opentelemetry/api
npm install --save @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

    

Traccia di esempio

Gli esempi riportati di seguito mostrano come vengono visualizzate le informazioni sulle tracce in Cloud Trace. Per ulteriori informazioni su possibili attributi e valori, consulta Attributi ed eventi dell'intervallo di traccia.

Esempio di intervallo di traccia

Un intervallo di traccia visualizzato da Cloud Trace

Log eventi di esempio

Un log degli eventi dell'intervallo di traccia visualizzato da Cloud Trace

Valori di attributo di esempio

Valori degli attributi di un intervallo di traccia visualizzato da Cloud Trace

Esempio di analisi dello stack ed evento di eccezione

Un'analisi dello stack visualizzata da Cloud Trace

Un evento di eccezione visualizzato da Cloud Trace

Passaggi successivi