Exploración de los registros de seguimiento de .NET, .NET Core y Python en Application Insights

  • Artículo

Envíe registros de seguimiento de diagnóstico para la aplicación ASP.NET/ASP.NET Core desde ILogger, NLog, log4Net o System.Diagnostics.Trace a Azure Application Insights. En el caso de las aplicaciones de Python, envíe registros de seguimiento de diagnóstico mediante AzureLogHandler en OpenCensus para Python para Azure Monitor. A continuación, puede explorar y buscarlos. Esos registros se fusionan con los demás archivos de registro de su aplicación. Puede usarlos para identificar las trazas asociadas a cada solicitud de usuario y correlacionarlas con otros eventos e informes de excepción.

Nota

¿Necesita el módulo de captura de registros? Es un adaptador útil para registradores de terceros, Pero si aún no usa NLog, log4Net o System.Diagnostics.Trace, considere la posibilidad de llamar a Application Insights TrackTrace().

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.

Instalación del registro en la aplicación

Instale el marco de registro elegido en el proyecto, lo que debería producir una entrada en app.config o web.config.

 <configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener" type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Configuración de Application Insights para recopilar registros

Agregue Application Insights al proyecto si aún no lo ha hecho y hay una opción para incluir el recopilador de registros.

También puede hacer clic con el botón derecho en el proyecto en el Explorador de soluciones para configurar Application Insights. Seleccione la opción Configure trace collection (Configurar recolección de seguimientos).

Nota

¿No aparece ningún menú de Application Insights ni ninguna opción de recopilador de registros? Pruebe la solución de problemas.

Instalación manual

Utilice este método si el tipo de proyecto no es compatible con el programa de instalación de Application Insights. Por ejemplo, si es un proyecto de escritorio de Windows.

  1. Si planea usar log4Net o NLog, instálelo en su proyecto.

  2. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Administrar paquetes NuGet.

  3. Busque Application Insights.

  4. Seleccione uno de los siguientes paquetes:

El paquete NuGet instala los ensamblados necesarios y, si es aplicable, modifica el archivo web.config o app.config.

ILogger

Para ver algunos ejemplos de uso de la implementación de ILogger para Application Insights con aplicaciones de consola y de ASP.NET Core, vea ApplicationInsightsLoggerProvider para registros ILogger de .NET Core.

Insertar llamadas de registro de diagnóstico

Si usa System.Diagnostics.Trace, una llamada típica sería:

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

Si prefiere log4net o NLog, use lo siguiente:

    logger.Warn("Slow response - database01");

Uso de eventos EventSource

Puede configurar eventos System.Diagnostics.Tracing.EventSource para enviarse a Application Insights como seguimientos. Primero, instale el paquete de NuGet Microsoft.ApplicationInsights.EventSourceListener. Seguidamente, edite la sección TelemetryModules del archivo ApplicationInsights.config.

    <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

En cada origen, puede establecer los siguientes parámetros:

  • Name especifica el nombre del evento EventSource que se recopilará.
  • Level especifica el nivel de registro que se recopilará: Critical, Error, Informational, LogAlways, Verbose o Warning.
  • Keywords (opcional) especifica el valor del entero de combinaciones de palabras clave que se usará.

Uso de eventos DiagnosticSource

Puede configurar eventos System.Diagnostics.DiagnosticSource para enviarlos a Application Insights como seguimientos. Primero, instale el paquete de NuGet Microsoft.ApplicationInsights.DiagnosticSourceListener. Después, edite la sección "TelemetryModules" del archivo ApplicationInsights.config.

    <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

Para cada instancia de origen de diagnóstico que quiera seguir, agregue una entrada con el atributo Name establecido con el nombre de la instancia origen de diagnóstico.

Uso de eventos ETW

Puede configurar eventos de Seguimiento de eventos para Windows (ETW) para enviarse a Application Insights como seguimientos. Primero, instale el paquete de NuGet Microsoft.ApplicationInsights.EtwCollector. Después, edite la sección "TelemetryModules" del archivo ApplicationInsights.config.

Nota

Solo se pueden recopilar eventos ETW si el proceso que hospeda el SDK se ejecuta bajo una identidad que sea miembro de Usuarios del registro de rendimiento o Administradores.

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

En cada origen, puede establecer los siguientes parámetros:

  • ProviderName es el nombre del proveedor ETW que se recopilará.
  • ProviderGuid especifica el GUID del proveedor ETW que se recopilará. Se puede usar en lugar de ProviderName.
  • Level establece el nivel de registro que se recopilará. Puede ser Critical, Error, Informational, LogAlways, Verbose o Warning.
  • Keywords (opcional) establece el valor del entero de combinaciones de palabras clave que se usará.

