Habilitar Azure Application Insights para aplicaciones de ASP.NET Core

En este artículo se describe cómo habilitar Application Insights para una aplicación de ASP.NET Core implementada como una aplicación web de Azure. Esta implementación usa un enfoque basado en SDK, también está disponible un enfoque de instrumentación automática.

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 de ASP.NET Core que tiene net6.0 como destino. Estas instrucciones se pueden aplicar a todas las aplicaciones de ASP.NET Core. Si usa el Servicio de trabajo, siga las instrucciones que encontrará aquí.

Nota

Hay disponible una oferta de .NET basada en OpenTelemetry en versión preliminar. Más informació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.

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 siempre y cuando .NET Core sea compatible. El soporte trata los escenarios siguientes:

  • 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: IIS (Internet Information Server) o Kestrel.
  • Plataforma de hospedaje: característica Web Apps de Azure App Service, VM de Azure, Docker, Azure Kubernetes Service (AKS), etc.
  • Versión de .NET Core: todas las versiones de .NET Core compatibles oficialmente que no están en versión preliminar.
  • IDE: Visual Studio, Visual Studio Code o la línea de comandos.

Requisitos previos

Si desea seguir las instrucciones de este artículo, se necesitan ciertos requisitos previos.

  • Visual Studio 2022
  • Cargas de trabajo de Visual Studio: desarrollo web y ASP.NET, almacenamiento y procesamiento de datos y desarrollo de Azure
  • .NET 6.0
  • Suscripción y cuenta de usuario de Azure (con la capacidad de crear y eliminar recursos)

Implementación de recursos de Azure

Siga las instrucciones para implementar la aplicación de ejemplo desde su repositorio de GitHub.

Para proporcionar nombres únicos globales a algunos recursos, se ha asignado un sufijo de 5 caracteres. Anote este sufijo para usarlo más adelante en este artículo.

La lista de recurso implementados de Azure se muestra con los sufijos de 5 caracteres marcados.

Creación de recursos en Application Insights

  1. En el Azure Portal, busque y seleccione el grupo de recursos application-insights-azure-café.

  2. En la barra de herramientas del menú superior, seleccione + Crear.

    El grupo de recursos application-insights-azure-cafe muestra el botón + Crear marcado en menú de la barra de herramientas.

  3. En la pantalla Crear un recurso, busque y seleccione Application Insights en el cuadro de texto de búsqueda de Marketplace.

    La pantalla de recursos Crear muestra los Application Insights que se han introducido en el cuadro de búsqueda y los resultados de la búsqueda marcados de Application Insights

  4. En la pantalla de información general del recurso de Application Insights, seleccione Crear.

    La pantalla de información general de Application Insights muestra el botón Crear marcado.

  5. En la pestaña Aspectos básicos de la pantalla de Application Insights. Complete el formulario como se indica a continuación y, a continuación, seleccione el botón Revisar + crear. Los campos no especificados en la tabla siguiente pueden conservar sus valores predeterminados.

    Campo Valor
    Nombre Escriba azure-cafe-application-insights-{SUFFIX}, reemplazando {SUFFIX} por el valor de sufijo adecuado registrado anteriormente.
    Region Seleccione la misma región elegida al implementar los recursos del artículo.
    Área de trabajo de Log Analytics Seleccione azure-cafe-log-analytics-workspace, como alternativa, se puede crear un área de trabajo de Log Analytics aquí.

    La pestaña Aspectos básicos de Application Insights muestra un formulario rellenado con los valores anteriores.

  6. Una vez superada la validación, seleccione Crear para implementar el recurso.

    La pantalla de validación de Application Insights muestra que se ha pasado con éxito la validación y el botón Create está marcado.

  7. Una vez completada la implementación, vuelva al grupo de recursos application-insights-azure-cafe y seleccione el recurso de Application Insights implementado.

    El grupo de recursos Azure Cafe se muestra con el recurso de Application Insights marcado.

  8. En la pantalla Información general del recurso de Application Insights, copie el valor de Cadena de conexión que se usará en la sección siguiente de este artículo.

    La pantalla de información general de Application Insights muestra el valor Cadena de conexión marcado y el botón Copiar seleccionado.

