Application Insights para Java 2.x

  • Artículo

Precaución

Este documento se aplica a Application Insights Java 2.x, que ya no se recomienda.

La documentación de la versión más reciente se puede encontrar en Application Insights para Java 3.x.

En este artículo, aprenderá a usar Application Insights Java 2.x. En este artículo aprenderá a:

  • Empezar a usarlo y aprender a instrumentar las solicitudes, realizar un seguimiento de las dependencias y recopilar contadores de rendimiento, diagnosticar problemas de rendimiento y excepciones y escribir código para realizar un seguimiento de lo que hacen los usuarios con la aplicación.
  • Enviar registros de seguimiento a Application Insights y explorarlos mediante el portal de Application Insights.
  • Supervisar las dependencias, las excepciones detectadas y los tiempos de ejecución del método en aplicaciones web de Java.
  • Filtrar la telemetría de la aplicación web de Java.
  • Explorar las métricas de rendimiento del sistema Linux en Application Insights mediante collectd.
  • Medir las métricas del código de aplicación basado en máquina virtual Java (JVM). Exportar los datos a sus sistemas de supervisión favoritos mediante la supervisión de aplicaciones de Micrometer.

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 a Application Insights en un proyecto web de Java

En esta sección, se usa el SDK de Application Insights para instrumentar solicitudes, realizar un seguimiento de dependencias, recopilar contadores de rendimiento, diagnosticar problemas de rendimiento y excepciones y escribir código para realizar un seguimiento de lo que hacen los usuarios con la aplicación.

Application Insights es un servicio de análisis extensible para desarrolladores web que ayuda a comprender el rendimiento y el uso de la aplicación activa. Application Insights es compatible con aplicaciones Java que se ejecutan en Linux, Unix o Windows.

Prerrequisitos

Necesita:

Obtención de una clave de instrumentación de Application Insights

  1. Inicie sesión en Azure Portal.

  2. En Azure Portal, cree un nuevo recurso de Application Insights. Establezca el tipo de aplicación a una aplicación web de Java.

  3. Busque la clave de instrumentación del nuevo recurso. Pronto tendrá que pegarla en el proyecto de código.

    Captura de pantalla del panel Información general de un recurso de Application Insights en Azure Portal con la clave de instrumentación resaltada.

Incorporación del SDK de Application Insights para Java al proyecto

Elija el tipo de proyecto.

Si su proyecto ya se ha configurado para usar Maven para la compilación, combine el siguiente código en el archivo pom.xml. A continuación, actualice las dependencias del proyecto, para obtener los archivos binarios descargados.

    <dependencies>
      <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <!-- or applicationinsights-web for manual web filter registration -->
        <!-- or applicationinsights-core for bare API -->
        <version>2.6.4</version>
      </dependency>
    </dependencies>

Preguntas más frecuentes

  • ¿Cuál es la relación entre los componentes -web-auto, -web y -core?

    • applicationinsights-web-auto proporciona métricas que realizan el seguimiento de los recuentos de solicitudes de servlet HTTP y los tiempos de respuesta, mediante el registro automático del filtro de servlet de Application Insights en tiempo de ejecución.
    • applicationinsights-web proporciona métricas que realizan el seguimiento de los recuentos de solicitudes HTTP y los tiempos de respuesta. Sin embargo, se requiere el registro manual del filtro de servlet de Application Insights en la aplicación.
    • applicationinsights-core proporciona la API básica, por ejemplo, si la aplicación no se basa en servlet.

  • ¿Cómo se debe actualizar el SDK a la versión más reciente?

    • A partir de noviembre de 2020, se recomienda supervisar las aplicaciones Java con Application Insights Java 3.x. Para más información sobre cómo empezar, consulte Java 3.x para Application Insights.

Adición del archivo ApplicationInsights.xml

Agregue ApplicationInsights.xml a la carpeta de recursos del proyecto o asegúrese de que se agrega a la ruta de acceso de la clase de implementación del proyecto. Copie en ella el siguiente XML.

Reemplace la clave de instrumentación por la que recibió de Azure Portal.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">

   <!-- The key from the portal: -->
   <InstrumentationKey>** Your instrumentation key **</InstrumentationKey>

   <!-- HTTP request component (not required for bare API) -->
   <TelemetryModules>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebSessionTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebUserTrackingTelemetryModule"/>
   </TelemetryModules>

   <!-- Events correlation (not required for bare API) -->
   <!-- These initializers add context data to each event -->
   <TelemetryInitializers>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationIdTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationNameTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebSessionTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserAgentTelemetryInitializer"/>
   </TelemetryInitializers>

</ApplicationInsights>

