Configuración del SDK de Application Insights con ApplicationInsights.config o .xml

El SDK de Application Insights para .NET consta de numerosos paquetes de NuGet. El paquete principal proporciona la API para enviar telemetría a Application Insights. Numerosos paquetes proporcionan módulos e inicializadores de telemetría para hacer un seguimiento automático de la telemetría de la aplicación y su contexto. Si ajusta el archivo de configuración, puede habilitar o deshabilitar los módulos e inicializadores de telemetría. También puede establecer parámetros para algunos de ellos.

Nota:

La siguiente documentación se basa en la API clásica de Application Insights. El plan a largo plazo de Application Insights consiste en recopilar datos mediante OpenTelemetry. Para más información, consulte Habilitación de Azure Monitor OpenTelemetry para aplicaciones de .NET, Node.js, Python y Java.

El archivo de configuración se llama ApplicationInsights.config o ApplicationInsights.xml. El nombre depende del tipo de la aplicación. Se agrega automáticamente al proyecto cuando se instalan la mayoría de las versiones del SDK. De forma predeterminada, cuando se usa la experiencia automatizada de los proyectos de plantilla de Visual Studio que admiten Agregar>Telemetría de Application Insights, se crea el archivo ApplicationInsights.config en la carpeta raíz del proyecto. Cuando se compila, se copia en la carpeta bin. También es agregado a una aplicación web por el Agente de Application Insights en un servidor IIS. El archivo de configuración se omite si se usa la extensión para sitios web de Azure o la extensión para máquinas virtuales de Azure y conjuntos de escalado de máquinas virtuales.

No hay un archivo equivalente para controlar el SDK en una página web.

En este artículo se describen las secciones que verá en el archivo de configuración, cómo controlan los componentes del SDK y qué paquetes NuGet cargan esos componentes.

Nota

Las instrucciones de ApplicationInsights.config y .xml no se aplican al SDK de .NET Core. Para configurar aplicaciones de .NET Core, siga las instrucciones que se indican en Application Insights para aplicaciones de ASP.NET Core.

Módulos de telemetría (ASP.NET)

Cada módulo de telemetría recopila un tipo específico de datos y usa la API principal para enviar dichos datos. Los módulos los instalan diferentes paquetes NuGet, que también agregan las líneas necesarias al archivo .config.

Hay un nodo en el archivo de configuración para cada módulo. Para deshabilitar un módulo, elimine el nodo o conviértalo en comentario.

Seguimiento de dependencias

Dependency tracking recopila la telemetría sobre las llamadas que realiza la aplicación a bases de datos y a servicios y bases de datos externos. Para permitir que este módulo funcione en un servidor IIS, debe instalar el agente de Application Insights.

También puede escribir su propio código de seguimiento de dependencias con la API TrackDependency.

• Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
• Paquete NuGet Microsoft.ApplicationInsights.DependencyCollector

Se pueden recopilar dependencias automáticamente sin modificar el código mediante la asociación basada en agente (sin código). Para utilizarlo en aplicaciones web de Azure, habilite la extensión Application Insights. Para usarlo en una máquina virtual de Azure o en un conjunto de escalado de máquinas virtuales de Azure, habilite la extensión de supervisión de aplicaciones para máquinas virtuales y conjuntos de escalado de máquinas virtuales.

Recopilador de rendimiento

El recopilador de rendimiento recopila contadores de rendimiento del sistema como CPU, memoria y carga de la red desde instalaciones de IIS. Puede especificar qué contadores se recopilarán, incluidos los contadores de rendimiento que ha configurado usted mismo.

• Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
• Paquete NuGet Microsoft.ApplicationInsights.PerfCounterCollector

Telemetría de diagnósticos de Application Insights

La clase DiagnosticsTelemetryModule informa de errores en el propio código de instrumentación de Application Insights. Por ejemplo, si el código no puede acceder a los contadores de rendimiento o si ITelemetryInitializer inicia una excepción. La telemetría de seguimiento que sigue este módulo aparece en la Búsqueda de diagnóstico.

• Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
• Microsoft.ApplicationInsights . Si solamente se instala este paquete, el archivo ApplicationInsights.config no se crea automáticamente.

Modo de desarrollador

La clase DeveloperModeWithDebuggerAttachedTelemetryModule obliga al elemento TelemetryChannel de Application Insights a enviar datos inmediatamente, un elemento de telemetría cada vez, cuando se asocia un depurador al proceso de aplicación. Este diseño reduce la cantidad de tiempo entre el momento en que la aplicación realiza un seguimiento de la telemetría y el momento en que esta aparece en el portal de Application Insights. Esto provoca una sobrecarga considerable en la CPU y el ancho de banda.

• Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
• Application Insights Windows Server

Seguimiento de solicitud web

El seguimiento de solicitud web informa del tiempo de respuesta y del código de resultado de las solicitudes HTTP.

• Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
• Microsoft.ApplicationInsights.Web

