Instrumentación automática basada en OpenTelemetry de Azure Monitor para aplicaciones Java

En este artículo se describe cómo habilitar y configurar la oferta de Java de Azure Monitor basada en OpenTelemetry. Cuando termine de leer las instrucciones de este artículo, podrá usar Application Insights de Azure Monitor para supervisar la aplicación.

Introducción

La instrumentación automática de Java se puede habilitar sin cambios en el código.

Prerrequisitos

• Aplicación Java con Java 8+
• Una suscripción a Azure: cree una de forma gratuita.
• Recurso de Application Insights: Creación de un recurso de Application Insights

Habilitación de Azure Monitor Application Insights

1. Descarga del archivo JAR de instrumentación automática

1. Descargar el archivo JAR.

Descargue el archivo applicationinsights-agent-3.2.3.jar.

2. Apuntar la JVM al archivo JAR.

Agregue -javaagent:path/to/applicationinsights-agent-3.2.3.jar a los argumentos de JVM de la aplicación.

3. Establecer la cadena de conexión de Application Insights.

Apunte el archivo jar al recurso de Application Insights, ya sea estableciendo una variable de entorno:

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...

O creando un archivo de configuración denominado applicationinsights.json y colocándolo en el mismo directorio que applicationinsights-agent-3.2.3.jar, con el siguiente contenido:

{
  "connectionString": "InstrumentationKey=..."
}

Busque la cadena de conexión en el recurso de Application Insights.

4. Confirmar que los datos fluyen.

Ejecute la aplicación y abra la pestaña Recurso de Application Insights en Azure Portal. Los datos pueden tardar unos minutos en aparecer en el portal.

Opciones de configuración

En el archivo applicationinsights.json también puede configurar estos valores:

• Nombre del rol en la nube
• Instancia de rol en la nube
• muestreo
• Métricas JMX
• Dimensiones personalizadas
• Procesadores de telemetría (versión preliminar)
• Registros recopilados automáticamente
• Métricas de Micrometer recopiladas automáticamente (incluidas las métricas del accionador de Spring Boot)
• Latido
• Proxy HTTP
• Diagnóstico automático

Para obtener detalles, vea las opciones de configuración.

Bibliotecas de instrumentación

Java 3.X incluye las siguientes bibliotecas de instrumentación.

Solicitudes recopiladas automáticamente

• Consumidores de JMS
• Consumidores de Kafka
• Netty/WebFlux
• Servlets
• Programación de Spring

Dependencias recopiladas automáticamente

Dependencias recopiladas automáticamente más la propagación de seguimiento distribuido de bajada:

• Apache HttpClient
• Apache HttpAsyncClient
• AsyncHttpClient
• Google HttpClient
• gRPC
• java.net.HttpURLConnection
• Java 11 HttpClient
• JAX-RS Client
• Jetty HttpClient
• JMS
• Kafka
• Cliente Netty
• OkHttp

Dependencias recopiladas automáticamente (sin propagación de seguimiento distribuido de bajada):

• Cassandra
• JDBC
• MongoDB (asincrónico y sincrónico)
• Redis (Lettuce y Jedis)

Registros recopilados automáticamente

• java.util.logging
• Log4j (incluidas las propiedades de MDC)
• SLF4J/Logback (incluidas las propiedades de MDC)

Métricas recopiladas automáticamente

• Micrometer (incluidas las métricas del actuador de Spring Boot)
• Métricas JMX

SDK de Azure

La telemetría emitida por estos SDK de Azure se recopila automáticamente de forma predeterminada:

• App Configuration 1.1.10+
• Cognitive Search 11.3.0+
• Communication Chat 1.0.0+
• Communication Common 1.0.0+
• Communication Identity 1.0.0+
• Communication Phone Numbers 1.0.0+
• Communication SMS 1.0.0+
• Cosmos DB 4.13.0+
• Digital Twins: básico 1.1.0+
• Event Grid 4.0.0+
• Event Hubs 5.6.0+
• Event Hubs: almacén de puntos de control de Azure Blob Storage 1.5.1+
• Form Recognizer 3.0.6+
• Identity 1.2.4+
• Key Vault: certificados 4.1.6+
• Key Vault: claves 4.2.6+
• Key Vault: secretos 4.2.6+
• Service Bus 7.1.0+
• Storage: Blobs 12.11.0+
• Storage: Blobs Batch 12.9.0+
• Storage: Blobs Cryptography 12.11.0+
• Storage: Common 12.11.0+
• Storage: Files Data Lake 12.5.0+
• Storage: Files Shares 12.9.0+
• Storage: Queues 12.9.0+
• Text Analytics 5.0.4+

Modificación de la telemetría

Incorporación de atributos de intervalo

Puede usar opentelemetry-api para agregar atributos a intervalos. Estos atributos pueden incluir la incorporación de una dimensión empresarial personalizada a la telemetría. También puede usar atributos para establecer campos opcionales en el esquema de Application Insights, como Id. de usuario o IP de cliente.

Adición de dimensiones personalizadas

Al agregar una o más dimensiones personalizadas, se rellena el campo customDimensions de la tabla de solicitudes, dependencias o excepciones.

Agregue opentelemetry-api-1.6.0.jar a la aplicación:

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.0</version>
</dependency>

Agregue dimensiones personalizadas al código:

import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("mycustomdimension", "myvalue1");

Establecimiento del identificador de usuario