Si lo desea, el archivo de configuración puede estar en cualquier ubicación a la que su aplicación tenga acceso. La propiedad del sistema -Dapplicationinsights.configurationDirectory especifica el directorio que contiene ApplicationInsights.xml. Por ejemplo, un archivo de configuración ubicado en E:\myconfigs\appinsights\ApplicationInsights.xml se configuraría con la propiedad -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights".

  • La clave de instrumentación se envía junto con todos los elementos de telemetría e indica a Application Insights que se muestre en el recurso.
  • El componente de la solicitud HTTP es opcional. Envía automáticamente telemetría sobre las solicitudes y tiempos de respuesta en el portal.
  • La correlación de eventos es una incorporación al componente de la solicitud HTTP. Asigna un identificador a cada solicitud recibida por el servidor. A continuación, agrega este identificador como propiedad a todos los elementos de telemetría como la propiedad Operation.Id. Le permite correlacionar la telemetría asociada a cada solicitud estableciendo un filtro en la búsqueda de diagnóstico.

Alternativas para establecer la clave de instrumentación

SDK de Application Insights busca la clave en este orden:

  • Propiedad del sistema: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  • Variable de entorno: APPINSIGHTS_INSTRUMENTATIONKEY
  • Archivo de configuración: ApplicationInsights.xml

También se puede configurar en el código:

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

Adición del agente

Instale el agente de Java para capturar llamadas HTTP salientes, consultas de JDBC y registros de aplicaciones y mejorar la nomenclatura de las operaciones.

Ejecución de la aplicación

Ejecútela en modo de depuración en la máquina de desarrollo o bien publíquela en el servidor.

Visualización de la telemetría en Application Insights

Vuelva al recurso Application Insights en Azure Portal.

Los datos de las solicitudes HTTP aparecen en el panel de información general. Si todavía no está ahí, espere unos segundos y, luego, seleccione Actualizar.

Captura de pantalla que muestra datos de ejemplo de información general.

Más información sobre las métricas.

Haga clic en cualquier gráfico para ver métricas agregadas más detalladas.

Captura de pantalla que muestra un panel de errores de Application Insights con gráficos.

Datos de instancia

Haga clic en un tipo de solicitud específico para ver las instancias individuales.

Captura de pantalla que muestra la exploración en profundidad de una vista de ejemplo específica.

Log Analytics: lenguaje de consulta eficaz

A medida que acumula más datos, puede ejecutar consultas tanto para agregar datos como para buscar instancias individuales. Log Analytics es una eficaz herramienta tanto para conocer el rendimiento y el uso, como para el diagnóstico.

Captura de pantalla que muestra un ejemplo de Log Analytics en Azure Portal.

Instalación de la aplicación en el servidor

Ahora puede publicar la aplicación en el servidor, dejar que la utilicen los usuarios y ver la telemetría en el portal.

  • Asegúrese de que el firewall permite que la aplicación envíe datos de telemetría a estos puertos:

    • dc.services.visualstudio.com:443
    • f5.services.visualstudio.com:443

  • Si el tráfico saliente debe enrutarse a través de un firewall, defina las propiedades del sistema http.proxyHost y http.proxyPort.

  • En los servidores de Windows, instale:

Azure App Service, Azure Kubernetes Service, configuración de máquinas virtuales

El mejor enfoque y el más sencillo para supervisar las aplicaciones que se ejecutan en cualquiera de los proveedores de recursos de Azure es usar Application Insights Java 3.x.

Excepciones y errores de solicitud

El filtro web de Application Insights recopila automáticamente las excepciones no controladas y las solicitudes con error.

Para recopilar datos de otras excepciones, puede insertar llamadas a trackException() en el código.

Supervisión de llamadas a métodos y dependencias externas

Instale el agente de Java para registrar los métodos internos especificados y las llamadas realizadas mediante JDBC, con datos de tiempo, y para las denominación automática de operaciones.

Seguimiento distribuido de W3C

El SDK de Java de Application Insights ahora admite el seguimiento distribuido de W3C.

La configuración entrante del SDK se explica con más detalle en Correlación de telemetría en Application Insights.

La configuración del SDK de salida se define en el archivo AI-Agent.xml.

Contadores de rendimiento

Seleccione Investigar>Métricas para ver un intervalo de contadores de rendimiento.

Captura de pantalla que muestra el panel Métricas de un recurso Application Insights en Azure Portal con bytes privados de proceso seleccionados.

Personalizar la recopilación de contadores de rendimiento

Para deshabilitar la recopilación del conjunto estándar de contadores de rendimiento, agregue el siguiente código bajo el nodo raíz del archivo ApplicationInsights.xml:

    <PerformanceCounters>
       <UseBuiltIn>False</UseBuiltIn>
    </PerformanceCounters>

Recopilación de más contadores de rendimiento

Puede especificar más contadores de rendimiento para recopilar.

Contadores JMX (expuestos por la máquina virtual de Java)
    <PerformanceCounters>
      <Jmx>
        <Add objectName="java.lang:type=ClassLoading" attribute="TotalLoadedClassCount" displayName="Loaded Class Count"/>
        <Add objectName="java.lang:type=Memory" attribute="HeapMemoryUsage.used" displayName="Heap Memory Usage-used" type="composite"/>
      </Jmx>
    </PerformanceCounters>
  • displayName: el nombre mostrado en el portal de Application Insights.
  • objectName: el nombre del objeto JMX.
  • attribute: el atributo del nombre del objeto JMX que se va a capturar.
  • type (opcional): el tipo del atributo del objeto JMX:
    • Valor predeterminado: un tipo simple como int o long.
    • composite: los datos del contador de rendimiento tienen el formato de Attribute.Data.
    • tabular: los datos del contador de rendimiento tienen el formato de una fila de tabla.
