Monitora le prestazioni con le tracce lato client

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Per monitorare e eseguire il debug delle richieste end-to-end di Firestore in modalità Datastore (Datastore), puoi attivare le tracce nella libreria client Java. 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 che indicano quando il client ha inviato la richiesta RPC e quando il client ha ricevuto la risposta RPC, inclusa la latenza introdotta dal di rete e del sistema client
• Attributi (coppie chiave/valore) che mostrano informazioni sul client e sulla sua configurazione.
• Log associati agli eventi chiave negli intervalli.
• Analisi dello stack se si verifica un arresto anomalo sul client.

OpenTelemetry

Le tracce per la libreria client Java vengono analizzate utilizzando API di 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, limiti di span e altro ancora.

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 raccoglitore corre accanto la tua applicazione. Il collector riceve i messaggi del protocollo OpenTelemetry (OTLP), li elabora e li esporta nel backend di observability.

Limitazioni

Gli intervalli di traccia sono disponibili solo per la libreria client Java.

Fatturazione

Oltre all'utilizzo di Datastore, 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 traccia	Ruolo IAM
  Leggere le tracce	roles/cloudtrace.user
  Scrivere le 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 esportare i dati in un raccoglitore o direttamente in un backend di osservabilità. Inoltre, hai a disposizione le seguenti opzioni per configurare le tracce lato client:

• Puoi configurare le tracce con le API OpenTelemetry. Richiede codice modifiche alla tua applicazione. Vedi i seguenti esempi:
  • Esportare in un Collector con le API OpenTelemetry
  • Eseguire l'esportazione direttamente in un backend di osservabilità con le API OpenTelemetry
• Puoi configurare le tracce senza modifiche al codice utilizzando gli agenti automatici. Devi imposta la variabile di ambiente DATASTORE_ENABLE_TRACING=ON. Devi anche configurare altre impostazioni di configurazione come descritto in Configurazione agente. Vedi i seguenti esempi:
  • Esportare in un raccoglitore con gli agenti automatici
  • Esporta direttamente in un backend di osservabilità con Agenti automatici

Esportare le tracce in un Collector con le API OpenTelemetry

Il codice seguente configura la libreria client Java di Datastore per esportare intervalli con un rapporto di campionamento del 10% in un collettore 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();

    

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

Il seguente codice configura la libreria client Java per esportare direttamente gli intervalli di traccia in Cloud Trace con un rapporto di campionamento delle tracce del 10%. Puoi utilizzare la modalità altri fornitori di servizi di osservabilità di esportare direttamente nei propri di un backend cloud. Se il tuo backend di osservabilità supporta l'importazione di OTLP, puoi utilizzare OpenTelemetry OtlpGrpcSpanExporter per esportare nel tuo backend anziché utilizzare un esportatore personalizzato.

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

    

Esportare in un collettore 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.

Terminale

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

    

Esporta direttamente in un backend di observability con gli agenti automatici

Oltre a impostare la variabile di ambiente DATASTORE_ENABLE_TRACING=ON, devi aggiungere l'estensione dell'agente Java OpenTelemetry per il tuo di un backend cloud. L'esempio seguente utilizza l'estensione Esportatore di trace e un rapporto di campionamento delle trace del 10%.

Terminale

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

    

Traccia di esempio

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

Esempio di intervallo di traccia

Esempio di log eventi

Valori di attributo di esempio

Passaggi successivi

• Visualizza il riferimento per gli eventi e gli attributi dell'intervallo traccia.
• Scopri di più sul monitoraggio lato server.