Configuración de la configuración de la aplicación de cadena de conexión de Application Insights en el App Service web

  1. Vuelva al grupo de recursos application-insights-azure-cafe, busque y abra el recurso azure-café-web-{SUFFIX} App Service.

    El grupo de recursos de Azure Cafe muestra el recurso azure-cafe-web-{SUFFIX} marcado.

  2. En el menú de la izquierda, debajo del encabezado Configuración, seleccione Configuración. Entonces, en la pestaña Configuración de la aplicación, seleccione + Nueva configuración de la aplicación, bajo el encabezado de la configuración de la aplicación.

    La pantalla de recursos de App Service se muestra con el elemento de configuración del menú de la izquierda seleccionado y el botón de la barra de herramientas del nuevo elemento de configuración marcado.

  3. En la hoja Agregar o editar configuración de la aplicación, complete el formulario como se indica a continuación y seleccione Aceptar.

    Campo Valor
    Nombre APPLICATIONINSIGHTS_CONNECTION_STRING
    Valor Pegue la cadena de conexión de Application Insights obtenida en la sección anterior.

    La configuración de la aplicación Añadir/Editar de la hoja muestra los valores anteriores poblados.

  4. En la pantalla configuración de App Service, seleccione el botón Guardar en el menú de la barra de herramientas. Cuando se le pida que guarde los cambios, seleccione Continuar.

    La pantalla de configuración de App Service se muestra con el botón Guardar marcado en el menú de la barra de herramientas.

Instale el paquete NuGet de Application Insights

Es necesario configurar la ASP.NET Core aplicación web MVC para enviar telemetría. Esto se logra con el paquete NuGet de aplicaciones web de Application Insights para ASP.NET Core.

  1. Con Visual Studio Code, abra 1 - Starter Application\src\AzureCafe.sln.

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

    El explorador de soluciones se muestra con la gestión de paquetes de NuGet seleccionados del menú contextual.

  3. Seleccione la pestaña Examinar, busque y seleccione Microsoft.ApplicationInsights.AspNetCore. Seleccione Instalar y acepte las términos de licencia. Se recomienda usar 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.

    La pestaña de NuGet se muestra con la pestaña Buscar seleccionada y Microsoft.ApplicationInsights.AspNetCore está introducida en el cuadro de búsqueda. El paquete Microsoft.ApplicationInsights.AspNetCore está seleccionado de entre una lista de resultados. El panel derecho, la última versión estable está seleccionada de entre un menú desplegable y el botón Instalar está marcado.

  4. Mantenga Visual Studio abierto para la sección siguiente del artículo.

Habilitación de la telemetría de Application Insights del lado servidor

