Esta página se ha traducido con Cloud Translation API.

Ejemplo de instrumentación de Java

En este documento se describe cómo modificar una aplicación Java para recoger datos de trazas y métricas mediante el framework de código abierto OpenTelemetry, así como escribir registros JSON estructurados en la salida estándar. En este documento también se proporciona información sobre una aplicación de ejemplo de Java Spring Boot que puedes instalar y ejecutar. La aplicación está configurada para generar métricas, trazas y registros. Los pasos son los mismos tanto si usas el framework Spring Boot como si no.

Para obtener más información sobre la instrumentación, consulta los siguientes documentos:

Información sobre la instrumentación manual y sin código

La instrumentación descrita en este documento se basa en la instrumentación de código cero de OpenTelemetry para enviar telemetría a tu proyecto de Google Cloud . En Java, la instrumentación sin código hace referencia a la práctica de insertar dinámicamente bytecode en bibliotecas y frameworks para capturar telemetría. La instrumentación sin código puede recoger telemetría de elementos como las llamadas HTTP entrantes y salientes. Para obtener más información, consulta Agente de Java.

OpenTelemetry también proporciona una API para añadir instrumentación personalizada a tu propio código. OpenTelemetry lo denomina instrumentación manual. En este documento no se describe la instrumentación manual. Para ver ejemplos e información sobre este tema, consulta Instrumentación manual.

Antes de empezar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

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

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

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

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Instrumentar tu aplicación para recoger trazas, métricas y registros

Para instrumentar tu aplicación de forma que recoja datos de trazas y métricas, y para escribir JSON estructurado en la salida estándar, sigue los pasos que se describen en las secciones posteriores de este documento:

Configurar una aplicación para usar el agente Java de OpenTelemetry
Configurar OpenTelemetry
Configurar el almacenamiento de registros estructurado
Escribir registros estructurados

Configurar tu aplicación para usar el agente Java de OpenTelemetry

Para configurar la aplicación de forma que escriba registros estructurados y recoja métricas y datos de trazas mediante OpenTelemetry, actualiza la invocación de la aplicación para que use el agente Java de OpenTelemetry. Este método de instrumentación de tu aplicación se conoce como instrumentación automática porque no requiere que modifiques el código de la aplicación.

En el siguiente ejemplo de código se muestra un Dockerfile que descarga el archivo JAR del agente de Java de OpenTelemetry y actualiza la invocación de la línea de comandos para transferir la marca -javaagent.

Para ver el ejemplo completo, haz clic en Más y, a continuación, selecciona Ver en 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"

También puedes definir la marca -javaagent en la variable de entorno JAVA_TOOL_OPTIONS:

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

Configurar OpenTelemetry

La configuración predeterminada del agente de Java de OpenTelemetry exporta trazas y métricas mediante el protocolo OTLP. También configura OpenTelemetry para que use el formato Contexto de trazado de W3C para propagar el contexto de trazado. Esta configuración asegura que los intervalos tengan la relación correcta entre elementos principales y secundarios en una traza.

Para obtener más información y opciones de configuración, consulta Instrumentación automática de Java de OpenTelemetry.

Configurar el almacenamiento de registros estructurado

Para incluir la información de la traza en los registros con formato JSON que se escriben en la salida estándar, configura tu aplicación para que genere registros estructurados en formato JSON. Te recomendamos que uses Log4j2 como implementación de registro. El siguiente ejemplo de código muestra un archivo log4j2.xml configurado para generar registros estructurados en formato JSON mediante el diseño de plantilla 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 configuración anterior extrae información sobre el intervalo activo del contexto de diagnóstico asignado de SLF4J y añade esa información como atributos al registro. Estos atributos se pueden usar para correlacionar un registro con un rastreo:

logging.googleapis.com/trace: nombre de recurso de la traza asociada a la entrada de registro.
logging.googleapis.com/spanId: el ID del intervalo de la traza asociada a la entrada de registro.
logging.googleapis.com/trace_sampled: el valor de este campo debe ser true o false.

Para obtener más información sobre estos campos, consulta la LogEntry estructura.

Escribir registros estructurados

Para escribir registros estructurados que se vinculen a un rastreo, usa la API de registro SLF4J. Por ejemplo, en la siguiente instrucción se muestra cómo llamar al método Logger.info():

logger.info("handle /multi request with subRequests={}", subRequests);

El agente de Java de OpenTelemetry rellena automáticamente el contexto de diagnóstico asignado de SLF4J con el contexto de span del span activo actual en el contexto de OpenTelemetry. El contexto de diagnóstico asignado se incluye en los registros JSON, tal como se describe en el artículo sobre cómo configurar el registro estructurado.

Ejecutar una aplicación de ejemplo configurada para recoger telemetría

La aplicación de ejemplo usa formatos independientes del proveedor, como JSON para los registros y OTLP para las métricas y los rastreos, así como el framework Spring Boot. Para enrutar la telemetría a Google Cloud, en este ejemplo se usa OpenTelemetry Collector configurado con exportadores de Google. La aplicación tiene dos endpoints:

