En este documento, se describe cómo modificar una app de Java para recopilar datos de seguimiento y métricas con el framework de código abierto de OpenTelemetry y cómo escribir registros JSON estructurados en salida estándar. En este documento, también se proporciona información sobre una app de Java Spring Boot muestra que puedes instalar y ejecutar. La app está configurada para generar métricas, seguimientos y registros. Los pasos son los mismos, sin importar si usas el framework Spring Boot.
Para obtener más información sobre la instrumentación, consulta los siguientes documentos:
Información sobre la instrumentación manual y automática
La instrumentación descrita en este documento se basa en la instrumentación automática de OpenTelemetry para enviar telemetría a tu proyecto de Google Cloud. En Java, la instrumentación automática hace referencia a la práctica de insertar de forma dinámica el código de bytes en bibliotecas y frameworks para capturar telemetría. La instrumentación automática puede recopilar telemetría para llamadas HTTP entrantes y salientes. Para obtener más información, consulta Instrumentación automática para Java.
OpenTelemetry también proporciona una API para agregar instrumentación personalizada a tu propio código. OpenTelemetry hace referencia a esto como instrumentación manual. En este documento, no se describe la instrumentación manual. Para obtener información y ejemplos sobre ese tema, consulta Instrumentación manual.
Antes de comenzar
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Instrumenta tu app para recopilar seguimientos, métricas y registros
Si deseas instrumentar tu app para recopilar datos de seguimiento y métricas, y escribir JSON estructurado en la salida estándar, realiza los pasos que se describen en las siguientes secciones de este documento:
- Configura tu app para usar el agente de Java de OpenTelemetry
- Configura OpenTelemetry
- Configura el registro estructurado
- Escribe registros estructurados
Configura tu app para usar el agente de Java de OpenTelemetry
Si deseas configurar la app para que escriba registros estructurados y recopile métricas y datos de seguimiento mediante OpenTelemetry, actualiza la invocación de tu app para usar el agente de Java de OpenTelemetry. Este método para instrumentar tu app se conoce como instrumentación automática porque no requiere modificar el código de tu app.
En la siguiente muestra de código, se ilustra 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 pasar la marca -javaagent
.
Para ver la muestra completa, haz clic en more_vert Más y, luego, selecciona Ver en GitHub.
Como alternativa, también puedes establecer la marca -javaagent
en la variable de entorno JAVA_TOOL_OPTIONS
:
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
Configura OpenTelemetry
La configuración predeterminada para el agente de Java de OpenTelemetry exporta seguimientos y métricas mediante el protocolo OTLP. También configura OpenTelemetry para usar el formato de contexto de seguimiento W3C a fin de propagar el contexto de seguimiento. Esta configuración garantiza que los intervalos tengan la relación superior-secundaria correcta dentro de un seguimiento.
Para obtener más información y opciones de configuración, consulta Instrumentación automática de Java de OpenTelemetry.
Configura el registro estructurado
Para incluir la información de seguimiento como parte de los registros con formato JSON escritos en el resultado estándar, configura tu aplicación para que genere registros estructurados en formato JSON. Te recomendamos usar Log4j2 como tu implementación de registros.
En la siguiente muestra de código, se ilustra un archivo log4j2.xml
configurado para generar registros estructurados JSON a través del diseño de plantilla de JSON:
La configuración anterior extrae información sobre el intervalo activo del contexto de diagnóstico asignado de SLF4J y agrega esa información como atributos al registro. Estos atributos se pueden usar para correlacionar un registro con un seguimiento:
logging.googleapis.com/trace
: el nombre del recurso del seguimiento asociado a la entrada de registro.logging.googleapis.com/spanId
: el ID de intervalo con el seguimiento asociado a la entrada de registro.logging.googleapis.com/trace_sampled
: el valor de este campo debe sertrue
ofalse
.
Para obtener más información sobre estos campos, consulta la estructura LogEntry
.
Escribe registros estructurados
Para escribir registros estructurados que se vinculen a un seguimiento, usa la API de Logging de SLF4J. Por ejemplo, con 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 propaga de forma automática el contexto de diagnóstico asignado de SLF4J con el contexto de intervalo del intervalo activo actual en el contexto de OpenTelemetry. El contexto de diagnóstico asignado se incluye en los registros JSON como se describe en Configura el registro estructurado.
Ejecuta una app de ejemplo configurada para recopilar telemetría
La app de ejemplo usa formatos que no dependen de los proveedores, incluidos JSON para los registros y OTLP para las métricas y los seguimientos, y el framework de Spring Boot. Para enrutar la telemetría a Google Cloud, esta muestra usa el Collector
de OpenTelemetry configurado con los exportadores de Google. La app tiene dos extremos:
La función
handleMulti
controla el extremo/multi
. El generador de cargas de la app envía solicitudes al extremo/multi
. Cuando este extremo recibe una solicitud, envía entre tres y siete solicitudes al extremo/single
en el servidor local.La función
handleSingle
controla el extremo/single
. Cuando este extremo recibe una solicitud, se suspende durante un retraso breve y, luego, responde con una cadena.
Descarga e implementa la app
Para ejecutar la muestra, haz lo siguiente:
-
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 el repositorio:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java
Ve al directorio de muestra:
cd opentelemetry-operations-java/examples/instrumentation-quickstart
Compila y ejecuta la muestra:
docker compose up --abort-on-container-exit
Si no ejecutas en Cloud Shell, ejecuta la aplicación con la variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
que apunta a un archivo de credenciales. Las credenciales predeterminadas de la aplicación 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
Consulta tus métricas
La instrumentación de OpenTelemetry en la app de ejemplo genera métricas de Prometheus que puedes ver mediante 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 del cliente y almacena los resultados en un histograma.
-
En la consola de Google Cloud, ve a la página leaderboard Explorador de métricas:
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.
- En el elemento Métrica, expande el menú Seleccionar una métrica,
ingresa
http_server
en la barra de filtros y, luego, usa los submenús para seleccionar un métrica y tipo de recurso específicos:- En el menú Recursos activos, elige Destino de Prometheus.
- En el menú Categorías de métricas activas, elige Http.
- En el menú Métricas activas, selecciona una métrica.
- Haz clic en Aplicar.
- Configura cómo se ven los datos.
Cuando las mediciones de una métrica son acumulativas, el Explorador de métricas normaliza automáticamente los datos medidos por el período de alineación, lo que hace que el gráfico muestre una frecuencia. Para obtener más información, consulta Categorías, tipos y conversiones.
Cuando se miden valores de números 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
, establece el primer menú de la entrada Agregación como Ninguna.Para obtener más información sobre la configuración de un gráfico, consulta elige métricas cuando uses el Explorador de métricas.
Ve tus seguimientos
Para ver tus datos de seguimiento, haz lo siguiente:
-
En la consola de Google Cloud, ve a la página Explorador de seguimiento:
Ve al Explorador de seguimiento
También puedes usar la barra de búsqueda para encontrar esta página.
- En el gráfico de dispersión, selecciona un seguimiento con el URI de
/multi
. En el diagrama de Gantt del panel Detalles de seguimiento, selecciona el intervalo etiquetado como
/multi
.Se abre un panel que muestra información sobre la solicitud HTTP. Estos detalles incluyen el método, el código de estado, la cantidad de bytes y el usuario-agente del emisor.
Para ver los registros asociados con este seguimiento, selecciona la pestaña Registros y eventos.
La pestaña muestra registros individuales. Para ver los detalles de la entrada de registro, expande la entrada de registro. También puedes hacer clic en Ver registros y ver el registro con el Explorador de registros.
Si deseas obtener más información para usar el explorador de Cloud Trace, consulta Busca y explora seguimientos.
Mira los registros
En el Explorador de registros, puedes inspeccionar tus registros y, también, puedes ver los seguimientos asociados, cuando existen.
-
En la consola de Google Cloud, ve a la página Explorador de registros:
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
Ubica un registro con la descripción de
handle /multi request
.Para ver los detalles del registro, expande la entrada de registro.
Haz clic en Seguimientos en una entrada de registro con el mensaje "Controla solicitudes múltiples" y, luego, selecciona Ver detalles de seguimiento.
Se abrirá el panel Detalles de seguimiento y se mostrará el seguimiento seleccionado.
Para obtener más información sobre el uso del Explorador de registros, consulta Visualiza registros con el Explorador de registros.
¿Qué sigue?
- OpenTelemetry
- Especificación de OTLP
- Registro estructurado
- Solución de problemas de Managed Service para Prometheus
- Soluciona problemas de Cloud Trace