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. Se puede usar para cualquier entorno, incluido el entorno local. Cuando termine de leer las instrucciones de este artículo, podrá usar Application Insights de Azure Monitor para supervisar la aplicación.

Nota

El 31 de marzo de 2025 finalizará la compatibilidad con la ingesta de claves de instrumentación. La ingesta de claves de instrumentación seguirá funcionando, pero la característica ya no recibirá actualizaciones ni soporte técnico. Transición a las cadenas de conexión para aprovechar las nuevas funcionalidades.

Introducción

La instrumentación automática de Java está habilitada a través de cambios de configuración; no se requieren cambios en el código.

Prerrequisitos

Habilitación de Azure Monitor Application Insights

En esta sección se muestra cómo descargar el archivo jar de instrumentación automática.

Descarga del archivo .jar

Descargue el archivo applicationinsights-agent-3.4.4.jar.

Advertencia

Si va a actualizar desde una versión anterior de la versión 3.x,

A partir de la versión 3.4.0:

  • El muestreo de velocidad limitada es ahora el valor predeterminado (si no ha configurado previamente un porcentaje fijo). De forma predeterminada, capturará como máximo 5 solicitudes por segundo (junto con sus dependencias, seguimientos y eventos personalizados). Consulte muestreo de porcentaje fijo si desea revertir al comportamiento anterior de capturar el 100 % de las solicitudes.

A partir de la versión 3.3.0:

  • no se captura LoggingLevel de manera predeterminada como parte de la dimensión personalizada de seguimientos, puesto que esos datos ya se capturan en el campo SeverityLevel. Para más información sobre cómo volver a habilitar esta opción si fuera necesario, consulte las opciones de configuración.
  • Los registros de excepciones ya no se registran para las dependencias con errores, solo se registran para las solicitudes con errores.

A partir de la versión 3.2.0:

  • Las dependencias del controlador "InProc" ya no se capturan de forma predeterminada. Para saber cómo volver a activarlas, consulte las opciones de configuración.
  • Los nombres de dependencias de bases de datos ahora son más concisos y siguen teniendo la consulta completa (saneada) en el campo data. Los nombres de dependencias HTTP ahora son más descriptivos. Este cambio puede afectar a los paneles o las alertas personalizados si se basaban en los valores anteriores. Para obtener detalles, vea las notas de la versión 3.2.0.

A partir de la versión 3.1.0:

  • Los nombres de operación y los nombres de telemetría de solicitudes ahora tienen el método HTTP como prefijo (por ejemplo GET y POST). Este cambio puede afectar a los paneles o las alertas personalizados si se basaban en los valores anteriores. Para obtener detalles, vea las notas de la versión 3.1.0.

Apunte la JVM al archivo JAR.

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

Sugerencia

Para obtener ayuda con la configuración de los argumentos de JVM de la aplicación, consulte Sugerencias para actualizar los argumentos de JVM.

Sugerencia

Si desarrolla una aplicación de Spring Boot, puede reemplazar el argumento JVM por una configuración mediante programación. Consulte más información aquí.

Establezca la cadena de conexión de Application Insights.

  1. Hay dos maneras de apuntar el archivo jar al recurso de Application Insights:

    • Puede establecer una variable de entorno:

      APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>
      
    • O bien, puede crear un archivo de configuración denominado applicationinsights.json. Colóquelo en el mismo directorio que applicationinsights-agent-3.4.4.jar con el siguiente contenido:

      {
        "connectionString": "Copy connection string from Application Insights Resource Overview"
      }
      
  2. Busque la cadena de conexión en el recurso de Application Insights.

    Captura de pantalla que muestra la descripción general y la cadena de conexión de Application Insights.

Confirmación de 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.

Nota

Si no puede ejecutar la aplicación o no obtiene datos según lo esperado, consulte la sección Solución de problemas.

Captura de pantalla de la pestaña Información general de Application Insights con las solicitudes de servidor y el tiempo de respuesta del servidor resaltados.

Importante

Si tiene dos o más servicios que emiten telemetría al mismo recurso de Application Insights, debe establecer los nombres de rol en la nube para representarlos correctamente en el mapa de aplicación.

Como parte del uso de la instrumentación de Application Insights, se recopilan y envían datos de diagnóstico a Microsoft. Estos datos ayudan a ejecutar y mejorar Application Insights. Puede deshabilitar la recopilación de datos no esenciales. Para obtener más información, consulte Statsbeat en Azure Application Insights.

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 más información, consulte Opciones de configuración.

Instrumentación automática

Java 3.x incluye la siguiente instrumentación automática.

Solicitudes recopiladas automáticamente

  • Consumidores de JMS
  • Consumidores de Kafka
  • Netty/WebFlux
  • Quartz
  • 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
  • Cliente de JAX-RS
  • Jetty HttpClient
  • JMS
  • Kafka
  • Cliente Netty
  • OkHttp

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

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

Registros recopilados automáticamente

  • Log4j (incluidas las propiedades de contexto de MDC y subproceso)
  • Logback (incluidas las propiedades de MDC)
  • Registro de JBoss (incluidas las propiedades de MDC)
  • java.util.logging

Métricas recopiladas automáticamente

  • Micrometer, que incluye métricas del accionador 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:

Modificación de la telemetría

En esta sección se explica cómo modificar la telemetría.

Agregar intervalos

La manera más fácil de agregar sus propios intervalos es usar la anotación @WithSpan de OpenTelemetry.

Los intervalos rellenan las tablas requests y dependencies en Application Insights.

Nota