Contadores de rendimiento de Windows

Cada contador de rendimiento de Windows es un miembro de una categoría (de la misma manera que un campo es un miembro de una clase). Las categorías puede ser globales, o pueden tener instancias con nombre o número.

    <PerformanceCounters>
      <Windows>
        <Add displayName="Process User Time" categoryName="Process" counterName="%User Time" instanceName="__SELF__" />
        <Add displayName="Bytes Printed per Second" categoryName="Print Queue" counterName="Bytes Printed/sec" instanceName="Fax" />
      </Windows>
    </PerformanceCounters>
  • displayName: el nombre mostrado en el portal de Application Insights.
  • categoryName: la categoría de contador de rendimiento (objeto de rendimiento) con la que está asociada este contador de rendimiento.
  • counterName: el nombre del contador de rendimiento.
  • instanceName: el nombre de la instancia de categoría del contador de rendimiento; o bien, una cadena vacía ("") si la categoría contiene una sola instancia. Si categoryName es Process, y el contador de rendimiento que quiere recopilar es del proceso de JVM actual en que se ejecuta la aplicación, especifique "__SELF__".

Contadores de rendimiento de Unix

Instale collectd con el complemento de Application Insights para obtener una amplia variedad de datos de red y del sistema.

Obtención de datos de usuario y sesión

Ahora, va a enviar telemetría desde el servidor web. Para obtener la visión completa de 360 grados de la aplicación, puede agregar más supervisión:

Envío de su propia telemetría

Ahora que ha instalado el SDK, puede utilizar la API para enviar su propia telemetría:

Pruebas web de disponibilidad

Application Insights puede probar su sitio web a intervalos regulares para comprobar que está activo y que responde correctamente.

Más información sobre cómo configurar las pruebas web de disponibilidad.

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.

Exploración de los registros de seguimiento de Java en Application Insights

Si está usando Logback o Log4J (v1.2 o v2.0) para el seguimiento, los registros de seguimiento se pueden enviar automáticamente a Application Insights, donde puede explorarlos y buscar en ellos.

Sugerencia

Debe establecer la clave de instrumentación de Application Insights una sola vez para la aplicación. Si usa una plataforma como Java Spring, es posible que ya haya registrado la clave en otra parte de la configuración de la aplicación.

Uso del agente de Java de Application Insights

De forma predeterminada, el agente de Java de Application Insights captura automáticamente el registro realizado en el nivel WARN y superiores.

Puede cambiar el umbral de registro capturado mediante el archivo AI-Agent.xml:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn>
         <Logging threshold="info"/>
      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Puede deshabilitar la captura de registro del agente de Java mediante el archivo AI-Agent.xml:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn>
         <Logging enabled="false"/>
      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Alternativas

En lugar de usar el agente de Java, puede seguir estas instrucciones.

Instalación del SDK de Java

Siga las instrucciones para instalar el SDK de Application Insights para Java, si aún no lo ha hecho.

Incorporación de bibliotecas de registro al proyecto

Elija la forma adecuada para su proyecto.

Maven

Si su proyecto ya se ha configurado para usar Maven para la compilación, combine uno de los siguientes fragmentos de código en el archivo pom.xml. A continuación, actualice las dependencias del proyecto, para obtener los archivos binarios descargados.

Logback


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-logback</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>

Log4J v2.0


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-log4j2</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>

Log4J v1.2


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-log4j1_2</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>
Gradle

Si el proyecto ya se ha configurado para compilarlo con Gradle, agregue una de las líneas siguientes al grupo dependencies en el archivo build.gradle. A continuación, actualice las dependencias del proyecto, para obtener los archivos binarios descargados.

Logback


    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-logback', version: '2.0.+'

Log4J v2.0

    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j2', version: '2.0.+'

Log4J v1.2

    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j1_2', version: '2.0.+'

Siga las instrucciones para instalar manualmente el SDK de Java de Application Insights y descargar el archivo .jar. En la página de Maven Central, seleccione el vínculo jar en la sección de descarga del anexador adecuado. Agregue al proyecto el archivo .jar del anexador descargado.

Registrador Descargar Biblioteca
Logback JAR del appender de Logback applicationinsights-logging-logback
Log4J v2.0 JAR del appender de Log4J v2 applicationinsights-logging-log4j2
Log4J v1.2 JAR del appender de Log4J v1.2 applicationinsights-logging-log4j1_2

Incorporación del appender el marco de registro

Para empezar a recibir los seguimientos, combine el fragmento de código pertinente con el archivo de configuración Log4J o Logback.

Logback


    <appender name="aiAppender" 
      class="com.microsoft.applicationinsights.logback.ApplicationInsightsAppender">
        <instrumentationKey>[APPLICATION_INSIGHTS_KEY]</instrumentationKey>
    </appender>
    <root level="trace">
      <appender-ref ref="aiAppender" />
    </root>

