Abilitare i segnali di telemetria nelle librerie client di Cloud per Java

Google Cloud offre funzionalità avanzate di monitoraggio, logging e diagnostica per le applicazioni Java.

Le librerie client Java sono strumentate per emettere dati di tracciamento, metriche e logging. L'instrumentazione è facoltativa, devi attivarla esplicitamente. Questo documento descrive gli indicatori disponibili e come attivarli.

Indicatori disponibili

I Golden Signals includono i seguenti dati di telemetria, in conformità con le convenzioni semantiche di OpenTelemetry:

  • Trace:trace HTTP/gRPC di basso livello che rappresentano le richieste di rete effettuate dalle librerie client.
  • Metriche:metriche delle richieste client, monitoraggio della latenza e dei tassi di richieste. La metrica principale è gcp.client.request.duration.
  • Log:log degli errori utilizzabili a livello di DEBUG, che forniscono dettagli sulle richieste non riuscite a livello di trasporto, anche se vengono riprovate in un secondo momento.

Gli indicatori includono attributi OpenTelemetry standard (ad esempio, http.response.status_code e rpc.system.name) e attributi personalizzati specifici di Google Cloud, che possono includere questi e attributi simili:

  • gcp.client.service: il nome del servizio (ad esempio, pubsub o storage).
  • gcp.client.repo: Il repository della libreria client (ad esempio, googleapis/google-cloud-java).
  • gcp.client.version: la versione della libreria client.
  • gcp.client.artifact: il percorso del modulo specifico (ad esempio, com.google.cloud:google-cloud-secretmanager).
  • gcp.resource.destination.id: l'ID della risorsa su cui viene eseguita l'azione.
  • gcp.errors.domain: il dominio di errore per i log degli errori azionabili.
  • gcp.errors.metadata.<key>: Chiavi dei metadati di errore aggiuntive per le richieste non riuscite (appiattite).

Per un elenco completo degli attributi standard, consulta le convenzioni semantiche HTTP e gRPC di OpenTelemetry.

Attivazione della telemetria

Per proteggere i dati sensibili, gli indicatori di telemetria sono disattivati per impostazione predefinita. Per attivarli, devi esplicitamente acconsentire.

Tracciamento e metriche

Nelle librerie client Java generate, devi attivare la tracciabilità e le metriche in modo programmatico fornendo la factory di tracciamento appropriata alle impostazioni del client durante l'inizializzazione:

  • Tracciamento:configura il client con un OpenTelemetryTracingFactory.
  • Metriche:configura il client con un OpenTelemetryMetricsFactory.
  • Entrambi:se vuoi attivare sia la tracciatura che le metriche, configura il client con un CompositeTracerFactory che includa entrambe le fabbriche.

Logging

I log degli errori utilizzabili sono integrati direttamente nel framework ApiTracer principale. Per attivare i log degli errori eseguibili a livello globale nelle librerie client Google Cloud, utilizza la seguente variabile di ambiente:

export GOOGLE_SDK_JAVA_LOGGING=true

Propagazione del contesto di Trace

La propagazione del contesto di Trace nelle librerie client Java richiede l'attivazione esplicita del tracciamento.

Quando la generazione di tracce è attivata (ad esempio configurando un OpenTelemetryTracingFactory) e la tua applicazione ha uno span OpenTelemetry attivo nel contesto corrente quando viene chiamato un metodo della libreria client, la libreria lo utilizza per fornire un contesto di tracciamento per le richieste in uscita. In questo modo, le tracce a livello di applicazione possono essere correlate ai log e ai comportamenti del servizio di backend.

Esportazione della telemetria

Una volta abilitata la telemetria nelle librerie client, l'applicazione deve essere configurata per raccogliere ed esportare questi dati nel backend di osservabilità.

Tracciamento e metriche

Per esportare le tracce e le metriche generate dalle librerie client Java, inizializza l'SDK OpenTelemetry con l'esportatore che preferisci (ad esempio, OTLP) e configura il propagatore della mappa di testo globale nella tua applicazione.

Per ulteriori dettagli sulla raccolta e l'esportazione dei dati OpenTelemetry in Cloud Monitoring o Cloud Trace, consulta Scegliere un approccio di strumentazione.

Logging

Le librerie client Java utilizzano framework di logging standard come SLF4J e java.util.logging. Quando GOOGLE_SDK_JAVA_LOGGING=true è impostato, i log degli errori azionabili vengono emessi a livello di DEBUG.

Per indirizzare questi log strutturati a Cloud Logging, configura il framework di logging (ad esempio Logback) per scrivere JSON nell'output standard (stdout). Se esegui il deployment in un ambiente come Google Kubernetes Engine o Cloud Run, gli agenti integrati eseguono automaticamente lo scraping di questi log.

Per istruzioni dettagliate sulla configurazione di Logback o java.util.logging per l'output di JSON compatibili con Cloud Logging, inclusa la correlazione delle tracce, consulta Configurare la registrazione strutturata per Java.