Registro em log do Application Insights com .NET

  • Artigo

Neste artigo, você aprenderá a capturar logs com o Application Insights em aplicativos .NET usando o pacote do Microsoft.Extensions.Logging.ApplicationInsights provedor. Se você usar esse provedor, poderá consultar e analisar seus logs usando as ferramentas do Application Insights.

Nota

A documentação a seguir depende da API clássica do Application Insights. O plano de longo prazo para o Application Insights é coletar dados usando OpenTelemetry. Para obter mais informações, consulte Habilitar o Azure Monitor OpenTelemetry para aplicativos .NET, Node.js, Python e Java.

Nota

Se você quiser implementar a gama completa de telemetria do Application Insights junto com o registro em log, consulte Configurar o Application Insights para seus sites ASP.NET ou Application Insights para aplicativos ASP.NET Core.

Gorjeta

O Microsoft.ApplicationInsights.WorkerService pacote NuGet, usado para habilitar o Application Insights para serviços em segundo plano, está fora do escopo. Para obter mais informações, consulte Application Insights for Worker Service apps.

ASP.NET Aplicações principais

Para adicionar o log do Application Insights aos aplicativos ASP.NET Core:

  1. Instale o Microsoft.Extensions.Logging.ApplicationInsightsarquivo .

  2. Adicionar 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();

Com o pacote NuGet instalado e o provedor sendo registrado com injeção de dependência, o aplicativo está pronto para registrar. Com a injeção do construtor, uma ou ILogger a alternativa ILogger<TCategoryName> do tipo genérico é necessária. Quando essas implementações são resolvidas, ApplicationInsightsLoggerProvider fornece-as. Mensagens registradas ou exceções são enviadas para o Application Insights.

Considere o seguinte exemplo de controlador:

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 obter mais informações, consulte Fazendo login no ASP.NET Core e Qual tipo de telemetria do Application Insights é produzido a partir de logs ILogger? Onde posso ver os logs do ILogger no Application Insights?.

Aplicação de consola

Para adicionar o log do Application Insights aos aplicativos de console, primeiro instale os seguintes pacotes NuGet:

O exemplo a seguir usa o pacote Microsoft.Extensions.Logging.ApplicationInsights e demonstra o comportamento padrão para um aplicativo de console. O pacote Microsoft.Extensions.Logging.ApplicationInsights deve ser usado em um aplicativo de console ou sempre que você quiser uma implementação mínima do Application Insights sem o conjunto completo de recursos, como métricas, rastreamento distribuído, amostragem e inicializadores de telemetria.

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 obter mais informações, consulte Qual tipo de telemetria do Application Insights é produzido a partir de logs ILogger? Onde posso ver os logs do ILogger no Application Insights?.

Escopos de registro em log

ApplicationInsightsLoggingProvider Suporta escopos de log. Os escopos são habilitados por padrão.

Se o escopo for do tipo IReadOnlyCollection<KeyValuePair<string,object>>, cada par chave/valor na coleção será adicionado à telemetria do Application Insights como propriedades personalizadas. No exemplo a seguir, os logs são capturados como TraceTelemetry e tem ("MyKey", "MyValue") em propriedades.

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

Se qualquer outro tipo for usado como escopo, ele será armazenado sob a propriedade Scope na telemetria do Application Insights. No exemplo a seguir, TraceTelemetry tem uma propriedade chamada Scope que contém o escopo.

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

Perguntas mais frequentes

Que tipo de telemetria do Application Insights é produzido a partir de logs ILogger? Onde posso ver os logs do ILogger no Application Insights?

ApplicationInsightsLoggerProvider captura ILogger logs e cria TraceTelemetry a partir deles. Se um Exception objeto for passado para o Log método em , ExceptionTelemetry será criado em ILoggervez de TraceTelemetry.

Visualizando a Telemetria ILogger

No Portal do Azure:

  1. Vá para o Portal do Azure e acesse seu recurso do Application Insights.
  2. Clique na seção "Logs" dentro do Application Insights.
  3. Use Kusto Query Language (KQL) para consultar mensagens ILogger, geralmente armazenadas na traces tabela.
    • Exemplo de consulta: traces | where message contains "YourSearchTerm".
  4. Refine suas consultas para filtrar dados ILogger por gravidade, intervalo de tempo ou conteúdo específico da mensagem.

No Visual Studio (Depurador Local):

  1. Inicie seu aplicativo no modo de depuração no Visual Studio.
  2. Abra a janela "Ferramentas de diagnóstico" enquanto o aplicativo é executado.
  3. Na guia "Eventos", os logs do ILogger aparecem junto com outros dados de telemetria.
  4. Utilize os recursos de pesquisa e filtro na janela "Ferramentas de diagnóstico" para localizar mensagens específicas do ILogger.

Se preferir enviar TraceTelemetrysempre, use este trecho:

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

Por que alguns logs ILogger não têm as mesmas propriedades que outros?

O Application Insights captura e envia ILogger logs usando as mesmas TelemetryConfiguration informações usadas para todas as outras telemetrias. Mas há uma exceção. Por predefinição, TelemetryConfiguration não está totalmente configurado quando inicia sessão a partir de Programa.cs ou Arranque.cs. Os logs desses locais não têm a configuração padrão, portanto, não estão executando todas as TelemetryInitializer instâncias e TelemetryProcessor instâncias.

Estou usando o pacote autônomo Microsoft.Extensions.Logging.ApplicationInsights e quero registrar mais telemetria personalizada manualmente. Como devo fazê-lo?

Quando você usa o pacote autônomo, TelemetryClient não é injetado no contêiner de injeção de dependência (DI). Você precisa criar uma nova instância e usar a mesma configuração que o provedor de TelemetryClient logger usa, como mostra o código a seguir. Esse requisito garante que a mesma configuração seja usada para todas as telemetrias e telemetrias personalizadas do 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

Se você usar o pacote para habilitar o Microsoft.ApplicationInsights.AspNetCore Application Insights, modifique esse código para entrar TelemetryClient diretamente no construtor.

Não tenho o SDK instalado e uso a extensão de Aplicativos Web do Azure para habilitar o Application Insights para meus aplicativos ASP.NET Core. Como posso utilizar o novo fornecedor?

A extensão do Application Insights nos Aplicativos Web do Azure usa o novo provedor. Você pode modificar as regras de filtragem no arquivo appsettings.json para seu aplicativo.

Próximos passos