Application Insights para aplicaciones de ASP.NET Core

En este artículo se describe cómo habilitar y configurar Application Insights para una aplicación de ASP.NET Core.

Precaución

Se recomienda Distribución de OpenTelemetry de Azure Monitor para nuevas aplicaciones o clientes para poder Application Insights de Azure Monitor. La Distribución de OpenTelemetry de Azure Monitor ofrece una funcionalidad y experiencia similares al SDK de Application Insights. Es posible migrar desde el SDK de Application Insights mediante las guías de migración para .NET, Node.jsy Python, pero todavía estamos trabajando para agregar una algunas características más para la compatibilidad con versiones anteriores.

Application Insights puede recopilar los siguientes datos de telemetría de la aplicación de ASP.NET Core:

• Requests
• Dependencias
• Excepciones
• Contadores de rendimiento
• Latidos
• Registros

Usaremos un ejemplo de aplicación MVC. Si usa el servicio Worker, siga las instrucciones de Application Insights para aplicaciones del servicio Worker.

Hay disponible una oferta de .NET basada en OpenTelemetry. Para más información, consulte la introducción a OpenTelemetry.

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.

Nota

Si quiere usar el proveedor ILogger independiente, use Microsoft.Extensions.Logging.ApplicationInsight.

Escenarios admitidos

El SDK de Application Insights para ASP.NET Core puede supervisar sus aplicaciones, independientemente de dónde y cómo se ejecuten. Si la aplicación se está ejecutando y tiene conectividad de red a Azure, se pueden recopilar datos de telemetría. La supervisión de Application Insights se admite en cualquier lugar en que se admita .NET Core y abarca los siguientes escenarios:

• Sistema operativo: Windows, Linux o Mac.
• Método de hospedaje: en el proceso o fuera del proceso.
• Método de implementación: marco dependiente o independiente.
• Servidor web: Internet Information Server (IIS) o Kestrel
• Plataforma de hospedaje: la característica Web Apps de Azure App Service, Microsoft Azure Virtual Machines, Docker y Azure Kubernetes Service (AKS).
• Versión de .NET: todas las versiones de .NET compatibles oficialmente que no están en versión preliminar
• IDE: Visual Studio, Visual Studio Code o la línea de comandos.

Requisitos previos

• Una aplicación de ASP.NET Core en funcionamiento. Si necesita crear una aplicación de ASP .NET Core, siga este tutorial de ASP.NET Core.
• Referencia a una versión compatible del paquete NuGet de Application Insights.
• Una cadena de conexión de Application Insights válida. Esta cadena es necesaria para enviar los datos de telemetría a Application Insights. Si necesita crear un nuevo recurso de Application Insights para obtener un cadena de conexión, consulte Creación de recursos en Application Insights.

Habilitación de la telemetría de Application Insights del lado servidor (Visual Studio)

En caso de Visual Studio para Mac, use las instrucciones manuales. Solo la versión de Windows de Visual Studio admite este procedimiento.

1. Abra el proyecto en Visual Studio.

2. Vaya a Proyecto>Agregar Telemetría de Application Insights.

3. Seleccione Aplicación de Azure Insights>Siguiente.

4. Elija su suscripción y una instancia de Application Insights. O bien, puede crear una instancia con Crear nueva. Seleccione Next (Siguiente).

5. Agregue o confirme la cadena de conexión de Application Insights. Debe rellenarse previamente en función de lo que se haya seleccionado en el paso anterior. Seleccione Finalizar.

6. Después de agregar Application Insights al proyecto, confirme que está usando la versión estable más reciente del SDK. Vaya a Proyecto>Administrar paquetes NuGet>Microsoft.ApplicationInsights.AspNetCore. Si es necesario, seleccione Actualizar.

   

Habilitación de la telemetría de Application Insights del lado servidor (sin Visual Studio)

1. Instale el SDK de Application Insights desde el paquete de NuGet para ASP.NET Core.

   Se recomienda que use siempre la versión estable más reciente. Consulte las notas de la versión completa para el SDK en el repositorio de GitHub de código abierto.

   En el ejemplo de código siguiente se muestran los cambios que se van a agregar al archivo de .csproj del proyecto:

   <ItemGroup>
       <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
   </ItemGroup>
   