Seguimiento de excepciones

La clase ExceptionTrackingTelemetryModule realiza el seguimiento de las excepciones no controladas en la aplicación web. Para más información, consulte Errores y excepciones.

• Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
• Paquete NuGet Microsoft.ApplicationInsights.Web.
• Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: realiza el seguimiento de las excepciones de tareas no supervisadas.
• Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: realiza el seguimiento de las excepciones no controladas de roles de trabajo, servicios de Windows y aplicaciones de consola.
• Application Insights Windows Server .

Seguimiento de EventSource

La clase EventSourceTelemetryModule permite configurar el envío de eventos EventSource a Application Insights como seguimientos. Para información sobre el seguimiento de eventos EventSource, consulte Uso de eventos EventSource.

• Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
• Microsoft.ApplicationInsights.EventSourceListener

Seguimiento de eventos ETW

La clase EtwCollectorTelemetryModule permite configurar el envío de eventos de proveedores ETW a Application Insights como seguimientos. Para información sobre el seguimiento de eventos ETW, consulte Uso de eventos ETW.

• Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
• Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

El paquete Microsoft.ApplicationInsights proporciona la API principal del SDK. Los demás módulos de telemetría usan esta API. También puede usarla para definir su propia telemetría.

• No hay entrada en ApplicationInsights.config.
• Microsoft.ApplicationInsights . Si solamente instala este NuGet, no se genera ningún archivo .config.

Canal de telemetría

El canal de telemetría administra el almacenamiento en búfer y la transmisión de telemetría al servicio Application Insights.

• Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel es el canal predeterminado para aplicaciones web. Almacena en búfer los datos en memoria y emplea mecanismos de reintento y almacenamiento en el disco local para proporcionar una entrega de telemetría más confiable.
• Microsoft.ApplicationInsights.InMemoryChannel es un canal de telemetría ligero. Se usa si no está configurado ningún otro canal.

Inicializadores de telemetría (ASP.NET)

Los inicializadores de telemetría establecen propiedades de contexto que se envían junto con todos los elementos de telemetría.

También puede escribir sus propios inicializadores para establecer propiedades de contexto.

Los inicializadores estándar están todos establecidos por los paquetes NuGet web o WindowsServer:

• AccountIdTelemetryInitializer establece la propiedad AccountId.

• AuthenticatedUserIdTelemetryInitializer establece la propiedad AuthenticatedUserId como está establecida por el SDK de JavaScript.

• AzureRoleEnvironmentTelemetryInitializer actualiza las propiedades RoleName y RoleInstance del contexto Device para todos los elementos de telemetría con información extraída del entorno de tiempo de ejecución de Azure.

• BuildInfoConfigComponentVersionTelemetryInitializer actualiza la propiedad Version del contexto Component para todos los elementos de telemetría con el valor extraído del archivo BuildInfo.config que produce MS Build.

• ClientIpHeaderTelemetryInitializer actualiza la propiedad Ip del contexto Location de todos los elementos de telemetría según el encabezado HTTP X-Forwarded-For de la solicitud.

• DeviceTelemetryInitializer actualiza las propiedades siguientes del contexto Device para todos los elementos de telemetría.

  • Type se establece en PC.
  • Id se establece en el nombre de dominio del equipo donde se ejecuta la aplicación web.
  • OemName se establece en el valor extraído del campo Win32_ComputerSystem.Manufacturer con WMI.
  • Model se establece en el valor extraído del campo Win32_ComputerSystem.Model con WMI.
  • NetworkType se establece en el valor extraído de la propiedad NetworkInterface.
  • Language se establece en el nombre de la propiedad CurrentCulture.

• DomainNameRoleInstanceTelemetryInitializer actualiza la propiedad RoleInstance del contexto Device para todos los elementos de telemetría con el nombre de dominio del equipo donde se ejecuta la aplicación web.

• OperationNameTelemetryInitializer actualiza la propiedad Name de RequestTelemetry y la propiedad Name del contexto Operation de todos los elementos de telemetría según el método HTTP, así como los nombres del controlador MVC de ASP.NET y la acción que se invoca para procesar la solicitud.

• OperationIdTelemetryInitializer o OperationCorrelationTelemetryInitializer actualizan la propiedad de contexto Operation.Id de todos los elementos de telemetría de los que se realiza un seguimiento mientras se controla una solicitud con el RequestTelemetry.Id que se genera.

• SessionTelemetryInitializer actualiza la propiedad Id del contexto Session de todos los elementos de telemetría con valores extraídos de la cookie ai_session que genera el código de instrumentación JavaScript de ApplicationInsights que se ejecuta en el explorador del usuario.

• SyntheticTelemetryInitializer o SyntheticUserAgentTelemetryInitializer actualiza las propiedades de los contextos User, Session y Operation de todos los elementos de telemetría rastreados al administrar una solicitud de un origen sintético, como una prueba de disponibilidad o un bot de motor de búsqueda. De forma predeterminada, el Explorador de métricas no muestra telemetría sintética.

  Conjunto de <Filters> que identifica las propiedades de las solicitudes.