Log4J v2.0


    <Configuration packages="com.microsoft.applicationinsights.log4j.v2">
      <Appenders>
        <ApplicationInsightsAppender name="aiAppender" instrumentationKey="[APPLICATION_INSIGHTS_KEY]" />
      </Appenders>
      <Loggers>
        <Root level="trace">
          <AppenderRef ref="aiAppender"/>
        </Root>
      </Loggers>
    </Configuration>

Log4J v1.2


    <appender name="aiAppender" 
         class="com.microsoft.applicationinsights.log4j.v1_2.ApplicationInsightsAppender">
        <param name="instrumentationKey" value="[APPLICATION_INSIGHTS_KEY]" />
    </appender>
    <root>
      <priority value ="trace" />
      <appender-ref ref="aiAppender" />
    </root>

Se puede hacer referencia a los anexadores de Application Insights con cualquier registrador configurado y no necesariamente con el registrador raíz, como se muestra en los ejemplos de código anteriores.

En el portal de Application Insights, explore los seguimientos.

Ahora que ha configurado el proyecto para enviar seguimientos a Application Insights, puede verlos y buscarlos en el portal de Application Insights, en el panel Buscar.

Las excepciones enviadas a través de registradores se mostrarán en el portal como telemetría de excepciones.

Captura de pantalla que muestra el panel Buscar con un recurso de Application Insights en Azure Portal.

Supervisión de dependencias, excepciones detectadas y tiempos de ejecución del método en aplicaciones web de Java

Si ha instrumentado la aplicación web de Java con el SDK de Application Insights, puede usar el agente de Java para extraer información más detallada, sin tener que realizar cambios en el código:

  • Dependencias: datos sobre las llamadas realizadas por la aplicación a otros componentes, por ejemplo:

    • Llamadas HTTP salientes: se capturan las llamadas realizadas a través de Apache HttpClient, OkHttp y java.net.HttpURLConnection.
    • Llamadas Redis: se capturan las llamadas realizadas a través del cliente de Jedis.
    • Consultas JDBC: en el caso de MySQL y PostgreSQL, si la llamada tarda más de 10 segundos, el agente notifica el plan de consulta.

  • Registro de aplicaciones: puede capturar y correlacionar los registros de aplicaciones con solicitudes HTTP y otra telemetría:

    • Log4j 1.2
    • Log4j2
    • Logback

  • Nomenclatura mejorada para las operaciones: se usa para la agregación de solicitudes en el portal.

    • Spring: se basa en @RequestMapping.
    • JAX-RS: se basa en @Path.

Para usar el agente de Java, debe instalarlo en el servidor. Las aplicaciones web deben instrumentarse con el SDK de Application Insights para Java.

Instalación del agente de Application Insights para Java

  1. En la máquina que ejecuta el servidor de Java, descargue el agente 2.x. Asegúrese de que la versión del agente de Java 2.x que usa coincida con la versión del SDK de Java para Application Insights 2.x que usa.

  2. Edite el script de inicio del servidor de aplicaciones y agregue el siguiente argumento de JVM:

    -javaagent:<full path to the agent JAR file>

    Por ejemplo, en Tomcat en un equipo Linux:

    export JAVA_OPTS="$JAVA_OPTS -javaagent:<full path to agent JAR file>"

  3. Reinicie el servidor de aplicaciones.

Configuración del agente

Cree un archivo denominado AI-Agent.xml y colóquelo en la misma carpeta que el archivo .jar del agente.

Establezca el contenido del archivo XML. Edite el ejemplo siguiente para incluir u omitir las características que desee.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn enabled="true">

         <!-- capture logging via Log4j 1.2, Log4j2, and Logback, default is true -->
         <Logging enabled="true" />

         <!-- capture outgoing HTTP calls performed through Apache HttpClient, OkHttp,
              and java.net.HttpURLConnection, default is true -->
         <HTTP enabled="true" />

         <!-- capture JDBC queries, default is true -->
         <JDBC enabled="true" />

         <!-- capture Redis calls, default is true -->
         <Jedis enabled="true" />

         <!-- capture query plans for JDBC queries that exceed this value (MySQL, PostgreSQL),
              default is 10000 milliseconds -->
         <MaxStatementQueryLimitInMS>1000</MaxStatementQueryLimitInMS>

      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Configuración adicional (Spring Boot)

java -javaagent:/path/to/agent.jar -jar path/to/TestApp.jar

Para Azure App Service, siga estos pasos:

  1. Seleccione Configuración>Configuración de la aplicación.

  2. En Configuración de la aplicación, agregue un nuevo par clave-valor:

    • Clave: JAVA_OPTS
    • Valor: -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.6.4.jar

    El agente debe estar empaquetado como un recurso en el proyecto de forma que termine en el directorio D:/home/site/wwwroot/. Para confirmar que el agente está en el directorio correcto de App Service, vaya a Herramientas de desarrollo>Herramientas avanzadas>Consola de depuración y examine el contenido del directorio del sitio.

  3. Guarde la configuración y reinicie la aplicación. Estos pasos solo se aplican a los servicios de aplicaciones que se ejecutan en Windows.