Uso de la API de seguimiento directamente

Puede llamar directamente a la API de seguimiento de Application Insights. Los adaptadores de registro usan esta API.

Por ejemplo:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Una ventaja de TrackTrace es que puede colocar datos relativamente largos en el mensaje. Por ejemplo, aquí puede codificar datos POST.

También puede agregar un nivel de gravedad al mensaje. Además, al igual que con otra telemetría, puede agregar valores de propiedad para ayudar a filtrar o buscar distintos conjuntos de seguimientos. Por ejemplo:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

Ahora puede filtrar fácilmente en la búsqueda de transacciones todos los mensajes de un determinado nivel de gravedad que estén relacionados con una base de datos específica.

AzureLogHandler para OpenCensus para Python

El controlador de registro de Azure Monitor permite exportar registros de Python a Azure Monitor.

Instrumente la aplicación con el SDK de OpenCensus para Python para Azure Monitor.

En este ejemplo se muestra cómo enviar un registro de nivel de advertencia a Azure Monitor.

import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>'))
logger.warning('Hello, World!')

Explorar los registros

Ejecute la aplicación en modo de depuración o impleméntela para que esté activa.

En el panel de información general de la aplicación, seleccione Búsqueda de transacciones.

Por ejemplo, puede:

  • Filtrar por seguimientos de registro o por elementos con determinadas propiedades.
  • Inspeccionar un elemento específico en detalle
  • Buscar otros datos de registro del sistema que se relacionen con la misma solicitud de usuario (tiene el mismo id. de operación).
  • Guardar la configuración de una página como favorita.

Nota

Si usa el SDK de Application Insights para ASP.NET versión 2.0.0-beta3 o posterior y la aplicación envía una gran cantidad de datos, la característica de muestreo adaptativo puede operar y enviar solamente una parte de los datos de telemetría. Aprenda más sobre el muestreo.

Solución de problemas

Obtenga respuestas a preguntas comunes.

¿Qué causa la telemetría retrasada, una red sobrecargada y una transmisión ineficaz?

System.Diagnostics.Tracing tiene una característica autoflush. Esta función hace que el SDK se vacíe con cada elemento de telemetría, lo que no es deseable, y puede causar problemas en el adaptador de registro, como retraso en la telemetría, una red sobrecargada y una transmisión ineficiente.

¿Cómo se puede hacer para Java?

En la instrumentación sin código de Java, que es la recomendada, los registros se recogen de forma inmediata. Use Agente de Java 3.0.

El agente de Java de Application Insights recopila registros de Log4j, Logback y java.util.logging de manera inmediata.

¿Por qué no hay ninguna opción de Application Insights en el menú contextual del proyecto?

  • Asegúrese de que Developer Analytics Tools está instalado en el equipo de desarrollo. En Visual Studio, vaya a Herramientas>Extensiones y actualizaciones, y busque Developer Analytics Tools. Si no se encuentra en la pestaña Instalado, abra la pestaña En línea e instálelo.
  • Es posible que este tipo de proyecto no sea compatible con las Developer Analytics Tools. Use la instalación manual.

¿Por qué no hay una opción de adaptador de registro en la herramienta de configuración?

  • Instale primero la plataforma de registro.
  • Si usa System.Diagnostics.Trace, asegúrese de que lo ha configurado en web.config.
  • Asegúrese de que tiene la última versión de Application Insights. En Visual Studio, vaya a Herramientas>Extensiones y actualizaciones, y abra la pestaña Actualizaciones. Si Developer Analytics Tools está instalado, selecciónelo para actualizarlo.

¿Por qué aparece el mensaje de error "La clave de instrumentación no puede estar vacía"?

Probablemente haya instalado el paquete NuGet del adaptador de registro sin instalar Application Insights. En el Explorador de soluciones, haga clic con el botón derecho en ApplicationInsights.config y seleccione Actualizar Application Insights. Se le pedirá que inicie sesión en Azure y que cree un recurso de Application Insights o que vuelva a usar uno existente. Eso debería corregir el problema.

El paso de todos los eventos y solicitudes por la canalización puede llevar un rato.

¿Qué cantidad de datos se conserva?

Hay varios factores que afectan a la cantidad de datos que se conservan. Para obtener más información, vea la sección Límites de la página de métricas de eventos de cliente.

¿Por qué no veo las entradas de registro que esperaba?

Tal vez su aplicación envíe cantidades voluminosas de datos y use el SDK de Application Insights para ASP.NET versión 2.0.0-beta3 o posterior. En este caso, la característica de muestreo adaptable puede funcionar y enviar solo una parte de la telemetría. Aprenda más sobre el muestreo.

Pasos siguientes