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 el SDK. También hay 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

Para una aplicación de ejemplo, usaremos una aplicación MVC de ASP.NET Core destinada a net6.0. Sin embargo, 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. 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 con Azure, Application Insights puede recopilar datos de telemetría de ella. La supervisión de Application Insights se admite siempre y cuando .NET Core sea compatible. Se admiten 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: Internet Information Server (IIS) 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

Para completar este tutorial, necesita:

• Visual Studio 2022
• Las siguientes cargas de trabajo de Visual Studio:
  • ASP.NET y desarrollo web
  • Almacenamiento y procesamiento de datos
  • 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 los recursos, se asigna un sufijo de seis caracteres a algunos recursos. Anote este sufijo para usarlo más adelante en este artículo.

Creación de recursos en Application Insights

1. En Azure Portal, seleccione el grupo de recursos application-insights-azure-cafe.

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

   

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

   

   Captura de pantalla de Crear un recurso de Azure Portal. En la captura de pantalla se muestra una búsqueda de Application Insights resaltada y Application Insights que aparece en los resultados de la búsqueda, que también está resaltada.

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

   

5. En la pantalla Application Insights, en la pestaña Aspectos básicos, complete el formulario mediante la tabla siguiente y, a continuación, seleccione el botón Revisar y 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, puede crear un área de trabajo de Log Analytics.

   

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

   

7. Una vez implementado el recurso, vuelva al grupo de recursos application-insights-azure-cafe y seleccione el recurso de Application Insights que implementó.

   

8. En la pantalla Información general del recurso de Application Insights, seleccione el botón Copiar en el Portapapeles para copiar el valor de la cadena de conexión. Usará el valor de cadena de conexión en la sección siguiente de este artículo.

   

   Captura de pantalla de Información general de Application Insights en Azure Portal. En la captura de pantalla se muestra el valor de la cadena de conexión resaltado y el botón Copiar en el Portapapeles seleccionado y resaltado.

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 y abra el recurso azure-cafe-web-{SUFFIX} de App Service.

   

2. En el menú de la izquierda, en la sección 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.

   

   Captura de pantalla del recurso App Service de Azure Portal. La captura de pantalla muestra la opción Configuración en el menú izquierdo de la sección Configuración seleccionada y resaltada, la pestaña Configuración de la aplicación seleccionada y resaltada, y el botón de la barra de herramientas + Nueva configuración de la aplicación resaltado.

3. En el panel Agregar o editar la 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 el valor de la cadena de conexión de Application Insights copiada en la sección anterior.

   

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.

   

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. Abra 1 - Starter Application\src\AzureCafe.sln en Visual Studio.

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

   

3. Seleccione la pestaña Examinar y luego 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.

   

   Captura de pantalla que muestra la interfaz de usuario del Administrador de paquetes NuGet en Visual Studio con la pestaña Examinar seleccionada. Microsoft.ApplicationInsights.AspNetCore se escribe en el cuadro de búsqueda y el paquete Microsoft.ApplicationInsights.AspNetCore está seleccionado en una lista de resultados. En el panel derecho, la versión estable más reciente del paquete Microsoft.ApplicationInsights.AspNetCore está seleccionada en una lista desplegable y el botón Instalar está resaltado.

   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, abra el archivo Program.cs.

   

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();
   

   

   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. La aplicación de ejemplo tiene componentes del lado cliente. Siga los siguientes pasos para empezar a recopilar la telemetría de uso.

1. En el Explorador de soluciones de Visual Studio, abra \Views\_ViewImports.cshtml.

2. Agregue el siguiente código al final del archivo existente.

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

   

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

   @Html.Raw(JavaScriptSnippet.FullScript)
   

   

   Sugerencia

   Una alternativa al uso de FullScript es 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. Para habilitar la supervisión, configure el módulo de dependencias. La supervisión de dependencias, incluido SQL, está habilitada de forma predeterminada.

Siga estos pasos 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, abra el archivo Program.cs.

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

   using Microsoft.ApplicationInsights.DependencyCollector;
   

3. Para activar la instrumentación de texto de comandos SQL, inserte el siguiente código inmediatamente después del código builder.Services.AddApplicationInsightsTelemetry().

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

   

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. En el Explorador de soluciones de Visual Studio, haga clic con el botón derecho en el proyecto AzureCafe y seleccione Publicar en el menú contextual.

   

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

   

   Cuando la aplicación web de Azure Cafe se publica correctamente, se abre una nueva ventana del explorador en la aplicación web de Azure Cafe.

   

3. Para generar algunos datos de telemetría, siga estos pasos en la aplicación web para agregar una revisión.

   1. Para ver el menú y las opiniones de una cafetería, seleccione Detalles junto a una cafetería.

      

   2. Para ver y agregar opiniones, en la pantalla Café, seleccione la pestaña Reseñas. Seleccione el botón Agregar reseña para agregar una reseña.

      

   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 reseña.

      

   4. Si necesita generar telemetría adicional, agregue revisiones adicionales.

Métricas activas

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

Visualización del 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).

Application Insights hace una introspección de los datos de telemetría entrantes y es capaz de generar un mapa visual de las integraciones del sistema que detecta.

1. Inicie sesión en Azure Portal.

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

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

4. En el menú de la izquierda, bajo el encabezado Investigar, seleccione Mapa de aplicación. Observe el mapa de aplicación generado.

   

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. Para alternar entre las vistas de servidor y explorador (lado cliente) de los datos, use el botón de alternancia Servidor/Explorador.

   

   Captura de pantalla de Rendimiento de Application Insights en Azure Portal. En la captura de pantalla se muestra el botón de alternancia Servidor/Explorador y las llamadas HTTP recibidas por la aplicación resaltadas.

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

   

   Captura de pantalla de Rendimiento de Application Insights en Azure Portal. En la captura de pantalla se muestra una operación POST y una operación de ejemplo de la lista sugerida seleccionada y resaltada, y el botón Explorar ejemplos resaltado.

   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). También incluye 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.

   

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

   

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

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

   

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á 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 está 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 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

De manera predeterminada, 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. 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.LogInformation("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.

   

2. En Azure Portal, espere unos instantes y, a continuación, seleccione el recurso azure-cafe-insights-{SUFFIX} de Application Insights.

   

3. En el menú de la izquierda del recurso Application Insights, en la sección Supervisión, seleccione Registros.

4. En el panel Tablas, en el árbol Application Insights, haga doble clic en la tabla Seguimientos.

5. 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"
   

   Los resultados 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.

6. Como alternativa, también puede escribir la consulta 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 ILogger. En este caso, el nombre de la categoría es ValuesController (si hay un espacio de nombres asociado a la clase, el nombre llevará el prefijo del 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 su 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 tanto, 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 "Ninguno".

{
  //... 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

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

Pasos siguientes

• Explore los flujos de usuarios para saber cómo navegan 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.
• Información general de disponibilidad
• Inserción de dependencias en ASP.NET Core
• Registro en ASP.NET Core
• Registros de seguimiento de .NET en Application Insights
• Instrumentación automática para Application Insights