Application Insights para ASP.NET Core paquete NuGet de aplicaciones web encapsula características para permitir el envío de telemetría del lado servidor al recurso de Application Insights en Azure.

  1. En el Explorador de soluciones de Visual Studio, busque y abra el archivo Program.cs.

    El explorador de soluciones de Visual Studio muestra Program.cs marcado.

  2. Inserte el código siguiente antes de la instrucción builder.Services.AddControllersWithViews(). Este código lee automáticamente el valor de la cadena de conexión de Application Insights de la configuración. El método AddApplicationInsightsTelemetry registra ApplicationInsightsLoggerProvider con el contenedor integrado de inserción de dependencias, que se usará para satisfacer las solicitudes de implementación de ILogger e ILogger<TCategoryName>.

    builder.Services.AddApplicationInsightsTelemetry();
    

    Una ventana de código muestra el fragmento de código anterior marcado.

    Sugerencia

    Obtenga más información sobre las opciones de configuración en ASP.NET Core.

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. Esta aplicación tiene componentes del lado cliente, siga estos pasos para comenzar a recopilar telemetría de uso.

  1. En el Explorador de soluciones de Visual Studio, busque y abra \Views\_ViewImports.cshtml. Agregue el siguiente código al final del archivo existente.

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    

    El archivo _ViewImports.cshtml se muestra con la línea de código anterior marcada.

  2. Para habilitar correctamente la supervisión del lado cliente para la aplicación, el fragmento de código de JavaScript debe aparecer en la sección <head> de cada página de la aplicación que quiere supervisar. En Visual Studio Explorador de soluciones, busque y abra \Views\Shared\_Layout.cshtml, inserte el código siguiente inmediatamente antes de la etiqueta de cierre <\head>.

    @Html.Raw(JavaScriptSnippet.FullScript)
    

    El archivo _Layout.cshtml se muestra con la línea de código anterior marcada en la sección del encabezado de la página.

    Sugerencia

    Como alternativa al uso de FullScript, está disponible ScriptBody. 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>
    

Nota

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

Habilitación de la supervisión de consultas de base de datos

Al investigar las causas de degradación del rendimiento, es importante incluir información sobre las llamadas de base de datos. Habilite la supervisión mediante la configuración del módulo de dependencia. La supervisión de dependencias, incluido SQL, está habilitada de forma predeterminada. Se pueden seguir los pasos siguientes para capturar el texto completo de la consulta SQL.

Nota:

El texto SQL puede contener datos confidenciales, como contraseñas y PII. Tenga cuidado al habilitar esta característica.

  1. En el Explorador de soluciones de Visual Studio, busque y abra el archivo Program.cs.

  2. Al principio del archivo, agregue la siguiente instrucción using.

    using Microsoft.ApplicationInsights.DependencyCollector;
    
  3. Inmediatamente después del código builder.Services.AddApplicationInsightsTelemetry(), inserte lo siguiente para habilitar la instrumentación de texto del comando SQL.

    builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
    

    Una ventana de código muestra de código anterior marcado.

Ejecución de la aplicación web de Azure Cafe

Una vez implementado el código de la aplicación web, la telemetría fluirá a Application Insights. El SDK de Application Insights recopila automáticamente las solicitudes web entrantes en la aplicación.

  1. Haga clic con el botón derecho en el proyecto AzureCafe en el Explorador de soluciones y seleccione Publicar en el menú contextual.

    El explorador de soluciones de Visual Studio se muestra con el proyecto Azure Cafe seleccionado y el elemento del menú Publicar contexto marcado

  2. Seleccione Publicar para promover el nuevo código a la Azure App Service.

    El perfil de publicación de AzureCafe se muestra con el botón Publicar marcado.

  3. Una vez que la publicación se haya realizado correctamente, se abre una nueva ventana del explorador en la aplicación web de Azure Cafe.

    Se muestra la aplicación web de Azure Cafe.

  4. Realice varias actividades en la aplicación web para generar algunos datos de telemetría.

    1. Seleccione Detalles junto a Café para ver su menú y opiniones.

      Una parte de la lista de Azure se muestra con el botón Detalles marcado.

    2. En la pantalla Café, seleccione la pestaña Opiniones para ver y agregar revisiones. Seleccione el botón Agregar revisión para agregar una revisión.

      La pantalla de detalles de Café se muestra con el botón Agregar revisión marcado.

    3. En el cuadro de diálogo Crear una revisión, escriba un nombre, una clasificación, comentarios y cargue una foto para la revisión. Cuando termine, seleccione Agregar revisión.

      Se muestra el diálogo Crear una revisión.

    4. Repita la adición de revisiones según sea necesario para generar telemetría adicional.

Métricas activas

Live Metrics se puede usar para comprobar rápidamente si la supervisión de Application Insights está configurada correctamente. La telemetría puede tardar unos minutos en aparecer en el portal y el análisis, pero Live Metrics muestra el uso de la 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.