2. Agregue AddApplicationInsightsTelemetry() a la clase program.cs.

   Agregue builder.Services.AddApplicationInsightsTelemetry(); después del método WebApplication.CreateBuilder(), como en este ejemplo:

   // This method gets called by the runtime. Use this method to add services to the container.
   var builder = WebApplication.CreateBuilder(args);
   
   // The following line enables Application Insights telemetry collection.
   builder.Services.AddApplicationInsightsTelemetry();
   
   // This code adds other services for your application.
   builder.Services.AddMvc();
   
   var app = builder.Build();
   

3. Agregue la cadena de conexión, que se puede realizar de tres maneras:

   • (Recomendado) Establezca la cadena de conexión en la configuración.

     Establezca la cadena de conexión en appsettings.json y asegúrese de que el archivo de configuración se copia en la carpeta raíz de la aplicación durante la publicación.

     {
         "Logging": {
             "LogLevel": {
                 "Default": "Information",
                 "Microsoft.AspNetCore": "Warning"
             }
         },
         "AllowedHosts": "*",
         "ApplicationInsights": {
             "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
         }
     }
     

   • Establezca la cadena de conexión en la variable de entorno APPLICATIONINSIGHTS_CONNECTION_STRING o ApplicationInsights:ConnectionString en el archivo de configuración JSON.

     Por ejemplo:

     • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
     • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     • Normalmente, APPLICATIONINSIGHTS_CONNECTION_STRING se usa en Web Apps. También se puede usar en todos los lugares en los que se admita este SDK.

     Nota

     Las cadenas de conexión especificadas en el código prevalecen frente a la variables del entorno APPLICATIONINSIGHTS_CONNECTION_STRING, que a su vez prevalece sobre otras opciones.

   • Establezca la cadena de conexión en el código.

     Proporcione una cadena de conexión como parte del argumento ApplicationInsightsServiceOptions para AddApplicationInsightsTelemetry en la clase program.cs.

Secretos de usuario y otros proveedores de configuración

Si desea almacenar la cadena de conexión en los secretos de usuario de ASP.NET Core o recuperarla de otro proveedor de configuración, puede usar la sobrecarga con un parámetro Microsoft.Extensions.Configuration.IConfiguration. Un parámetro de ejemplo es services.AddApplicationInsightsTelemetry(Configuration);.

En Microsoft.ApplicationInsights.AspNetCorela versión 2.15.0, y posteriores, al llamar a services.AddApplicationInsightsTelemetry() se lee automáticamente la cadena de conexión desde Microsoft.Extensions.Configuration.IConfiguration de la aplicación. No es necesario proporcionar explícitamente el valor de IConfiguration.

Si IConfiguration ha cargado la configuración de varios proveedores, services.AddApplicationInsightsTelemetry prioriza la configuración de appsettings.json, independientemente del orden en que se agreguen los proveedores. Use el método services.AddApplicationInsightsTelemetry(IConfiguration) para leer la configuración de IConfiguration sin este trato preferencial para appsettings.json.

Ejecución de la aplicación

Ejecute la aplicación y realícele solicitudes. Ahora, la telemetría debería fluir hacia Application Insights. El SDK de Application Insights recopila automáticamente las solicitudes web entrantes en la aplicación, junto con la telemetría siguiente.

Live metrics

Live metrics se puede usar para comprobar rápidamente si la supervisión de aplicaciones con Application Insights está configurada correctamente. La telemetría puede tardar unos minutos en aparecer en Azure Portal, pero el panel de métricas dinámicas muestra el uso de CPU del proceso en ejecución casi en tiempo real. También puede mostrar otros tipos de telemetría, como las solicitudes, las dependencias y los seguimientos.

Habilitación de Live Metrics mediante código en cualquier aplicación .NET

Nota:

La característica Live Metrics se habilitará de forma predeterminada si se incorpora mediante las instrucciones recomendadas para aplicaciones .NET.

Para configurar Live Metrics manualmente:

1. Instale el paquete NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. El siguiente código de aplicación de consola de ejemplo muestra la configuración de Live Metrics:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