• UserTelemetryInitializer actualiza las propiedades Id y AcquisitionDate del contexto User de todos los elementos de telemetría con valores extraídos de la cookie ai_user que genera el código de instrumentación JavaScript de Application Insights que se ejecuta en el explorador del usuario.

• WebTestTelemetryInitializer establece el identificador de usuario, el identificador de sesión y las propiedades de origen sintético de las solicitudes HTTP que proceden de pruebas de disponibilidad. Conjunto de <Filters> que identifica las propiedades de las solicitudes.

En el caso de las aplicaciones de .NET que se ejecutan en Azure Service Fabric, puede incluir el paquete NuGet Microsoft.ApplicationInsights.ServiceFabric. Este paquete incluye una propiedad FabricTelemetryInitializer, que agrega propiedades de Service Fabric a elementos de telemetría. Para obtener más información, consulte la página de GitHub sobre las propiedades que agrega este paquete de NuGet.

Procesadores de telemetría (ASP.NET)

Los procesadores de telemetría pueden filtrar y modificar cada elemento de telemetría justo antes de que se envíe desde el SDK al portal.

También puede escribir sus propios procesadores de telemetría.

Procesador de telemetría de muestreo adaptivo (desde 2.0.0-beta3)

Esta funcionalidad está habilitada de forma predeterminada. Si la aplicación envía una cantidad considerable de datos de telemetría, este procesador quita algunos de ellos.

    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

El parámetro proporciona el destino que el algoritmo intenta alcanzar. Cada instancia del SDK funciona de forma independiente. Por lo tanto, si el servidor es un clúster de varias máquinas, se multiplicará el volumen real de telemetría en consonancia.

Aprenda más sobre el muestreo.

Procesador de telemetría de muestreo de tasa fija (desde 2.0.0-beta1)

También hay un procesador de telemetría de muestreo estándar (desde la versión 2.0.1):

    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

Consulte los ejemplos de código de la cadena de conexión.

InstrumentationKey

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.

Esta configuración determina el recurso de Application Insights en el que aparecen los datos. Normalmente se crea un recurso independiente, con una clave independiente, para cada una de las aplicaciones.

Si quiere establecer la clave de forma dinámica (por ejemplo, si quiere enviar resultados de su aplicación a distintos recursos) puede omitir la clave del archivo de configuración y establecerla en el código.

Para establecer la clave de todas las instancias de TelemetryClient, incluidos los módulos de telemetría estándar, realice este paso en un método de inicialización, como global.aspx.cs en un servicio de ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Si solo quiere enviar un conjunto específico de eventos a un recurso diferente, puede establecer la clave para un cliente de telemetría específico:

    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Para obtener una nueva clave, cree un nuevo recurso en el portal de Application Insights.

Proveedor ApplicationId

El proveedor está disponible a partir de v2.6.0.

El propósito de este proveedor es buscar un identificador de aplicación basado en una clave de instrumentación. El identificador de aplicación se incluye en RequestTelemetry y DependencyTelemetry y se usa para determinar la correlación en el portal.

Esta funcionalidad está disponible estableciendo TelemetryConfiguration.ApplicationIdProvider en el código o en el archivo de configuración.

Interfaz: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Se proporcionan dos implementaciones en el SDK Microsoft.ApplicationInsights: ApplicationInsightsApplicationIdProvider y DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Este contenedor es para nuestra API Profile. Limita las solicitudes y los resultados en la memoria caché.

Este proveedor se agrega al archivo de configuración cuando se instala Microsoft.ApplicationInsights.DependencyCollector o Microsoft.ApplicationInsights.Web.

Esta clase tiene una propiedad ProfileQueryEndpoint opcional. De forma predeterminada, se establece en https://dc.services.visualstudio.com/api/profiles/{0}/appId. Si tiene que definir un proxy para esta configuración, se recomienda uno en la dirección base y la inclusión de "/api/profiles/{0}/appId". El valor {0} se sustituye en tiempo de ejecución en cada solicitud por la clave de instrumentación.

Ejemplo de configuración mediante ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Ejemplo de configuración mediante código

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Este proveedor estático se basa en los pares de clave de instrumentación e identificador de aplicación configurados.

Esta clase tiene la propiedad Defined, que es un elemento Dictionary<string,string> de pares de clave de instrumentación e identificador de aplicación.

Esta clase tiene la propiedad Next opcional que puede emplearse para configurar otro proveedor al solicitar una clave de instrumentación que no existe en la configuración.

Ejemplo de configuración mediante ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Ejemplo de configuración mediante código

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Configurar la recopilación de instantáneas para aplicaciones ASP.NET

Configure una recopilación de instantáneas para las aplicaciones ASP.NET.

Pasos siguientes

Más información sobre la API