Rellene el campo Id. de usuario de la tabla de solicitudes, dependencias o excepciones.

Agregue opentelemetry-api-1.6.0.jar a la aplicación:

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.0</version>
</dependency>

Establezca user_Id en el código:

import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("enduser.id", "myuser");

Obtención del identificador de seguimiento o el identificador de intervalo

Puede usar opentelemetry-api para obtener el identificador de seguimiento o el identificador de intervalo. Esta acción sirve para agregar estos identificadores a la telemetría de registro existente a fin de mejorar la correlación al depurar y diagnosticar problemas.

Agregue opentelemetry-api-1.6.0.jar a la aplicación:

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.0</version>
</dependency>

Obtenga el identificador de seguimiento de la solicitud y el identificador de intervalo del código:

import io.opentelemetry.api.trace.Span;

String traceId = Span.current().getSpanContext().getTraceId();
String spanId = Span.current().getSpanContext().getSpanId();

Telemetría personalizada

Nuestro objetivo con Application Insights para Java 3.x es permitirle enviar telemetría personalizada mediante API estándar.

En este momento se admiten Micrometer, marcos de registro populares y el SDK de Application Insights para Java 2.x. Application Insights para Java 3.x capturará automáticamente la telemetría, la enviará a través de las API y la correlacionará con la telemetría recopilada automáticamente.

Telemetría personalizada admitida

En la tabla siguiente se representan los tipos de telemetría personalizados admitidos actualmente que se pueden habilitar para complementar el agente Java 3.x. En resumen, las métricas personalizadas se admiten a través de un micrómetro, las excepciones y seguimientos personalizados se pueden habilitar a través de las plataformas de registro, las solicitudes personalizadas, las dependencias y las excepciones se pueden habilitar a través de opentelemetry-api y cualquier tipo de telemetría personalizada se admite mediante el SDK de Java 2.x para Application Insights.

No tenemos previsto publicar ningún SDK con Application Insights 3.x en este momento.

Application Insights para Java 3.x ya escucha la telemetría que se envía al SDK de Application Insights para Java 2.x. Esta funcionalidad es una parte importante de la historia de actualización de los usuarios existentes de 2.x y llena una brecha importante en la compatibilidad con la telemetría personalizada hasta que OpenTelemetry API ofrezca disponibilidad general.

Envío de métricas personalizadas mediante Micrometer

Agregue Micrometer a la aplicación:

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-core</artifactId>
  <version>1.6.1</version>
</dependency>

Use el registro global de Micrometer para crear un medidor:

static final Counter counter = Metrics.counter("test_counter");

Use el contador para registrar métricas:

counter.increment();

Envío de seguimientos y excepciones personalizados mediante su plataforma de registro favorita

Log4j, Logback y java.util.logging se instrumentan automáticamente y los registros creados mediante estas plataformas de registro se recopilan automáticamente como telemetría de seguimiento y excepciones.

De forma predeterminada, los registros solo se recopilan cuando se crean en el nivel INFO o superior. Para cambiar este nivel, vea las opciones de configuración.

Si quiere adjuntar dimensiones personalizadas a los registros, puede usar Log4j 1.2 MDC, Log4j 2 MDC o Logback MDC. Application Insights para Java 3.x captura automáticamente esas propiedades de MDC como dimensiones personalizadas en la telemetría de seguimiento y excepciones.

Envío de telemetría personalizada mediante el SDK 2.x

Agregue applicationinsights-core-2.6.3.jar a la aplicación (todas las versiones 2.x son compatibles con Application Insights para Java 3.x, pero merece la pena usar la más reciente si es posible):

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>2.6.3</version>
</dependency>

Cree un elemento TelemetryClient:

static final TelemetryClient telemetryClient = new TelemetryClient();

Use el cliente para enviar telemetría personalizada:

Eventos

telemetryClient.trackEvent("WinGame");

Métricas

telemetryClient.trackMetric("queueLength", 42.0);

Dependencias

boolean success = false;
long startTime = System.currentTimeMillis();
try {
    success = dependency.call();
} finally {
    long endTime = System.currentTimeMillis();
    RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
    telemetry.setSuccess(success);
    telemetry.setTimestamp(new Date(startTime));
    telemetry.setDuration(new Duration(endTime - startTime));
    telemetryClient.trackDependency(telemetry);
}

Registros

telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);

Excepciones

try {
    ...
} catch (Exception e) {
    telemetryClient.trackException(e);
}

Solución de problemas

Vea el artículo Solución de problemas.

Soporte técnico

• Revise Pasos de solución de problemas.
• En caso de problemas de Soporte técnico de Azure, abra una incidencia de Soporte técnico de Azure.
• En caso de problemas de OpenTelemetry, póngase en contacto directamente con la comunidad de OpenTelemetry.

Comentarios de OpenTelemetry

• Rellene la encuesta de comentarios de los clientes de la comunidad de OpenTelemetry.
• Únase a la comunidad de usuarios pioneros de OpenTelemetry y cuente a Microsoft un poco sobre sí mismo.
• Interactúe con otros usuarios de Azure Monitor en Microsoft Tech Community.

Pasos siguientes

• Revise el código fuente en el repositorio de GitHub de instrumentación automática de Java para Azure Monitor.
• Para más información sobre OpenTelemetry y su comunidad, visite el repositorio de GitHub de Java para OpenTelemetry.
• Habilite la supervisión de usuarios web o de explorador para habilitar experiencias de uso.