Nota

AI-Agent.xml y el archivo .jar del agente deben estar en la misma carpeta. A menudo se colocan juntos en la carpeta /resources del proyecto.

Habilitación del seguimiento distribuido de W3C

Agréguele el siguiente fragmento de código a AI-Agent.xml:

<Instrumentation>
   <BuiltIn enabled="true">
      <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
   </BuiltIn>
</Instrumentation>

Nota

El modo de compatibilidad con versiones anteriores está habilitado de forma predeterminada. El parámetro enableW3CBackCompat es opcional y solo se debe usar cuando quiera desactivarlo.

El caso más conveniente sería cuando todos los servicios se han actualizado a versiones más recientes de los SDK compatibles con el protocolo W3C. Se recomienda pasar lo antes posible a las versiones más recientes de los SDK con compatibilidad con W3C.

Asegúrese de que las configuraciones (del agente) tanto entrantes como salientes sean exactamente iguales.

Visualización de los datos

En el recurso de Application Insights, aparecen tiempos de ejecución agregados de métodos y dependencias remotos en el icono Rendimiento.

Para buscar instancias individuales de informes de dependencia, excepción y método, abra Buscar.

Más información sobre cómo diagnosticar los problemas de dependencias.

¿Preguntas o problemas?

Use los siguientes recursos:

Filtrado de telemetría en la aplicación web de Java

Los filtros proporcionan una manera de seleccionar la telemetría que su aplicación web de Java envía a Application Insights. Hay algunos filtros predefinidos que puede usar. También puede escribir sus propios filtros personalizados.

Los filtros de serie incluyen:

  • El nivel de gravedad del seguimiento.
  • Direcciones URL, palabras clave o códigos de respuesta específicos.
  • Respuestas rápidas. En otras palabras, solicitudes a las que la aplicación respondió rápidamente.
  • Nombres de eventos específicos.

Nota

Los filtros sesgan las métricas de la aplicación. Por ejemplo, puede decidir que, para diagnosticar respuestas lentas, hay que establecer un filtro para descartar los tiempos de respuesta rápidos. Sin embargo, debe tener en cuenta que los tiempos de respuesta medios notificados por Application Insights serán más lentos que la velocidad real. Además, el recuento de solicitudes será menor que el recuento real.

Si puede resultar un problema, use el muestreo en su lugar.

Establecer filtros

En ApplicationInsights.xml, agregue una sección TelemetryProcessors como la de este ejemplo:


    <ApplicationInsights>
      <TelemetryProcessors>

        <BuiltInProcessors>
           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="100"/>
                  <Add name="NotNeededResponseCodes" value="200-400"/>
           </Processor>

           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="100"/>
                  <Add name="NotNeededNames" value="home,index"/>
                  <Add name="NotNeededUrls" value=".jpg,.css"/>
           </Processor>

           <Processor type="TelemetryEventFilter">
                  <!-- Names of events we don't want to see -->
                  <Add name="NotNeededNames" value="Start,Stop,Pause"/>
           </Processor>

           <!-- Exclude telemetry from availability tests and bots -->
           <Processor type="SyntheticSourceFilter">
                <!-- Optional: specify which synthetic sources,
                     comma-separated
                     - default is all synthetics -->
                <Add name="NotNeededSources" value="Application Insights Availability Monitoring,BingPreview"
           </Processor>

        </BuiltInProcessors>

        <CustomProcessors>
          <Processor type="com.fabrikam.MyFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>

      </TelemetryProcessors>
    </ApplicationInsights>

Inspeccione el conjunto completo de procesadores integrados.

Filtros integrados

En esta sección se describen los filtros integrados que están disponibles.

Filtro de telemetría de métricas


           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>
  • NotNeeded: lista de nombres personalizados de métricas separada por comas.

Filtro de telemetría de vista de página


           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="500"/>
                  <Add name="NotNeededNames" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>
  • DurationThresholdInMS: la duración se refiere al tiempo dedicado a cargar la página. Si se establece este parámetro, las páginas que se cargan a una velocidad mayor que este tiempo no se notifican.
  • NotNeededNames: lista de nombres de página separada por comas.
  • NotNeededUrls: lista de fragmentos de URL separada por comas. Por ejemplo, "home" filtra todas las páginas que tienen "inicio" en la dirección URL.

Filtro de telemetría de solicitudes


           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="500"/>
                  <Add name="NotNeededResponseCodes" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>

Filtro de origen sintético

Filtra toda la telemetría con valores en la propiedad SyntheticSource. Se incluyen solicitudes de bots, spiders y pruebas de disponibilidad.

Filtra la telemetría de todas las solicitudes sintéticas:


           <Processor type="SyntheticSourceFilter" />

Filtra la telemetría de orígenes sintéticos específicos:


           <Processor type="SyntheticSourceFilter" >
                  <Add name="NotNeeded" value="source1,source2"/>
           </Processor>
  • NotNeeded: lista de nombres de origen sintético separada por comas.

Filtro de eventos de telemetría

