Monitorare il rendimento con le tracce lato client

Per monitorare ed eseguire il debug delle richieste di Firestore in modalità Datastore (Datastore) end-to-end, puoi attivare le tracce nella libreria client Java. Il tracciamento lato client può fornire un segnale sulle prestazioni sperimentate dalla tua applicazione, nonché informazioni che possono aiutarti a eseguire il debug dei problemi.

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

  • Span con timestamp di quando il client ha inviato la richiesta RPC e quando 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 client e sulla sua configurazione.
  • Log associati agli eventi chiave negli intervalli.
  • Stack trace se si verifica un arresto anomalo sul 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 un'ampia gamma di strumenti, come API e SDK di strumentazione, raccoglitori, esportatori specifici per il backend e opzioni di configurazione flessibili, come controlli di campionamento, limiti di span e altro ancora.

Esportare le tracce con esportatori e raccoglitori

Nell'ambito delle configurazioni, puoi esportare le tracce in un backend di osservabilità. La maggior parte dei fornitori 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 gestire ulteriori operazioni come i nuovi tentativi, il batching e la crittografia. Un Collector viene eseguito insieme alla tua applicazione. Il collettore riceve messaggi OTLP (OpenTelemetry Protocol), li elabora e li esporta nel backend di osservabilità.

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 di intervalli di traccia nel backend di osservabilità potrebbe essere fatturabile. Ad esempio, se utilizzi Cloud Trace come backend, ti viene addebitato l'utilizzo 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 piccolo rapporto di campionamento delle tracce (traccia una piccola percentuale delle tue RPC) in base al tuo traffico.

Prima di iniziare

Prima di iniziare:

  • Assicurati di configurare il account di servizio con cui la tua app scrive le tracce nel backend di osservabilità con i ruoli Identity and Access Management necessari:

    Operazione di Trace Ruolo IAM
    Lettura delle tracce roles/cloudtrace.user
    Scrittura delle 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 esempi di configurazioni per le tracce lato client. Puoi esportare in un Collector o direttamente in un backend di osservabilità. Hai anche 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 Java di Datastore per esportare gli span 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 span di traccia in Cloud Trace con un rapporto di campionamento delle tracce 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 esportare nel 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 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 che è in ascolto sulla porta localhost 4317.

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

Esportare direttamente in un backend di osservabilità 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 backend specifico. L'esempio seguente utilizza l'estensione dell'esportatore di tracce e un rapporto di campionamento delle tracce 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

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

Esempio di intervallo di traccia

Un intervallo di traccia visualizzato da Cloud Trace.

Log eventi di esempio

Un log eventi di intervallo di traccia visualizzato da Cloud Trace.

Valori degli attributi di esempio

Valori degli attributi di un intervallo di traccia visualizzati da Cloud Trace.

Passaggi successivi