Questo documento descrive come modificare un'app Java per raccogliere tracce e dati delle metriche utilizzando il framework open source OpenTelemetry e come e scrivere log JSON strutturati su "Standard-out". Il presente documento fornisce inoltre informazioni su un'app Java Spring Boot di esempio che puoi installare ed eseguire. L'app è configurata per generare metriche, tracce e log. I passaggi sono gli stessi indipendentemente dal fatto che utilizzi o meno il framework di avvio a molla.
Per saperne di più sulla strumentazione, consulta i seguenti documenti:
Informazioni sulla strumentazione manuale e automatica
La strumentazione descritta in questo documento si basa su OpenTelemetry la strumentazione automatica per inviare dati di telemetria al tuo progetto Google Cloud. Per Java, per strumentazione automatica si intende la pratica della inserendo in modo dinamico il bytecode nelle librerie e nei framework per acquisire la telemetria. La strumentazione automatica può raccogliere dati di telemetria per cose come chiamate HTTP in entrata e in uscita. Per ulteriori informazioni, vedi Strumentazione automatica per Java.
OpenTelemetry fornisce anche un'API per aggiungere strumentazione personalizzata a il tuo codice. Con OpenTelemetry, si parla di strumentazione manuale. Questo documento non descrive la strumentazione manuale. Per esempi e informazioni su questo argomento, consulta la sezione Strumentazione manuale.
Prima di iniziare
Abilita le API Cloud Logging, Cloud Monitoring, and Cloud Trace.
Instrumenta la tua app per raccogliere tracce, metriche e log
Per instrumentare l'app in modo che raccolga dati relativi a tracce e metriche e per scrivere da JSON strutturato a Standard Out, esegui i seguenti passaggi come descritto nelle sezioni successive del presente documento:
- Configura l'app per l'utilizzo dell'agente Java OpenTelemetry
- Configurare OpenTelemetry
- Configurare il logging strutturato
- Scrivere log strutturati
Configura l'app per l'utilizzo dell'agente Java OpenTelemetry
Configurare l'app per la scrittura di log strutturati e la raccolta di metriche e tracce di dati utilizzando OpenTelemetry, aggiorna la chiamata dell'app in modo da utilizzare Agente Java OpenTelemetry. Questo metodo di strumentazione della tua app è nota come strumentazione automatica perché non richiede la modifica il codice dell'app.
L'esempio di codice seguente illustra un Dockerfile che scarica il file
il file JAR dell'agente Java OpenTelemetry e aggiorna la chiamata alla riga di comando per passare
-javaagent
flag.
Per visualizzare l'anteprima completa, fai clic su more_vert Altro, quindi seleziona Visualizza su GitHub.
In alternativa, puoi anche impostare il flag -javaagent
in JAVA_TOOL_OPTIONS
variabile di ambiente:
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
Configura OpenTelemetry
La configurazione predefinita per l'agente Java OpenTelemetry esporta tracce e metriche per utilizzando il protocollo OTLP. Inoltre, configura OpenTelemetry per l'utilizzo Formato Contesto traccia W3C per la propagazione della traccia contesto. Questa configurazione garantisce che gli intervalli abbiano la corretta relazione padre-figlio all'interno di una traccia.
Per ulteriori informazioni e opzioni di configurazione, vedi OpenTelemetry Java automatico dei dati.
Configura il logging strutturato
per includere le informazioni di traccia all'interno dei log in formato JSON scritti in
standard output, configura la tua app per l'output di log strutturati in JSON
formato. Ti consigliamo di utilizzare Log4j2 come implementazione di logging.
L'esempio di codice seguente illustra un file log4j2.xml
configurato per l'output
Log strutturati JSON con il layout del modello JSON:
La configurazione precedente estrae informazioni sull'intervallo attivo il Contesto diagnostico mappato di SLF4J e aggiunge queste informazioni come attributi nel log. Questi attributi possono quindi essere utilizzati per correlare un log a una traccia:
logging.googleapis.com/trace
: nome risorsa della traccia associata a la voce di log.logging.googleapis.com/spanId
: l'ID intervallo con la traccia che è associati alla voce di log.logging.googleapis.com/trace_sampled
: il valore di questo campo deve esseretrue
ofalse
.
Per saperne di più su questi campi, consulta la LogEntry
alla struttura del centro di costo.
Scrittura di log strutturati
Per scrivere log strutturati che si collegano a una traccia, utilizza il logging SLF4J
tramite Google Cloud CLI
o tramite l'API Compute Engine. Ad esempio, la seguente istruzione mostra come chiamare Logger.info()
:
logger.info("handle /multi request with subRequests={}", subRequests);
L'agente Java OpenTelemetry compila automaticamente il contesto diagnostico mappato di SLF4J con il contesto di intervallo dell'intervallo attivo corrente nel Contesto OpenTelemetry. Il contesto diagnostico mappato viene quindi incluso nei log JSON come descritto in Configurare i modelli il logging.
Esegui un'app di esempio configurata per raccogliere dati di telemetria
L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP
per metriche e tracce e il framework di avvio a molla. Al percorso
la telemetria a Google Cloud, questo esempio utilizza il valore Collector
di OpenTelemetry
configurate con gli esportatori Google. L'app ha due endpoint:
L'endpoint
/multi
è gestito dalla funzionehandleMulti
. Il carico nell'app invia richieste all'endpoint/multi
. Quando questo quando un endpoint riceve una richiesta, invia da 3 a 7 l'endpoint/single
sul server locale.L'endpoint
/single
è gestito dalla funzionehandleSingle
. Quando questo endpoint riceve una richiesta, dorme per un breve ritardo e poi risponde con una stringa.
Scarica ed esegui il deployment dell'app
Per eseguire l'esempio, segui questi passaggi:
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Clona il repository:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java
Vai alla directory di esempio:
cd opentelemetry-operations-java/examples/instrumentation-quickstart
Crea ed esegui l'esempio:
docker compose up --abort-on-container-exit
Se non stai utilizzando Cloud Shell, esegui l'applicazione con
GOOGLE_APPLICATION_CREDENTIALS
variabile di ambiente che punta a una delle credenziali. App predefinita Credenziali fornisce un file di credenziali all'indirizzo$HOME/.config/gcloud/application_default_credentials.json
.# Set environment variables export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" export USERID="$(id -u)" # Run docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
Visualizzare le metriche
La strumentazione OpenTelemetry nell'app di esempio genera Prometheus che puoi visualizzare utilizzando Esplora metriche:
Prometheus/http_server_duration_milliseconds/histogram
registra la durata delle richieste del server e archivia i risultati in un istogramma.Prometheus/http_client_duration_milliseconds/histogram
registra la durata delle richieste del client e archivia i risultati in un istogramma.
-
Nella console Google Cloud, vai alla pagina leaderboard Esplora metriche:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- Nell'elemento Metrica, espandi il menu Seleziona una metrica,
inserisci
http_server
nella barra dei filtri, poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:- Nel menu Risorse attive, seleziona Target Prometheus.
- Nel menu Categorie di metriche attive, seleziona Http.
- Seleziona una metrica nel menu Metriche attive.
- Fai clic su Applica.
- Configura la modalità di visualizzazione dei dati.
Quando le misurazioni di una metrica sono cumulativi, Metrics Explorer normalizza automaticamente i dati misurati il periodo di allineamento, che determina la visualizzazione di un tasso nel grafico. Per per saperne di più, consulta Tipi, tipi e conversioni.
Quando vengono misurati valori interi o doppi, ad esempio con i due valori
counter
, Metrics Explorer somma automaticamente tutte le serie temporali. Per visualizzare i dati relativi alle route HTTP/multi
e/single
, imposta il primo menu della voce Aggregation su None.Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche quando utilizzi Esplora metriche.
Visualizza le tue tracce
Per visualizzare i dati di traccia, segui questi passaggi:
-
Nella console Google Cloud, vai alla pagina Esplora tracce.
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
- Nel grafico a dispersione, seleziona una traccia con URI
/multi
. Nel grafico di Gantt, all'interno del riquadro Dettagli traccia, seleziona l'intervallo con l'etichetta
/multi
.Si apre un riquadro che mostra informazioni sulla richiesta HTTP. Questi tra cui metodo, codice di stato, numero di byte e e lo user agent del chiamante.
Per visualizzare i log associati a questa traccia, seleziona Log e Eventi.
La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandere la voce di log. Puoi anche fare clic su Visualizza log e visualizzare il log. mediante Esplora log.
Per ulteriori informazioni sull'utilizzo di Explorer di Cloud Trace, consulta Trovare ed esplorare le tracce.
Visualizza i log
In Esplora log puoi esaminare i log e anche visualizzare le tracce associate, se presenti.
-
Nella console Google Cloud, vai alla pagina Esplora log:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
Individua un log con la descrizione di
handle /multi request
.Per visualizzare i dettagli del log, espandi la voce di log.
Fai clic su
Tracce in una voce di log con "handle /multirichiesta" quindi seleziona Visualizza dettagli traccia.
Si apre un riquadro Dettagli traccia che mostra la traccia selezionata.
Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizza i log utilizzando Esplora log.
Passaggi successivi
- OpenTelemetry
- Specifiche OTLP
- Logging strutturato
- Risoluzione dei problemi di Managed Service per Prometheus
- Risolvi i problemi di Cloud Trace