Generare tracce e metriche con Java

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". Questo 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 dall'utilizzo o meno del framework Spring Boot.

Per scoprire di più sulla misurazione, consulta i seguenti documenti:

Informazioni sulla misurazione 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 misurazione automatica può raccogliere la telemetria per elementi come le chiamate HTTP in entrata e in uscita. Per ulteriori informazioni, vedi Strumentazione automatica per Java.

OpenTelemetry fornisce anche un'API per aggiungere strumenti di misurazione personalizzati al tuo codice. OpenTelemetry la definisce strumentazione manuale. Questo documento non descrive la strumentazione manuale. Per esempi e informazioni su questo argomento, consulta la sezione Strumentazione manuale.

Prima di iniziare

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Instrumenta l'app per raccogliere tracce, metriche e log

Per eseguire l'instrumentazione dell'app in modo da raccogliere dati sulle metriche e sulle tracce e scrivere JSON strutturato nello standard output, svolgi i seguenti passaggi come descritto nelle sezioni successive di questo documento:

  1. Configura l'app per l'utilizzo dell'agente Java OpenTelemetry
  2. Configurare OpenTelemetry
  3. Configurare il logging strutturato
  4. Scrivere log strutturati

Configura l'app per l'utilizzo dell'agente Java OpenTelemetry

Per configurare l'app in modo che scriva log strutturati e raccolga metriche e dati traccia utilizzando OpenTelemetry, aggiorna l'invocazione dell'app in modo che utilizzi l'agente Java OpenTelemetry. Questo metodo di strumentazione della tua app è nota come strumentazione automatica perché non richiede la modifica il codice dell'app.

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

Per visualizzare l'esempio completo, fai clic su Altro e poi 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 per utilizzando il protocollo OTLP. Inoltre, configura OpenTelemetry in modo da utilizzare il formato W3C Trace Context per propagare il contesto della traccia. Questa configurazione garantisce che gli intervalli abbiano la relazione padre-figlio corretta all'interno di una traccia.

Per ulteriori informazioni e opzioni di configurazione, consulta la strumentazione automatica Java di OpenTelemetry.

Configurare il logging strutturato

Per includere le informazioni sulla traccia all'interno dei log in formato JSON scritti nell'output standard, configura l'app in modo da generare log strutturati in formato JSON. 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 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

  Since log4j2 2.24.0, GcpLayout.json already includes trace context logging from MDC and
  the below additional fields are no longer needed -->
  <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 informazioni sull'intervallo attivo il Contesto diagnostico mappato di SLF4J e aggiunge queste informazioni come attributi nel log. Questi attributi possono essere utilizzati per correlare un log con 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 associata alla voce di log.
  • logging.googleapis.com/trace_sampled: il valore di questo campo deve essere true o false.

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 l'elemento 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 corrente nel contesto OpenTelemetry. Il contesto diagnostico mappato viene poi incluso nei log JSON come descritto in Configurare il logging strutturato.

Esegui un'app di esempio configurata per raccogliere la 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 funzione handleMulti. 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.

    /**
 * 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, entra in modalità di sospensione per un breve periodo di tempo e poi 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 il sample:

  1. In the Google Cloud console, activate Cloud Shell.

    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.

  2. Clona il repository:

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java

  3. Vai alla directory di esempio:

    cd opentelemetry-operations-java/examples/instrumentation-quickstart

  4. Crea ed esegui il sample:

    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 al server e memorizza i risultati in un istogramma.

  • Prometheus/http_client_duration_milliseconds/histogram registra la durata delle richieste del client e memorizza i risultati in un istogramma.

Per visualizzare le metriche generate dall'app di esempio, procedi nel seguente modo:

  1. 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.

  2. 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:
    1. Nel menu Risorse attive, seleziona Destinazione Prometheus.
    2. Nel menu Categorie di metriche attive, seleziona Http.
    3. Seleziona una metrica nel menu Metriche attive.
    4. Fai clic su Applica.
  3. Configura la 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 per le route HTTP /multi e /single, imposta il primo menu della voce Aggregazione su Nessuna.

    Per ulteriori informazioni sulla configurazione di un grafico, consulta Selezionare le metriche durante l'utilizzo di Metrics Explorer.

Visualizza le tue tracce

Per visualizzare i dati di traccia, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Esplora tracce.

    Vai a Trace Explorer

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nel grafico a dispersione, seleziona una traccia con l'URI /multi.

  3. Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona l'intervallo contrassegnato come /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.

  4. 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, 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

Da Esplora log, puoi ispezionare i log e anche visualizzare le tracce associate, se esistono.

  1. Nella console Google Cloud, vai alla pagina Esplora log:

    Vai a Esplora log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Individua un log con la descrizione di handle /multi request.

    Per visualizzare i dettagli del log, espandi la voce di log.

  3. Fai clic su Tracce in una voce di log con il messaggio "handle /multi request", quindi seleziona Visualizza dettagli traccia.

    Si apre un riquadro Dettagli traccia che mostra la traccia selezionata.

Per ulteriori informazioni sull'uso di Esplora log, consulta Visualizza i log utilizzando Esplora log.

Passaggi successivi