El endpoint /multi se gestiona con la función handleMulti. El generador de carga de la aplicación envía solicitudes al endpoint /multi. Cuando este endpoint recibe una solicitud, envía entre tres y siete solicitudes al endpoint /single del servidor local.

/**
 * 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"));
}

El endpoint /single se gestiona con la función handleSingle. Cuando este endpoint recibe una solicitud, espera un breve periodo y, a continuación, responde con una cadena.

/**
 * 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);
}

Descargar y desplegar la aplicación

Para ejecutar la muestra, haz lo siguiente:

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.

Clona el repositorio:

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

Ve al directorio de ejemplo:

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

Compila y ejecuta el ejemplo:

docker compose up --abort-on-container-exit

Si no estás ejecutando la aplicación en Cloud Shell, hazlo con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS que apunte a un archivo de credenciales. Las credenciales de aplicación predeterminadas proporcionan un archivo de credenciales en $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

Ver tus métricas

La instrumentación de OpenTelemetry en la aplicación de ejemplo genera métricas de Prometheus que puedes ver con el explorador de métricas:

Prometheus/http_server_duration_milliseconds/histogram Registra la duración de las solicitudes del servidor y almacena los resultados en un histograma.
Prometheus/http_client_duration_milliseconds/histogram Registra la duración de las solicitudes de cliente y almacena los resultados en un histograma.

En la Google Cloud consola, ve a la página Explorador de métricas:
Ve al explorador de métricas.

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.
En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
En el elemento Métrica, despliega el menú Seleccionar una métrica, introduce http_server en la barra de filtros y, a continuación, usa los submenús para seleccionar un tipo de recurso y una métrica específicos:
1. En el menú Recursos activos, selecciona Destino de Prometheus.
2. En el menú Categorías de métricas activas, selecciona Http.
3. En el menú Métricas activas, seleccione una métrica.
4. Haz clic en Aplicar.
Configure cómo se ven los datos.
Cuando las mediciones de una métrica son acumulativas, Explorador de métricas normaliza automáticamente los datos medidos por el periodo de alineación, lo que hace que el gráfico muestre una tasa. Para obtener más información, consulta Tipos, clases y conversiones.

Cuando se miden valores enteros o dobles, como con las dos métricas counter, el explorador de métricas suma automáticamente todas las series temporales. Para ver los datos de las rutas HTTP /multi y /single, defina el primer menú de la entrada Agregación como Ninguna.

Para obtener más información sobre cómo configurar un gráfico, consulta el artículo Seleccionar métricas al utilizar el explorador de métricas.

Ver tus trazas

Los datos de la traza pueden tardar varios minutos en estar disponibles. Por ejemplo, cuando tu proyecto recibe datos de traza, es posible que Google Cloud Observability tenga que crear una base de datos para almacenar esos datos. La creación de la base de datos puede tardar unos minutos. Durante ese periodo, no se podrá ver ningún dato de seguimiento.

Para ver los datos de la traza, haz lo siguiente:

En la Google Cloud consola, ve a la página Explorador de trazas:
Ir a Explorador de trazas

También puedes encontrar esta página mediante la barra de búsqueda.
En la sección de la tabla de la página, seleccione una fila con el nombre del intervalo /multi.
En el gráfico de Gantt del panel Detalles del rastreo, selecciona el intervalo etiquetado como /multi.

Se abrirá un panel con información sobre la solicitud HTTP. Estos detalles incluyen el método, el código de estado, el número de bytes y el agente de usuario de la persona que llama.
Para ver los registros asociados a este rastreo, selecciona la pestaña Registros y eventos.

En la pestaña se muestran los registros individuales. Para ver los detalles de la entrada de registro, despliégala. También puede hacer clic en Ver registros y consultar el registro con el Explorador de registros.

Para obtener más información sobre cómo usar el explorador de Cloud Trace, consulta Buscar y explorar trazas.

Consultar los registros

En Explorador de registros, puedes inspeccionar tus registros y ver las trazas asociadas, si las hay.

En la Google Cloud consola, ve a la página Explorador de registros:
Ve al Explorador de registros.

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.
Busca un registro con la descripción handle /multi request.

Para ver los detalles del registro, despliega la entrada.
En una entrada de registro con el mensaje "handle /multi request", haz clic en Trazas y, a continuación, selecciona Ver detalles de la traza.

Se abre el panel Detalles de la traza, donde se muestra la traza seleccionada.

Los datos de registro pueden estar disponibles varios minutos antes que los datos de la traza. Si se produce un error al ver los datos de seguimiento, ya sea buscando un seguimiento por ID o siguiendo los pasos de esta tarea, espera uno o dos minutos y vuelve a intentarlo.

Para obtener más información sobre cómo usar el Explorador de registros, consulta el artículo Ver registros con el Explorador de registros.