Mapa de aplicación

La aplicación de ejemplo realiza llamadas a varios recursos de Azure, incluidos Azure SQL, Azure Blob Storage y Azure Language Service (para revisar el análisis de sentimiento).

Se muestra la arquitectura de la aplicación de ejemplo de Azure Cafe.

Application Insights introspecciona los datos de telemetría entrantes y puede generar un mapa visual de las integraciones del sistema detectadas.

  1. Acceda al Azure Portal e inicie sesión.

  2. Abra el grupo de recursos application-insights-azure-cafe de aplicación de ejemplo.

  3. En la lista de recursos, seleccione el recurso azure-cafe-insights-{SUFFIX} de Application Insights.

  4. Seleccione Mapa de aplicación en el menú de la izquierda, debajo del encabezado Investigar. Observe el mapa de aplicación generado.

    Se muestra el mapa de aplicación de Application Insights.

Visualización de llamadas HTTP y texto del comando SQL de base de datos

  1. Abra el recurso de Application Insights en Azure Portal.

  2. Debajo del encabezado Investigar en el menú de la izquierda, seleccione Rendimiento.

  3. La pestaña Operaciones contiene detalles de las llamadas HTTP recibidas por la aplicación. También puede alternar entre las vistas servidor y explorador (lado cliente) de los datos.

    La pantalla de rendimiento de Application Insights se muestra con la alternancia entre Servidor y Navegador marcados entre la lista de llamadas HTTP recibidas por la aplicación.

  4. Seleccione una operación en la tabla y elija explorar en profundidad una muestra de la solicitud.

    La pantalla de rendimiento se muestra con la operación POST seleccionada, el botón Aumento de detalles de los ejemplos está marcado y está seleccionado un ejemplo de la lista de sugeridos.

  5. La transacción de un extremo a otro se muestra para la solicitud seleccionada. En este caso, se creó una revisión, incluida una imagen, por lo que incluye llamadas a Azure Storage, el servicio de lenguaje (para el análisis de sentimiento), así como las llamadas de base de datos a SQL Azure para conservar la revisión. En este ejemplo, el primer evento seleccionado muestra información relativa a la llamada HTTP POST.

    La transacción de un extremo a otro se muestra con la llamada de publicación HTTP seleccionada.

  6. Seleccione un elemento SQL para revisar el texto del comando SQL emitido en la base de datos.

    La transacción de un extremo a otro se muestra con detalles de comandos de SQL.

  7. Opcionalmente, seleccione Solicitudes de dependencia (salientes) a Azure Storage o al servicio de lenguaje.

  8. Vuelva a la pantalla Rendimiento y seleccione la pestaña Dependencias para investigar las llamadas a recursos externos. Observe que la tabla Operations incluye llamadas a Análisis de sentimiento, Blob Storage y Azure SQL.

    La pantalla de rendimiento se muestra con la pestaña Dependencias seleccionada y la tabla de operaciones marcada.

Registro de aplicaciones con Application Insights

Información general acerca del registro

Application Insights es un tipo de proveedor de registro disponible para las aplicaciones de ASP.NET Core que están disponibles para las aplicaciones cuando el paquete NuGet de application Insights para ASP.NET Core está instalado y la recopilación de telemetría del lado servidor habilitada. Como recordatorio, el código siguiente de Program.cs registra con ApplicationInsightsLoggerProvider el contenedor integrado de inserción de dependencias.

builder.Services.AddApplicationInsightsTelemetry();

Con el ApplicationInsightsLoggerProvider registrado como proveedor de registro, la aplicación está lista para iniciar sesión en Application Insights mediante la inserción de constructores con ILogger o la alternativa ILogger<TCategoryName> de tipo genérico.

Nota:

Con las opciones de configuración predeterminadas, el proveedor de registro está configurado para capturar automáticamente eventos de registro con una gravedad de LogLevel.Warning o mayor.

