Introducción a Application Insights en un proyecto web de Java

Precaución

Este documento se aplica a Application Insights para 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 tutorial, se usa el SDK de Application Insights para instrumentar solicitudes, realizar un seguimiento de 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.

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

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.

    En la información general de nuevos recursos, haga clic en Propiedades y copie la clave de instrumentació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.

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

  • ¿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 también proporciona métricas que realizan el seguimiento de los recuentos de solicitudes de servlet HTTP y los tiempos de respuesta, pero requiere el registro manual del filtro de servlet de Application Insights en la aplicación.
    • applicationinsights-core solo 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, para la supervisión de aplicaciones Java se recomienda el uso de Java 3.x para Application Insights. Para más información sobre cómo empezar, consulte Java 3.x para Application Insights.

Adición de un 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 una 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:

  1. Propiedad del sistema: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. Variable de entorno: APPINSIGHTS_INSTRUMENTATIONKEY
  3. 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 el equipo de desarrollo o bien publíquela en el servidor.

Visualización de la telemetría en Application Insights

Vuelva al recurso de Application Insights en el Portal de Microsoft Azure.

Los datos de las solicitudes HTTP aparecen en la hoja de información general. (Si todavía no está ahí, espere unos segundos y, a continuación, haga clic en Actualizar).

Captura de pantalla de información general con datos de ejemplo

Más información acerca de las métricas.

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

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.

Profundización en una vista de ejemplo concreta

Análisis: Lenguaje de consulta eficaz

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

Ejemplo de Analytics

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 de sistema http.proxyHost y http.proxyPort.

  • En los servidores de Windows, instale:

Azure App Service, AKS y 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 Java 3.x para Application Insights.

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 a través de JDBC, con datos de tiempo.

También sirve para la nomenclatura automática de las operaciones.

Seguimiento distribuido de W3C

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

La configuración del SDK de entrada se explica más en detalle en nuestro artículo sobre correlación.

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

Contadores de rendimiento

Abra Investigar y Métricas para ver un intervalo de contadores de rendimiento.

Captura de pantalla del panel de métricas con los bytes privados del 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>

Recopilar contadores de rendimiento adicionales

Puede especificar contadores de rendimiento adicionales que se van a 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 '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 numeradas.

    <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 una cadena vacía (""), si la categoría contiene una sola instancia. Si categoryName es Proceso, y el contador de rendimiento que desea recopilar está en el proceso de JVM actual en que se ejecuta la aplicación, especifique "__SELF__".

Contadores de rendimiento de Unix

Obtención de datos de usuario y sesión

Bien, va a enviar telemetría desde el servidor web. Ahora, para obtener la visión completa de 360 grados de la aplicación, puede agregar mayor 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.

Obtenga 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.

Pasos siguientes