El ejemplo anterior es para una aplicación de consola, pero se puede usar el mismo código en cualquier aplicación .NET. Si cualquier otro módulo de telemetría se habilita para recopilar automáticamente la telemetría, es importante asegurarse de que la misma configuración que se use para la inicialización de los módulos también se emplee para el módulo de Live Metrics.

Registros de ILogger

La configuración predeterminada recopila los registros ILogger Warning y los registros más graves. Para más información, consulte ¿Cómo puedo personalizar la colección de registros de ILogger?.

Dependencias

La recopilación de dependencias está habilitada de manera predeterminada. En Seguimiento de dependencias en Application Insights se explican las dependencias que se recopilan automáticamente y que también contienen pasos para realizar el seguimiento manual.

Contadores de rendimiento

La compatibilidad con los contadores de rendimiento en ASP.Net Core es limitada:

• Las versiones 2.4.1 y posteriores del SDK recopilan los contadores de rendimiento si la aplicación se ejecuta en Web Apps (Windows).
• Las versiones 2.7.1 y posteriores del SDK recopilan contadores de rendimiento si la aplicación se ejecuta en Windows y tiene como destino netstandard2.0 o una versión posterior.
• Para las aplicaciones que tienen como destino .NET Framework, todas las versiones del SDK admiten contadores de rendimiento.
• Las versiones 2.8.0 y posteriores del SDK admiten el contador de CPU/memoria de Linux. No se admite ningún otro contador en Linux. Para obtener contadores del sistema en Linux y otros entornos que no son Windows, use EventCounters.

EventCounter

EventCounterCollectionModule está habilitado de forma predeterminada. Para obtener información sobre cómo configurar la lista de contadores que se recopilarán, consulte Introducción a EventCounters.

Enriquecimiento de datos a través de HTTP

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Habilitación de la telemetría del lado cliente para aplicaciones web

Los pasos anteriores son suficientes para ayudarle a empezar a recopilar datos de telemetría del lado servidor. Si la aplicación tiene componentes del lado cliente, siga estos pasos para comenzar a recopilar la telemetría de uso mediante la inserción del script del cargador del SDK de JavaScript (Web) por configuración.

1. En _ViewImports.cshtml, agregue inyección:

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. En _Layout.cshtml, inserte HtmlHelper al final de la sección <head>, pero antes de cualquier otro script. Si quiere informar de cualquier telemetría de JavaScript desde la página, insértela después de este fragmento de código:

       @Html.Raw(JavaScriptSnippet.FullScript)
   </head>
   

Como alternativa al uso de FullScript, ScriptBody está disponible a partir del SDK de Application Insights para ASP.NET Core, versión 2.14. Use ScriptBody si necesita controlar la etiqueta <script> para establecer una directiva de seguridad de contenido:

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

Los .cshtml nombres de archivo a los que se hace referencia anteriormente proceden de una plantilla de aplicación MVC predeterminada. En última instancia, si desea habilitar correctamente la supervisión del lado cliente para la aplicación, el script del cargador del SDK de JavaScript (web) debe aparecer en la sección <head> de cada página de la aplicación que desea supervisar. Agregue el script del cargador del SDK de JavaScript (Web) a _Layout.cshtml en una plantilla de aplicación para habilitar la supervisión del lado cliente.

Si el proyecto no incluye _Layout.cshtml, todavía puede agregar supervisión del lado cliente agregando el script de cargador del SDK de JavaScript (Web) a un archivo equivalente que controla el <head> de todas las páginas de la aplicación. También puede agregar el script del cargador del SDK de JavaScript (Web) a varias páginas, pero esto no es recomendable.

Nota

La inserción de JavaScript proporciona una experiencia de configuración predeterminada. Si necesita una realizar una configuración que vaya más allá de establecer la cadena de conexión, debe quitar la inserción automática,tal como se ha descrito, y agregar manualmente el SDK de JavaScript.

Configuración del SDK de Application Insights

Puede personalizar el SDK de Application Insights para ASP.NET Core para cambiar la configuración predeterminada. Es posible que los usuarios del SDK de Application Insights ASP.NET estén familiarizados con el cambio de configuración mediante applicationInsights.config o modificando TelemetryConfiguration.Active. Para ASP.NET Core, realice casi todos los cambios de configuración en el ConfigureServices()método de la clase Startup.cs, a menos que se le indique lo contrario. Para más información, consulte las siguientes secciones.