Esta característica solo está disponible en la versión 3.2.0 y posteriores.

  1. Agregue opentelemetry-extension-annotations-1.16.0.jar a la aplicación:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-extension-annotations</artifactId>
      <version>1.16.0</version>
    </dependency>
    
  2. Use la anotación @WithSpan para emitir un intervalo cada vez que se ejecute el método:

     import io.opentelemetry.extension.annotations.WithSpan;
    
     @WithSpan(value = "your span name")
     public void yourMethod() {
     }
    

De forma predeterminada, el intervalo terminará en la tabla de dependencias con el tipo de dependencia InProc.

Si el método representa un trabajo en segundo plano que aún no está capturado por la instrumentación automática, se recomienda aplicar el atributo kind = SpanKind.SERVER a la anotación @WithSpan para que termine en la tabla requests de Application Insights.

Agregar eventos de intervalo

Puede usar opentelemetry-api para crear eventos de intervalo, que rellenan la tabla de seguimientos en Application Insights. La cadena pasada addEvent() se guarda en el campo de mensaje dentro del seguimiento.

Nota

Esta característica solo está disponible en la versión 3.2.0 y posteriores.

  1. 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>
    
  2. Agregue eventos de intervalo en su código:

     import io.opentelemetry.api.trace.Span;
    
     Span.current().addEvent("eventName");
    

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.

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

Nota

Esta característica solo está disponible en la versión 3.2.0 y posteriores.

  1. 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>
    
  2. Agregue dimensiones personalizadas al código:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.common.AttributeKey;
    
     AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");
     Span.current().setAttribute(attributeKey, "myvalue1");
    

Actualizar el estado del intervalo y registrar excepciones

Puede usar opentelemetry-api para actualizar el estado de un intervalo y registrar excepciones.

Nota

Esta característica solo está disponible en la versión 3.2.0 y posteriores.

  1. 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>
    
  2. Establezca el estado en error y registre una excepción en su código:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.trace.StatusCode;
    
     Span span = Span.current();
     span.setStatus(StatusCode.ERROR, "errorMessage");
     span.recordException(e);
    

Establezca el identificador de usuario

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

Importante

Consulte las leyes de privacidad aplicables antes de establecer el id. de usuario autenticado.

Nota

Esta característica solo está disponible en la versión 3.2.0 y posteriores.

  1. 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>
    
  2. 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 de intervalo

Puede usar opentelemetry-api para obtener el identificador de seguimiento o el 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.

Nota

Esta característica solo está disponible en la versión 3.2.0 y posteriores.

  1. 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>
    
  2. Obtenga el identificador de seguimiento de la solicitud y el identificador de intervalo del código:

    import io.opentelemetry.api.trace.Span;
    
    Span span = Span.current();
    String traceId = span.getSpanContext().getTraceId();
    String spanId = span.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 Micrometer.
  • Las excepciones y los seguimientos personalizados se admiten a través de marcos de registro.
  • Las solicitudes personalizadas, las dependencias, las métricas y las excepciones se admiten a través de opentelemetry-api.
  • Todos los tipos de telemetría personalizada se admiten a través de Application Insights para el SDK de Java 2.x.
Tipo de telemetría personalizado Micrómetro Log4j, logback, JUL SDK 2.x opentelemetry-api
Eventos personalizados
Métricas personalizadas
Dependencias
Excepciones
Vistas de página
Requests
Traces

En este momento, 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 del caso de actualización para los usuarios 2.x existentes. Además, rellena una brecha importante en nuestra compatibilidad con telemetría personalizada hasta que se admiten todos los tipos de telemetría personalizados a través de la API de OpenTelemetry.

Envío de métricas personalizadas mediante Micrometer

  1. Agregue Micrometer a la aplicación:

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-core</artifactId>
      <version>1.6.1</version>
    </dependency>
    
  2. Use el registro global de Micrometer para crear un medidor:

    static final Counter counter = Metrics.counter("test.counter");
    
  3. Use el contador para registrar métricas:

    counter.increment();
    
  4. Las métricas se ingieren en la tabla customMetrics, con etiquetas capturadas en la columna . También puede ver las métricas en el Explorador de métricas, en el espacio de nombres de métricas "Métricas basadas en registros".

    Nota

    Java de Application Insights reemplaza todos los caracteres no alfanuméricos (excepto guiones) en el nombre de la métrica Micrometer por caracteres de subrayado, por lo que la métrica test.counter anterior se mostrará como test_counter.

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

Log4j, Logback y java.util.logging se instrumentan automáticamente. El registro realizado a través de estos marcos de registro se realiza automáticamente como telemetría de seguimiento y excepción.

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

  1. Agregue applicationinsights-core-2.6.4.jar a la aplicación. Todas las versiones 2.x son compatibles con Application Insights para Java 3.x. Si tiene la opción de hacerlo, vale la pena usar la versión más reciente:

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>applicationinsights-core</artifactId>
      <version>2.6.4</version>
    </dependency>
    
  2. Cree un elemento TelemetryClient:

    static final TelemetryClient telemetryClient = new TelemetryClient();
    
  3. 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

Consulte el artículo de solución de problemas dedicado.

Prueba de la conectividad entre el host de la aplicación y el servicio de ingesta

Los SDK y agentes de Application Insights envían telemetría para ingerirse como llamadas REST a nuestros puntos de conexión de ingesta. Puede probar la conectividad desde el servidor web o la máquina host de la aplicación a los puntos de conexión del servicio de ingesta mediante clientes REST sin procesar con comandos de PowerShell o curl. Consulte Solución de problemas de telemetría de aplicaciones que faltan en Azure Monitor Application Insights.

Notas de la versión

Vea las notas de la versión en GitHub.

Soporte técnico

Para obtener soporte técnico:

Comentarios de OpenTelemetry

Para proporcionar comentarios:

Pasos siguientes