Considere el siguiente controlador de ejemplo que muestra la inserción de ILogger que se resuelve con el ApplicationInsightsLoggerProvider que está registrado con el contenedor de inserción de dependencias. Observe en el método Get que se registra un mensaje informativo, de advertencia y de error.

Nota:

De forma predeterminada, no se registrará el seguimiento de nivel de información. Solo se capturan los niveles Warning y posteriores.

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInfo("An example of an Info trace..")
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Consulte el artículo sobre el registro de ASP.NET Core para más información.

Visualización de registros en Application Insights

ValuesController anterior se implementa con la aplicación de ejemplo y se encuentra en la carpeta Controllers del proyecto.

  1. Con un explorador de Internet, abra la aplicación de ejemplo. En la barra de direcciones, anexe /api/Values y pulse Enter.

    Se muestra una ventana de explorador web con valores /api/ anexados en la URL en la barra de dirección.

  2. Espere unos instantes y vuelva al recurso de Application Insights en el Azure Portal.

    Un grupo de recursos se muestra con el recurso de Application Insights marcado.

  3. En el menú izquierdo del recurso de Application Insights, seleccione Registros debajo de la sección Supervisión. En el panel Tablas, haga doble clic en la tabla de seguimientos, que se encuentra en el árbol de Application Insights. Modifique la consulta para recuperar seguimientos para el controlador Values como se indica a continuación y, a continuación, seleccione Ejecutar para filtrar los resultados.

    traces 
    | where operation_Name == "GET Values/Get"
    
  4. Observe los resultados que muestran los mensajes de registro presentes en el controlador. Una gravedad de registro de 2 indica un nivel de advertencia y una gravedad de registro de 3 indica un nivel de error.

  5. Como alternativa, la consulta también se puede escribir para recuperar los resultados en función de la categoría del registro. De forma predeterminada, la categoría es el nombre completo de la clase donde se inserta el ILogger, en este caso ValuesController (si había un espacio de nombres asociado a la clase, el nombre se prefijo con el espacio de nombres). Vuelva a escribir y ejecute la siguiente consulta para recuperar los resultados en función de la categoría.

    traces 
    | where customDimensions.CategoryName == "ValuesController"
    

Control del nivel de registros enviados a Application Insights

Las implementaciones de ILogger tienen un mecanismo integrado para aplicar el filtrado de registros. Este filtrado permite controlar los registros que se envían a cada proveedor registrado, incluido el proveedor de Application Insights. El filtrado se puede usar en la configuración (mediante un archivo appsettings.json) o en el código. Para obtener más información sobre los niveles de registro y las instrucciones sobre el uso adecuado, consulte la documentación del nivel de registro.

En los ejemplos siguientes se muestra cómo aplicar reglas de filtro a ApplicationInsightsLoggerProvider para controlar el nivel de registros enviados a Application Insights.

Creación de reglas de filtro con la configuración

ApplicationInsightsLoggerProvider se aplica alias como ApplicationInsights en la configuración. En la sección siguiente de un archivo appsettings.json se establece el nivel de registro predeterminado para todos los proveedores en LogLevel.Warning. La configuración del proveedor ApplicationInsights específicamente para las categorías que comienzan por "ValuesController" invalidan este valor predeterminado con LogLevel.Error y versiones posteriores.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

La implementación de la aplicación de ejemplo con el código anterior en appsettings.json producirá solo el seguimiento de errores que se envía a Application Insights al interactuar con ValuesController. Esto se debe a que LogLevel de la categoría ValuesController está establecido en Error, por lo que se suprime el seguimiento de advertencia.

Desactivar el registro en Application Insights

Para deshabilitar el registro mediante la configuración, establezca todos los valores de LogLevel en "None".

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

Del mismo modo, en el código, establezca el nivel predeterminado para ApplicationInsightsLoggerProvider y los niveles de registro posteriores en Ninguno.

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

SDK de código abierto

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

Pasos siguientes