Nota

En las aplicaciones de ASP.NET Core, no se admite cambiar la configuración modificando TelemetryConfiguration.Active.

Utilice ApplicationInsightsServiceOptions

Puede modificar algunos ajustes de configuración comunes pasando de ApplicationInsightsServiceOptions a AddApplicationInsightsTelemetry, como se muestra en este ejemplo:

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

Esta tabla contiene la lista completa de valores ApplicationInsightsServiceOptions:

Configuración	Descripción	Valor predeterminado
EnablePerformanceCounterCollectionModule	Habilitar o deshabilitar PerformanceCounterCollectionModule.	True
EnableRequestTrackingTelemetryModule	Habilitar o deshabilitar RequestTrackingTelemetryModule.	True
EnableEventCounterCollectionModule	Habilitar o deshabilitar EventCounterCollectionModule.	True
EnableDependencyTrackingTelemetryModule	Habilitar o deshabilitar DependencyTrackingTelemetryModule.	True
EnableAppServicesHeartbeatTelemetryModule	Habilitar o deshabilitar AppServicesHeartbeatTelemetryModule.	True
EnableAzureInstanceMetadataTelemetryModule	Habilitar o deshabilitar AzureInstanceMetadataTelemetryModule.	True
EnableQuickPulseMetricStream	Habilitar o deshabilitar la característica LiveMetrics.	Verdadero
EnableAdaptiveSampling	Habilitar o deshabilitar el muestreo adaptable.	Verdadero
EnableHeartbeat	Habilitar o deshabilitar la característica de latidos. Esta envía periódicamente (cada 15 minutos de forma predeterminada) una métrica personalizada denominada HeartbeatState con información sobre el entorno de ejecución; por ejemplo, la versión de .NET e información del entorno de Azure, si procede.	Verdadero
AddAutoCollectedMetricExtractor	Habilitar o deshabilitar AutoCollectedMetrics extractor. Este procesador de telemetría envía métricas agregadas previamente sobre solicitudes o dependencias antes de que tenga lugar el muestreo.	True
RequestCollectionOptions.TrackExceptions	Habilitar o deshabilitar los informes de seguimiento de excepciones no controladas por parte del módulo de recopilación de solicitudes.	False en netstandard2.0 (porque se realiza un seguimiento de las excepciones con ApplicationInsightsLoggerProvider). True en caso contrario.
EnableDiagnosticsTelemetryModule	Habilitar o deshabilitar DiagnosticsTelemetryModule. La deshabilitación hace que se omita la siguiente configuración: EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule y EnableAppServicesHeartbeatTelemetryModule.	True

Para obtener una lista más actualizada, vea los valores configurables en ApplicationInsightsServiceOptions.

Recomendación de configuración para la versión 2.15.0 y posterior del SDK de Microsoft.ApplicationInsights.AspNetCore

En microsoft.ApplicationInsights.AspNetCore SDK, versión 2.15.0 y posteriores, configure todos los valores disponibles en ApplicationInsightsServiceOptions, incluido ConnectionString. Use la instancia IConfiguration de la aplicación. La configuración debe estar en la sección ApplicationInsights, como se muestra en el ejemplo siguiente. La siguiente sección de appSettings.json configura la cadena de conexión y deshabilita el muestreo adaptable y la recopilación de contadores de rendimiento.

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Si se usa builder.Services.AddApplicationInsightsTelemetry(aiOptions) para ASP.NET Core 6.0 o services.AddApplicationInsightsTelemetry(aiOptions) para ASP.NET Core 3.1 y versiones anteriores, se invalida la configuración de Microsoft.Extensions.Configuration.IConfiguration.

muestreo

El SDK de Application Insights SDK para ASP.NET Core admite el muestreo adaptable y el de tipo fijo. El muestreo adaptable está habilitado de forma predeterminada.

Para obtener más información, consulte Configuración del muestreo adaptable para aplicaciones ASP.NET Core.

Incorporación de TelemetryInitializers

Cuando quiera enriquecer la telemetría con más información, use inicializadores de telemetría.

