Monitorare il rendimento con le tracce lato client

Monitorare il rendimento 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 Firestore end-to-end, 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 cliente e sulla sua configurazione
• Log associati agli eventi chiave negli intervalli
• Analisi dello stack se si verifica un arresto anomalo nel client

OpenTelemetry

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

Esporta tracce con esportatori e raccoglitori

Nell'ambito delle configurazioni, puoi esportare le tracce in e 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 una Raccoglitore. Un raccoglitore ti consente di servizio scarica i dati rapidamente e il raccoglitore si occupa di per la gestione di nuovi tentativi, batch e crittografia. Un raccoglitore corre accanto la 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 intervalli di traccia sono disponibili per la libreria client Java.
• La libreria client non produce intervalli di traccia per i 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, e fatturati in base ai prezzi di Cloud Trace. Se utilizzi un altro fornitore di servizi di osservabilità, scopri il suo modello di fatturazione e costi associati.

Per comprendere meglio la fatturazione, inizia con un piccolo rapporto di campionamento della traccia (traccia una piccola percentuale delle tue RPC) in base sul 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
  Scrittura 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. Ciò richiede modifiche al codice della tua applicazione. Vedi i seguenti esempi:
  • Esportare in un Collector con le API OpenTelemetry
  • Esporta direttamente in un backend di osservabilità con le API OpenTelemetry
• Puoi configurare le tracce senza modifiche al codice utilizzando gli agenti automatici. Devi impostare la variabile di ambiente FIRESTORE_ENABLE_TRACING=ON. Devi anche impostare altre impostazioni di configurazione come descritto in Configurazione dell'agente. Vedi i seguenti esempi:
  • Esportare in un raccoglitore con gli agenti automatici
  • Esportare direttamente in un backend di osservabilità con gli agenti automatici

Esporta le tracce in un raccoglitore con le API OpenTelemetry

Il codice seguente configura la libreria client Java di Firestore per esportare intervalli con un rapporto di campionamento del 10% in un collettore OpenTelemetry.

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.
OpenTelemetry otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpaaudit-loggingnProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build());

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

    

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

Il codice seguente configura la libreria client Java per esportare direttamente la traccia si estende a Cloud Trace con un rapporto di campionamento della traccia del 10%. Puoi utilizzare gli esportatori di altri fornitori di servizi di osservabilità per esportare direttamente nel loro backend. Se il backend di osservabilità supporta l'importazione OTLP, puoi utilizzare OpenTelemetry OtlpGrpcSpanExporter per eseguire l'esportazione nel tuo backend anziché utilizzare un esportatore personalizzato.

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
OpenTelemetry otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build());

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

    

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.

Terminale

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 osservabilità con agenti automatici

Oltre a impostare la variabile di ambiente FIRESTORE_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 traccia e un rapporto di campionamento delle tracce del 10%.

Terminale

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                                              \

    

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

Esempio di analisi dello stack ed evento di eccezione

Passaggi successivi

• Visualizza la documentazione di riferimento per gli eventi e gli attributi degli intervalli di traccia
• Scopri di più sul monitoraggio lato server