Filtra los eventos personalizados que se registraron mediante TrackEvent():


           <Processor type="TelemetryEventFilter" >
                  <Add name="NotNeededNames" value="event1, event2"/>
           </Processor>
  • NotNeededNames: lista de nombres de eventos separada por comas.

Filtro de telemetría de seguimiento

Filtra los seguimientos de registros mediante TrackTrace() o un recopilador de plataforma de registro:


           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

  • Los valores válidos de FromSeverityLevel son:

    • OFF: filtra todos los seguimientos.
    • TRACE: no hay filtrado. Es igual al nivel TRACE.
    • INFO: filtra el nivel TRACE.
    • WARN: filtra los niveles TRACE e INFO.
    • ERROR: filtra los niveles WARN, INFO, y TRACE.
    • CRITICAL: filtra todo excepto el nivel CRITICAL.

Filtros personalizados

En las secciones siguientes se muestran los pasos para crear sus propios filtros personalizados.

Codificación del filtro

En el código, cree una clase que implemente TelemetryProcessor:


    package com.fabrikam.MyFilter;
    import com.microsoft.applicationinsights.extensibility.TelemetryProcessor;
    import com.microsoft.applicationinsights.telemetry.Telemetry;

    public class SuccessFilter implements TelemetryProcessor {

        /* Any parameters that are required to support the filter.*/
        private final String successful;

        /* Initializers for the parameters, named "setParameterName" */
        public void setNotNeeded(String successful)
        {
            this.successful = successful;
        }

        /* This method is called for each item of telemetry to be sent.
           Return false to discard it.
           Return true to allow other processors to inspect it. */
        @Override
        public boolean process(Telemetry telemetry) {
            if (telemetry == null) { return true; }
            if (telemetry instanceof RequestTelemetry)
            {
                RequestTelemetry requestTelemetry = (RequestTelemetry)    telemetry;
                return request.getSuccess() == successful;
            }
            return true;
        }
    }

Invocación del filtro en el archivo de configuración

Ahora, en ApplicationInsights.xml:



    <ApplicationInsights>
      <TelemetryProcessors>
        <CustomProcessors>
          <Processor type="com.fabrikam.SuccessFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>
      </TelemetryProcessors>
    </ApplicationInsights>

Invocación del filtro (Java Spring)

En el caso de las aplicaciones basadas en el marco Spring, los procesadores de telemetría personalizados deben registrarse en la clase principal de la aplicación como un bean. Luego, cuando se inicie la aplicación, se conectarán automáticamente.

@Bean
public TelemetryProcessor successFilter() {
      return new SuccessFilter();
}

Cree sus propios parámetros de filtro en application.properties. A continuación, use el marco de configuración externalizado de Spring Boot para pasar esos parámetros al filtro personalizado.

Solución de problemas

En esta sección se ofrece una sugerencia de solución de problemas.

El filtro no funciona

Compruebe que ha proporcionado valores de parámetro válidos. Por ejemplo, las duraciones deben ser números enteros. Unos valores no válidos hará que el filtro que ignore. Si el filtro personalizado produce una excepción desde un constructor o el método set, se omitirá.

collectd: métricas de rendimiento de Linux en Application Insights (en desuso)

Para explorar las métricas de rendimiento del sistema de Linux en Application Insights, instale collectd junto con su complemento Application Insights. Esta solución de código abierto recopila diversas estadísticas de red y del sistema.

Normalmente, usará collectd si ya ha instrumentado el servicio web de Java con Application Insights. Así obtendrá más datos para ayudarlo a mejorar el rendimiento de la aplicación o a diagnosticar los problemas.

Obtención de la clave de instrumentación

En Azure Portal, abra el recurso Application Insights donde quiere que aparezcan los datos. O bien, puede crear un nuevo recurso.

Realice una copia de la clave de instrumentación, que identifica el recurso.

Captura de pantalla que muestra el panel de información general de un recurso Application Insights en Azure Portal con la clave de instrumentación resaltada.

Instalación de collectd y del complemento

En los equipos de servidor Linux:

  1. Instale la versión de collectd 5.4.0 o posterior.
  2. Descargue el complemento del escritor collectd de Application Insights. Anote el número de versión.
  3. Copie el archivo .jar del complemento en /usr/share/collectd/java.
  4. Edite /etc/collectd/collectd.conf:

    • Asegúrese de que el complemento de Java está habilitado.

    • Actualice el elemento JVMArg para que java.class.path incluya el archivo .jar siguiente. Actualice el número de versión para que coincida con el que descargó:

      • /usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar

    • Agregue este fragmento de código con la clave de instrumentación del recurso:

      
     LoadPlugin "com.microsoft.applicationinsights.collectd.ApplicationInsightsWriter"
     <Plugin ApplicationInsightsWriter>
        InstrumentationKey "Your key"
     </Plugin>

      A continuación se muestra un archivo de configuración de ejemplo:

      
    ...
    # collectd plugins
    LoadPlugin cpu
    LoadPlugin disk
    LoadPlugin load
    ...

    # Enable Java Plugin
    LoadPlugin "java"

    # Configure Java Plugin
    <Plugin "java">
      JVMArg "-verbose:jni"
      JVMArg "-Djava.class.path=/usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar:/usr/share/collectd/java/collectd-api.jar"

      # Enabling Application Insights plugin
      LoadPlugin "com.microsoft.applicationinsights.collectd.ApplicationInsightsWriter"

      # Configuring Application Insights plugin
      <Plugin ApplicationInsightsWriter>
        InstrumentationKey "12345678-1234-1234-1234-123456781234"
      </Plugin>

      # Other plugin configurations ...
      ...
    </Plugin>
    ...