Agregue cualquier nuevo objeto TelemetryInitializer al contenedor DependencyInjection tal como se muestra en el código siguiente. El SDK recoge automáticamente cualquier objeto TelemetryInitializer que se agregue al contenedor DependencyInjection.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Nota:

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funciona con inicializadores simples. Para otros, se necesita builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" });.

Eliminación de TelemetryInitializers

Los inicializadores de telemetría están presentes de forma predeterminada. Para quitar todos los inicializadores de telemetría o solo algunos específicos, use el siguiente código de ejemplo después de llamar a AddApplicationInsightsTelemetry().

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

Adición de procesadores de telemetría

Puede agregar procesadores de telemetría personalizados a TelemetryConfiguration mediante el método de extensión AddApplicationInsightsTelemetryProcessor en IServiceCollection. Los procesadores de telemetría se usan en escenarios de filtrado avanzado. Utilice el ejemplo siguiente:

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

Configuración o eliminación de valores de TelemetryModules predeterminado

Application Insights recopila automáticamente información de telemetría sobre cargas de trabajo específicas sin necesidad de seguimiento manual por parte del usuario.

Los siguientes módulos de recopilación automática están habilitados de forma predeterminada. Estos módulos son responsables de recopilar automáticamente datos de telemetría. Puede deshabilitarlos o configurarlos para modificar su comportamiento predeterminado.

• RequestTrackingTelemetryModule: recopila la información de RequestTelemetry de las solicitudes web entrantes.
• DependencyTrackingTelemetryModule: recopila información de DependencyTelemetry de llamadas HTTP salientes y llamadas SQL.
• PerformanceCollectorModule: recopila información de PerformanceCounters de Windows.
• QuickPulseTelemetryModule: Recopila datos de telemetría para mostrarlos en el panel de métricas activas.
• AppServicesHeartbeatTelemetryModule: recopila latidos (que se envían como métricas personalizadas) sobre el entorno de Azure App Service en el que se hospeda la aplicación.
• AzureInstanceMetadataTelemetryModule: recopila latidos (que se envían como métricas personalizadas) sobre el entorno de la máquina virtual de Azure en el que se hospeda la aplicación.
• EventCounterCollectionModule: recopila información de EventCounters. Este módulo es una característica nueva y está disponible tanto en la versión 2.8.0 del SDK como en las posteriores.

Para configurar cualquier objeto predeterminado TelemetryModule, use el método de la extensión ConfigureTelemetryModule<T> en IServiceCollection, como se muestra en el ejemplo siguiente:

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

En las versiones 2.12.2 y posteriores, ApplicationInsightsServiceOptions incluye una opción sencilla para deshabilitar cualquiera de los módulos predeterminados.

Configuración de un canal de telemetría

El Canal de telemetría predeterminado es ServerTelemetryChannel. El ejemplo siguiente muestra cómo reemplazarlo.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

Nota:

Si desea vaciar el búfer, consulte Vaciado de datos. Por ejemplo, es posible que necesite vaciar el búfer si usa el SDK en una aplicación que se apaga.

Deshabilitar la telemetría dinámicamente

Si desea deshabilitar la telemetría condicional y dinámicamente, puede resolver la instancia TelemetryConfiguration con el contenedor de inyección de dependencias de ASP.NET Core en cualquier parte del código y establecer DisableTelemetry como marca.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

El ejemplo de código anterior impide el envío de telemetría a Application Insights. No impide que los módulos de recopilación automática recopilen la telemetría. Si quiere quitar un módulo de recopilación automática concreto, consulte Eliminación del módulo de telemetría.

Preguntas más frecuentes

Esta sección proporciona respuestas a preguntas comunes.

¿Admite Application Insights ASP.NET Core 3.1?

ASP.NET Core 3.1 ya no es compatible con Microsoft.

El SDK de Application Insights para ASP.NET Core versión 2.8.0 y Visual Studio 2019 o posterior se pueden usar con aplicaciones de ASP.NET Core 3.1.

¿Cómo puedo realizar un seguimiento de la telemetría que se recopila automáticamente?

