Questa pagina è stata tradotta dall'API Cloud Translation.

Genera tracce e metriche con Java

Questo documento descrive come modificare un'app Java per raccogliere dati di traccia e metriche utilizzando il framework open source OpenTelemetry e come scrivere log JSON strutturati allo standard out. Questo documento fornisce anche 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 sulla strumentazione automatica OpenTelemetry per inviare dati di telemetria al tuo progetto Google Cloud. Per Java, con strumentazione automatica si intende la pratica di inserire dinamicamente il bytecode nelle librerie e nei framework per acquisire la telemetria. La strumentazione automatica può raccogliere dati di telemetria per elementi come le chiamate HTTP in entrata e in uscita. Per maggiori informazioni, consulta Strumentazione automatica per Java.

OpenTelemetry fornisce anche un'API per aggiungere strumentazione personalizzata al 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.

Abilita le API

Instrumenta la tua app per raccogliere tracce, metriche e log

Per consentire all'app di raccogliere dati di traccia e metriche e scrivere un file JSON strutturato in un formato standard, esegui i passaggi riportati di seguito, come descritto nelle sezioni successive di questo 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

Per configurare l'app per la scrittura di log strutturati e per raccogliere metriche e dati di traccia utilizzando OpenTelemetry, aggiorna la chiamata dell'app in modo che utilizzi l'agente Java OpenTelemetry. Questo metodo di strumentazione della tua app è noto come strumentazione automatica perché non richiede la modifica del codice dell'app.

L'esempio di codice seguente illustra un Dockerfile che scarica il file JAR dell'agente Java OpenTelemetry e aggiorna la chiamata della riga di comando per passare il flag -javaagent.

Per visualizzare l'esempio completo, fai clic su Altro, quindi seleziona Visualizza su GitHub.

RUN wget -O /opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.31.0/opentelemetry-javaagent.jar
CMD sh -c "java -javaagent:/opentelemetry-javaagent.jar -cp app:app/lib/* com.example.demo.DemoApplication \
	2>&1 | tee /var/log/app.log"

In alternativa, puoi anche impostare il flag -javaagent nella variabile di ambiente JAVA_TOOL_OPTIONS:

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"

Configura OpenTelemetry

La configurazione predefinita per l'agente Java OpenTelemetry esporta tracce e metriche utilizzando il protocollo OTLP. Configura inoltre OpenTelemetry per l'utilizzo del formato Contesto di traccia W3C per la propagazione del contesto delle tracce. 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 Strumentazione automatica Java di OpenTelemetry.

Configura il logging strutturato

Per includere le informazioni di traccia nei log in formato JSON scritti nell'output standard, configura la tua app per l'output di log strutturati in formato JSON. Ti consigliamo di utilizzare Log4j2 come implementazione di logging. Il seguente esempio di codice illustra un file log4j2.xml configurato per generare log strutturati JSON utilizzando il layout del modello JSON:

<!-- Format JSON logs for the Cloud Logging agent
https://cloud.google.com/logging/docs/structured-logging#special-payload-fields -->

<!-- Log4j2's JsonTemplateLayout includes a template for Cloud Logging's special JSON fields
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#event-templates -->
<JsonTemplateLayout eventTemplateUri="classpath:GcpLayout.json">
  <!-- Extend the included GcpLayout to include the trace and span IDs from Mapped
  Diagnostic Context (MDC) so that Cloud Logging can correlate Logs and Spans -->
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace"
    format="JSON"
    value='{"$resolver": "mdc", "key": "trace_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/spanId"
    format="JSON"
    value='{"$resolver": "mdc", "key": "span_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace_sampled"
    format="JSON"
    value="true"
  />
</JsonTemplateLayout>

La configurazione precedente estrae le informazioni sull'intervallo attivo dal Contesto diagnostico mappato di SLF4J e le aggiunge come attributi al log. Questi attributi possono quindi essere utilizzati per correlare un log a una traccia:

logging.googleapis.com/trace: nome risorsa della traccia associata alla voce di log.
logging.googleapis.com/spanId: l'ID intervallo con la traccia associata alla voce di log.
logging.googleapis.com/trace_sampled: il valore di questo campo deve essere true o false.

Per ulteriori informazioni su questi campi, consulta la struttura di LogEntry.