Configure otros complementos collectd, que pueden recopilar diversos datos de distintos orígenes.

Reinicie collectd de acuerdo con su manual.

Visualización de los datos en Application Insights

En el recurso Application Insights, abra Métricas y agregue gráficos. Seleccione las métricas que quiere ver en la categoría Personalizado.

De forma predeterminada, las métricas se agregan en todos los equipos host desde los que se recopilaron estas. Para ver las métricas por host, en el panel Detalles del gráfico, active Agrupación y elija agrupar por CollectD-Host.

Exclusión de estadísticas específicas de la carga

De forma predeterminada, el complemento de Application Insights envía todos los datos recopilados por todos los complementos collectd read habilitados.

Para excluir los datos de orígenes de datos o complementos específicos:

  • Edite el archivo de configuración.

  • En <Plugin ApplicationInsightsWriter>, agregue líneas de directiva como las de la tabla siguiente:

    Directiva Efecto
    Exclude disk Excluya todos los datos recopilados por el complemento disk.
    Exclude disk:read,write Excluya los orígenes denominados read y write del complemento disk.

Separar directivas con una nueva línea.

¿Tiene problemas?

En esta sección se ofrecen sugerencias para solucionar problemas.

No veo datos en el portal

Pruebe estas opciones:

  • Abra Buscar para ver si han llegado los eventos sin procesar. A veces tardan más en aparecer en el Explorador de métricas.
  • Es posible que deba establecer excepciones del firewall para los datos salientes.
  • Habilite el seguimiento en el complemento Application Insights. Agregue esta línea en <Plugin ApplicationInsightsWriter>:
    • SDKLogger true
  • Abra un terminal e inicie collectd en modo detallado para ver los posibles problemas que se estén notificando:
    • sudo collectd -f

Problema conocido

El complemento de escritura de Application Insights no es compatible con determinados complementos de lectura. En ocasiones, algunos complementos envían NaN, pero el complemento de Application Insights espera un número de punto flotante.

  • Síntoma: el registro collectd muestra errores que incluyen "AI:... SyntaxError: token inesperado N".
  • Solución alternativa: excluya los datos recopilados por los complementos de escritura con problemas.

La aplicación Micrometer supervisa las métricas de medidas para código de aplicación basado en JVM y le permite exportar los datos a los sistemas de supervisión que prefiera. Esta sección le muestra cómo usar Micrometer con Application Insights tanto para aplicaciones Spring Boot como para las que no sean Spring Boot.

Uso de Spring Boot 1.5x

Agregue las siguientes dependencias al archivo pom.xml o al archivo build.gradle:

  • Application Insights pring-boot-starter 2.5.0 o posterior.
  • Micrometer Azure Registry 1.1.0 o posterior.
  • Micrometer Spring Legacy 1.1.0 o posterior. Retroimporta el código de configuración automática en la plataforma de Spring.
  • Recurso ApplicationInsights.

Siga estos pasos:

  1. Actualice el archivo pom.xml de la aplicación Spring Boot y agréguele las siguientes dependencias:

    <dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>applicationinsights-spring-boot-starter</artifactId>
    <version>2.5.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-spring-legacy</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-azure-monitor</artifactId>
    <version>1.1.0</version>
</dependency>

  2. Actualice el archivo application.properties o YML con la clave de instrumentación de Application Insights mediante la siguiente propiedad:

    azure.application-insights.instrumentation-key=<your-instrumentation-key-here>

  3. Compile la aplicación y ejecútela.

Los pasos anteriores deberían conseguir que empezara a ejecutar las métricas agregadas previamente y recopiladas de forma automática para Azure Monitor.

Uso de Spring 2.x

Agregue las siguientes dependencias al archivo pom.xml o al archivo build.gradle:

Siga estos pasos:

  1. Actualice el archivo pom.xml de la aplicación de Spring Boot y agréguele la siguiente dependencia:

    <dependency> 
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure-spring-boot-metrics-starter</artifactId>
      <version>2.0.7</version>
</dependency>

  2. Actualice el archivo application.properties o YML con la clave de instrumentación de Application Insights mediante la siguiente propiedad:

    azure.application-insights.instrumentation-key=<your-instrumentation-key-here>

  3. Compile la aplicación y ejecútela.

Los pasos anteriores deberían conseguir que empezara a ejecutar las métricas agregadas previamente y recopiladas de forma automática para Azure Monitor. Para más información sobre cómo optimizar Spring Boot Starter de Application Insights, consulte el archivo Léame en GitHub.