Obtenga una instancia de TelemetryClient mediante el uso de la inserción del constructor y llame al método TrackXXX() necesario que incluye. No se recomienda crear nuevas instancias TelemetryClient o TelemetryConfiguration en una aplicación de ASP.NET Core. Una instancia singleton de TelemetryClient ya está registrada en el contenedor DependencyInjection, que comparte TelemetryConfiguration con el resto de los datos de telemetría. Cree una instancia de TelemetryClient solo si necesita una configuración independiente del resto de la telemetría.

En el ejemplo siguiente se muestra cómo realizar el seguimiento de más datos de telemetría desde un controlador.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }
}

Para obtener más información acerca de los datos personalizados que reporta Application Insights, consulte API de Application Insights para eventos y métricas personalizados. Se puede usar un enfoque similar para el envío de métricas personalizadas a Application Insights mediante GetMetric API.

¿Cómo puedo capturar el cuerpo de la solicitud y la respuesta en mi telemetría?

ASP.NET Core tiene compatibilidad integrada para registrar información de solicitud y respuesta HTTP (incluido el cuerpo) mediante ILogger. Se recomienda aprovechar esto. Esto puede exponer información de identificación personal (PII) en telemetría y puede hacer que los costos (costos de rendimiento y facturación de Application Insights) aumenten significativamente, de modo que conviene evaluar detenidamente los riesgos antes de usarlo.

¿Cómo puedo personalizar la colección de registros de ILogger?

La configuración predeterminada de Application Insights es capturar solo advertencia y registros más graves.

Capture información y registros menos graves cambiando la configuración de registro para el proveedor de Application Insights como se indica a continuación.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information"
        },
        "ApplicationInsights": {
            "LogLevel": {
                "Default": "Information"
            }
        }
    },
    "ApplicationInsights": {
        "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
    }
}

Es importante tener en cuenta que el ejemplo siguiente no hará que el proveedor de Application Insights capture los registros Information. No lo captura porque el SDK agrega un filtro de registro predeterminado que indica a ApplicationInsights que capture solo los registros Warning y los registros más graves. Application Insights requiere una invalidación explícita.

{
    "Logging": {
        "LogLevel": {
            "Default": "Information"
        }
    }
}

Para más información, consulte Configuración de ILogger.

Algunas plantillas de Visual Studio usan el método de extensión UseApplicationInsights() en IWebHostBuilder para habilitar Application Insights. ¿Es este uso aún válido?

El método de extensión UseApplicationInsights() todavía es compatible, pero está marcado como obsoleto desde la versión 2.8.0 y posteriores del SDK de Application Insights. Se quita en el siguiente cambio de versión principal del SDK. Para habilitar la telemetría de Application Insights, use AddApplicationInsightsTelemetry(), ya que proporciona sobrecargas para controlar cierta configuración. Además, en las aplicaciones ASP.NET Core 3.X, services.AddApplicationInsightsTelemetry() es la única manera de habilitar Application Insights.

Estoy implementando mi aplicación de ASP.NET Core en Web Apps. ¿Debo habilitar la extensión de Application Insights desde Web Apps?

Si está instalado el SDK en tiempo de compilación, como se muestra en este artículo, no es necesario habilitar la extensión de Application Insights desde el portal de App Service. Si la extensión está instalada, se retirará cuando detecte que el SDK ya está agregado. Si habilita Application Insights desde la extensión, no tiene que instalar ni actualizar el SDK. Pero si habilita Application Insights siguiendo las instrucciones de este artículo, tendrá más flexibilidad porque:

• La telemetría de Application Insights seguirá funcionando en:
  • Todos los sistemas operativos, incluidos Windows, Linux y Mac.
  • Todos los modos de publicación, incluidos los independientes o dependientes del marco.
  • Todas las plataformas de destino, incluida la versión completa de .NET Framework.
  • Todas las opciones de hospedaje, incluidos contenedores, Web Apps, máquinas virtuales, Linux, AKS y hospedaje independiente de Azure.
  • Todas las versiones de .NET Core, incluidas las versiones preliminares.
• Puede ver datos de telemetría localmente cuando depure desde Visual Studio.
• Puede realizar un seguimiento de telemetría personalizada adicional mediante la API TrackXXX().
• Tiene control total sobre la configuración.