Scrittura di log strutturati

Per scrivere log strutturati che si collegano a una traccia, utilizza l'API di logging SLF4J. Ad esempio, la seguente istruzione mostra come chiamare il metodo 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 dell'intervallo dell'intervallo attivo attuale in Contesto OpenTelemetry. Il contesto diagnostico mappato viene quindi incluso nei log JSON, come descritto in Configurare il logging strutturato.

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 Spring Boot. Per instradare la telemetria a Google Cloud, questo esempio utilizza il valore OpenTelemetry Collector configurato con gli esportatori Google. L'app ha due endpoint:

L'endpoint /multi è gestito dalla funzione handleMulti. Il generatore di carico nell'app invia richieste all'endpoint /multi. Quando questo endpoint riceve una richiesta, invia da tre a sette richieste all'endpoint /single sul server locale.

/**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/multi")
public Mono<String> handleMulti() throws Exception {
  int subRequests = ThreadLocalRandom.current().nextInt(3, 8);

  // Write a structured log with the request context, which allows the log to
  // be linked with the trace for this request.
  logger.info("handle /multi request with subRequests={}", subRequests);

  // Make 3-7 http requests to the /single endpoint.
  return Flux.range(0, subRequests)
      .concatMap(
          i -> client.get().uri("http://localhost:8080/single").retrieve().bodyToMono(Void.class))
      .then(Mono.just("ok"));
}

L'endpoint /single è gestito dalla funzione handleSingle. Quando questo endpoint riceve una richiesta, dorme per un breve ritardo e risponde con una stringa.

/**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/single")
public String handleSingle() throws InterruptedException {
  int sleepMillis = ThreadLocalRandom.current().nextInt(100, 200);
  logger.info("Going to sleep for {}", sleepMillis);
  Thread.sleep(sleepMillis);
  logger.info("Finishing the request");
  return String.format("slept %s\n", sleepMillis);
}

Scarica ed esegui il deployment dell'app

Per eseguire l'esempio, segui questi passaggi:

Nella console Google Cloud, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

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 è in esecuzione su Cloud Shell, esegui l'applicazione con la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS che punta a un file delle credenziali. Credenziali predefinite dell'applicazione 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 metriche Prometheus che puoi visualizzare utilizzando Metrics Explorer:

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.

Per visualizzare le metriche generate dall'app di esempio:

Nella console Google Cloud, vai alla pagina Esplora metriche:
Vai a 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 e utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
1. Nel menu Risorse attive, seleziona Target Prometheus.
2. Nel menu Categorie di metriche attive, seleziona Http.
3. Seleziona una metrica nel menu Metriche attive.
4. Fai clic su Applica.
Configura la modalità di visualizzazione dei dati.
Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, il che genera la visualizzazione del grafico nel grafico. Per ulteriori informazioni, consulta Tipi, tipi e conversioni.

Quando vengono misurati valori interi o doppi, ad esempio con le due metriche 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 Aggregazione su Nessuna.

Per saperne di più sulla configurazione di un grafico, consulta Selezionare le metriche quando si utilizza Esplora metriche.

Visualizza le tue tracce

Per visualizzare i dati di traccia, segui questi passaggi:

Nella console Google Cloud, vai alla pagina Esplora tracce.
Vai a Trace Explorer

Puoi trovare questa pagina anche utilizzando la barra di ricerca.
Nel grafico a dispersione, seleziona una traccia con URI /multi.
Nel grafico di Gantt nel riquadro Dettagli traccia, seleziona l'intervallo con l'etichetta /multi.

Si apre un riquadro che mostra informazioni sulla richiesta HTTP. Questi dettagli includono il metodo, il codice di stato, il numero di byte e lo user agent del chiamante.
Per visualizzare i log associati a questa traccia, seleziona la scheda Log ed eventi.

La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandila. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

Per ulteriori informazioni sull'utilizzo di Explorer di Cloud Trace, consulta Trovare ed esplorare le tracce.

visualizza i log

Da Esplora log puoi esaminare i log e puoi anche visualizzare le tracce associate, se presenti.

Nella console Google Cloud, vai alla pagina Esplora log:
Vai a Esplora log

Se usi 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 il messaggio "handle /multi-richiesta", 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 Visualizzare i log con Esplora log.