Métricas predeterminadas:

  • Se configuran métricas automáticamente para Tomcat, JVM, Logback Metrics, Log4J Metrics, Uptime Metrics, Processor Metrics y FileDescriptorMetrics.
  • Por ejemplo, si Netflix Hystrix está presente en la ruta de acceso de la clase, también obtenemos esas métricas.
  • Las siguientes métricas pueden estar disponibles al agregar los beans respectivos:
    • CacheMetrics (CaffeineCache, EhCache2, GuavaCache, HazelcastCache y JCache)
    • DataBaseTableMetrics
    • HibernateMetrics
    • JettyMetrics
    • OkHttp3 Metrics
    • Kafka Metrics

Desactive la recopilación automática de métricas:

  • Métricas de JVM:
    • management.metrics.binders.jvm.enabled=false
  • Métricas de Logback:
    • management.metrics.binders.logback.enabled=false
  • Métricas de tiempo de actividad:
    • management.metrics.binders.uptime.enabled=false
  • Métricas de procesador:
    • management.metrics.binders.processor.enabled=false
  • FileDescriptorMetrics:
    • management.metrics.binders.files.enabled=false
  • Hystrix Metrics si la biblioteca está en classpath:
    • management.metrics.binders.hystrix.enabled=false
  • AspectJ Metrics si la biblioteca está en classpath:
    • spring.aop.enabled=false

Nota

Especifique las propiedades anteriores en el archivo application.properties o application.yml de la aplicación Spring Boot.

Uso de Micrometer con aplicaciones web que no son Spring Boot

Agregue las siguientes dependencias al archivo pom.xml o al archivo build.gradle:

Siga estos pasos:

  1. Agregue las siguientes dependencias al archivo pom.xml o build.gradle:

        <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-azure-monitor</artifactId>
        <version>1.1.0</version>
    </dependency>

    <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <version>2.5.0</version>
    </dependency>

  2. Si aún no lo ha hecho, agregue el archivo ApplicationInsights.xml a la carpeta de recursos. Para obtener más información, consulte Adición de un archivo ApplicationInsights.xml.

  3. Clase de Servlet de ejemplo (emite una métrica de temporizador):

        @WebServlet("/hello")
    public class TimedDemo extends HttpServlet {

      private static final long serialVersionUID = -4751096228274971485L;

      @Override
      @Timed(value = "hello.world")
      protected void doGet(HttpServletRequest request, HttpServletResponse response)
          throws ServletException, IOException {

        response.getWriter().println("Hello World!");
        MeterRegistry registry = (MeterRegistry) getServletContext().getAttribute("AzureMonitorMeterRegistry");

    //create new Timer metric
        Timer sampleTimer = registry.timer("timer");
        Stream<Integer> infiniteStream = Stream.iterate(0, i -> i+1);
        infiniteStream.limit(10).forEach(integer -> {
          try {
            Thread.sleep(1000);
            sampleTimer.record(integer, TimeUnit.MILLISECONDS);
          } catch (Exception e) {}
           });
      }
      @Override
      public void init() throws ServletException {
        System.out.println("Servlet " + this.getServletName() + " has started");
      }
      @Override
      public void destroy() {
        System.out.println("Servlet " + this.getServletName() + " has stopped");
      }

    }

  4. Clase de configuración de ejemplo:

         @WebListener
     public class MeterRegistryConfiguration implements ServletContextListener {

       @Override
       public void contextInitialized(ServletContextEvent servletContextEvent) {

     // Create AzureMonitorMeterRegistry
       private final AzureMonitorConfig config = new AzureMonitorConfig() {
         @Override
         public String get(String key) {
             return null;
         }
        @Override
           public Duration step() {
             return Duration.ofSeconds(60);}

         @Override
         public boolean enabled() {
             return false;
         }
     };

  MeterRegistry azureMeterRegistry = AzureMonitorMeterRegistry.builder(config);

         //set the config to be used elsewhere
         servletContextEvent.getServletContext().setAttribute("AzureMonitorMeterRegistry", azureMeterRegistry);

       }

       @Override
       public void contextDestroyed(ServletContextEvent servletContextEvent) {

       }
     }

Para más información sobre las métricas, consulte la documentación de Micrometer.

Otro ejemplo de código sobre cómo crear distintos tipos de métricas puede encontrarse en el repositorio de GitHub de Micrometer oficial.

Enlace de más recopilaciones de métricas

En las secciones siguientes se muestra cómo recopilar más métricas.

SpringBoot/Spring

Cree un bean de la categoría de métrica respectiva. Por ejemplo, supongamos que necesita las métricas de caché de Guava:

    @Bean
    GuavaCacheMetrics guavaCacheMetrics() {
        Return new GuavaCacheMetrics();
    }

Varias métricas no están habilitadas de forma predeterminada, pero se pueden enlazar de la manera anterior. Para obtener una lista completa, consulte el repositorio de GitHub de Micrometer.

Aplicaciones que no sean Spring

Agregue el siguiente código de enlace al archivo de configuración:

    New GuavaCacheMetrics().bind(registry);

Pasos siguientes