Registro de Application Insights con .NET

  • Artículo

En este artículo obtendrá información sobre cómo capturar registros con Application Insights en aplicaciones de .NET usando el paquete de proveedor de Microsoft.Extensions.Logging.ApplicationInsights. Si usa este proveedor, puede consultar y analizar los registros mediante las herramientas de Application Insights.

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.

Nota:

Si desea implementar la gama completa de telemetría de Application Insights junto con el registro, consulte Configuración de Application Insights para los sitios web de ASP.NET o Application Insights para aplicaciones ASP.NET Core.

Sugerencia

Está fuera del ámbito el paquete Microsoft.ApplicationInsights.WorkerService de NuGet, que se usa para habilitar Application Insights para servicios en segundo plano. Para más información, consulte Application Insights para aplicaciones de Worker Service.

Aplicaciones de ASP.NET Core

Para agregar el registro de Application Insights a las aplicaciones ASP.NET Core:

  1. Instale los Microsoft.Extensions.Logging.ApplicationInsights.

  2. Agregue ApplicationInsightsLoggerProvider:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Con el paquete NuGet instalado y el proveedor registrado con la inserción de dependencias, la aplicación está lista para registrarse. Con la inserción de constructores, se necesita ILogger o la alternativa de tipo genérico ILogger<TCategoryName>. Cuando se resuelvan estas implementaciones, ApplicationInsightsLoggerProvider las proporcionará. Las excepciones o los mensajes registrados se enviarán a Application Insights.

Considere el siguiente controlador de ejemplo:

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

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

Para más información, consulte Registro en ASP.NET Core y ¿Qué tipo de telemetría de Application Insights se genera a partir de registros de ILogger? ¿Dónde puedo ver los registros de ILogger en Application Insights?.

Aplicación de consola

Para agregar el registro de Application Insights a las aplicaciones de la consola, primero instala los siguientes paquetes de NuGet:

En el ejemplo siguiente se usa el paquete Microsoft.Extensions.Logging.ApplicationInsights y se muestra el comportamiento predeterminado para una aplicación de consola. El paquete Microsoft.Extensions.Logging.ApplicationInsights debe usarse en una aplicación de consola o siempre que desee una implementación mínima de Application Insights sin el conjunto de características completo, como métricas, seguimiento distribuido, muestreo e inicializadores de telemetría.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Para más información, consulte ¿Qué tipo de telemetría de Application Insights se genera a partir de registros de ILogger? ¿Dónde puedo ver los registros de ILogger en Application Insights?

Ámbitos de registro

ApplicationInsightsLoggingProvider admite ámbitos de registro. Los ámbitos están habilitados de manera predeterminada.

Si el ámbito es de tipo IReadOnlyCollection<KeyValuePair<string,object>>, todos los pares clave-valor de la colección se agregan a los datos de telemetría de Application Insights como propiedades personalizadas. En el siguiente ejemplo, los registros se capturan como TraceTelemetry y tienen ("MyKey", "MyValue") en las propiedades.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Si se usa cualquier otro tipo como ámbito, se almacena en la propiedad Scope de los datos de telemetría de Application Insights. En el siguiente ejemplo, TraceTelemetry tiene una propiedad denominada Scope que contiene el ámbito.

    using (_logger.BeginScope("hello scope"))
    {
        _logger.LogError("An example of an Error level message");
    }

Preguntas más frecuentes

¿Qué tipo de datos de telemetría de Application Insights se generan a partir de los registros de ILogger? ¿Dónde puedo ver los registros de ILogger en Application Insights?

ApplicationInsightsLoggerProvider captura registros de ILogger y crea TraceTelemetry a partir de estos. Si se pasa un objeto Exception al método Log en ILogger, se crea ExceptionTelemetry en lugar de TraceTelemetry.

Visualización de la telemetría de ILogger

En Azure Portal:

  1. Vaya a Azure Portal y acceda al recurso de Application Insights.
  2. Haga clic en la sección "Registros" dentro de Application Insights.
  3. Use el lenguaje de consulta Kusto (KQL) para consultar mensajes de ILogger, normalmente almacenados en la tabla traces.
    • Ejemplo de consulta: traces | where message contains "YourSearchTerm".
  4. Refine las consultas para filtrar los datos de ILogger por gravedad, intervalo de tiempo o contenido de mensaje específico.

En Visual Studio (depurador local):

  1. Ejecute la aplicación en modo de depuración en Visual Studio.
  2. Abra la ventana "Herramientas de diagnóstico" mientras se ejecuta la aplicación.
  3. En la pestaña "Eventos", los registros de ILogger aparecen junto con otros datos de telemetría.
  4. Utilice las características de búsqueda y filtro en la ventana "Herramientas de diagnóstico" para buscar mensajes de ILogger específicos.

Si prefiere enviar TraceTelemetry siempre, use este fragmento de código:

builder.AddApplicationInsights(
    options => options.TrackExceptionsAsExceptionTelemetry = false);

¿Por qué algunos registros de ILogger no tiene las mismas propiedades que otros?

Application Insights captura y envía los registros de ILogger usando la misma información de TelemetryConfiguration que se usa para los demás datos de telemetría. Sin embargo, hay una excepción. De manera predeterminada, TelemetryConfiguration no se ha configurado por completo al registrarse desde Program.cs o Startup.cs. Los registros con estas procedencias no tienen la configuración predeterminada, por lo que no se ejecutan todas las instancias TelemetryInitializer y TelemetryProcessor.

Estoy usando el paquete independiente Microsoft.Extensions.Logging.ApplicationInsights y quiero registrar manualmente más datos de telemetría personalizados. ¿Cómo debo hacerlo?

Cuando se usa el paquete independiente, TelemetryClient no se inserta en el contenedor de inserción de dependencias (DI). Debe crear una instancia de TelemetryClient y usar la misma configuración que el proveedor del registrador, tal y como se muestra en el siguiente código. Este requisito garantiza que se use la misma configuración para todos los datos de telemetría personalizados y los datos de telemetría de ILogger.

public class MyController : ApiController
{
   // This TelemetryClient instance can be used to track additional telemetry through the TrackXXX() API.
   private readonly TelemetryClient _telemetryClient;
   private readonly ILogger _logger;

   public MyController(IOptions<TelemetryConfiguration> options, ILogger<MyController> logger)
   {
        _telemetryClient = new TelemetryClient(options.Value);
        _logger = logger;
   }  
}

Nota

Si utiliza el paquete Microsoft.ApplicationInsights.AspNetCore para habilitar Application Insights, modifique este código para obtener TelemetryClient directamente en el constructor.

No tengo instalado el SDK y uso la extensión Web Apps de Azure para habilitar Application Insights para mis aplicaciones de ASP.NET Core. ¿Cómo uso el nuevo proveedor?

La extensión de Application Insights en Azure Web Apps usa el nuevo proveedor. Puede modificar las reglas de filtrado en el archivo appsettings.json para la aplicación.

Pasos siguientes