¿Puedo habilitar la supervisión de Application Insights mediante herramientas como el agente de Application Insights para Azure Monitor (anteriormente, Monitor de estado v2)?

Sí. En Application Insights Agent 2.0.0-beta1 y versiones posteriores, se admiten aplicaciones de ASP.NET Core hospedadas en IIS.

¿Se admiten todas las características si ejecuto mi aplicación en Linux?

Sí. La compatibilidad de características para el SDK es la misma en todas las plataformas, con las siguientes excepciones:

• El SDK recopila contadores de eventos en Linux, ya que los contadores de rendimiento solo se admiten en Windows. La mayoría de las métricas son las mismas.

¿Se admite este SDK para los servicios de trabajo?

No. En su lugar, use Application Insights para aplicaciones de Servicio de trabajo (aplicaciones que no son HTTP) para los servicios de trabajo.

¿Cómo puedo desinstalar el SDK?

Para quitar Application Insights, debe quitar los paquetes NuGet y las referencias de la API en la aplicación. Puede desinstalar paquetes NuGet mediante el Administrador de paquetes NuGet en Visual Studio.

Nota:

Estas instrucciones sirven para desinstalar el SDK de ASP.NET Core. Si necesita desinstalar el SDK de ASP.NET, consulte ¿Cómo puedo desinstalar el SDK de ASP.NET?.

1. Desinstale el paquete Microsoft.ApplicationInsights.AspNetCore utilizando el Administrador de paquetes NuGet.
2. Para quitar completamente Application Insights, compruebe y elimine manualmente el código o los archivos agregados junto con cualquier llamada API que haya agregado en el proyecto. Para obtener más información, consulte ¿Qué se crea al agregar el SDK de Application Insights?.

¿Qué se crea al agregar el SDK de Application Insights?

Cuando agrega Application Insights al proyecto, crea archivos y agrega código a algunos de sus archivos. La desinstalación exclusiva de paquetes NuGet no siempre descartará los archivos y el código. Para quitar completamente Application Insights, debe comprobar y eliminar manualmente el código o los archivos agregados junto con cualquier llamada API que haya agregado en el proyecto.

Al agregar Telemetría de Application Insights a un proyecto de plantilla de ASP.NET Core de Visual Studio, se agregan los siguientes archivos:

• [Nombre del proyecto].csproj

  <PropertyGroup>
      <TargetFramework>netcoreapp3.1</TargetFramework>
      <ApplicationInsightsResourceId>/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>
  
  <ItemGroup>
      <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>
  
  <ItemGroup>
      <WCFMetadata Include="Connected Services" />
  </ItemGroup>
  

• Appsettings.json

  "ApplicationInsights": {
      "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
  

• ConnectedService.json

  {
      "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
      "Version": "16.0.0.0",
      "GettingStartedDocument": {
          "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
      }
  }
  

• Startup.cs

  public void ConfigureServices(IServiceCollection services)
      {
          services.AddRazorPages();
          services.AddApplicationInsightsTelemetry(); // This is added
      }
  

¿Cómo puedo deshabilitar la correlación de telemetría?

Para deshabilitar la correlación de telemetría en el código, consulte <ExcludeComponentCorrelationHttpHeadersOnDomains> en Application Insights para aplicaciones de consola.

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.

SDK de código abierto

Lectura y contribución al código.

Para obtener las actualizaciones y correcciones de errores más recientes, vea las notas de la versión.

Notas de la versión

Para la versión 2.12 y versiones más recientes: SDK para .NET (incluidos los adaptadores de registro, ASP.NET Core y ASP.NET)

Nuestras Actualizaciones del servicio también resumen las principales mejoras de Application Insights.

Pasos siguientes

• Explore los flujos de usuarios para saber cómo de desplazan los usuarios por la aplicación.
• Configure una colección de instantáneas para ver el estado del código fuente y las variables en el momento en que se produzca una excepción.
• Use la API para enviar sus propios eventos y métricas para obtener una vista detallada del rendimiento y del uso de la aplicación.
• Las pruebas de disponibilidad comprueban la aplicación constantemente desde cualquier parte del mundo.
• Obtenga más información sobre la inserción de dependencias en ASP.NET Core.