Application Insights registrando em log com .NET

  • Artigo

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

Observação

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

Observação

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

Dica

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

Aplicativos do ASP.NET Core

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

  1. Instale os Microsoft.Extensions.Logging.ApplicationInsights.

  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 o log. Com a injeção de construtor, exija uma ILogger ou a alternativa de tipo genérico ILogger<TCategoryName>, conforme necessário. Quando essas implementações forem resolvidas, o ApplicationInsightsLoggerProvider as fornecerá. As mensagens ou exceções registradas 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, confira Registrar em log no ASP.NET Core e Qual tipo de telemetria do Application Insights é produzido a partir de logs do ILogger? Onde posso ver os logs do ILogger no Application Insights?.

Aplicativo de console

Para adicionar o registro em 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 de 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, confira Qual tipo de telemetria do Application Insights é produzido a partir de logs do ILogger? Onde posso ver os logs do ILogger no Application Insights?.

Escopos de registro de log

ApplicationInsightsLoggingProvider usa 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") nas 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 frequentes

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

ApplicationInsightsLoggerProvider captura ILogger logs e cria TraceTelemetry com base neles. Se um Exception objeto for passado para oLog método em ILogger, ExceptionTelemetry é criado em vez deTraceTelemetry.

Exibindo a telemetria do ILogger

No portal do Azure:

  1. Abra o portal do Azure e acesse o seu recurso do Application Insights.
  2. Clique na seção "Logs" dentro do Application Insights.
  3. Use a KQL (Linguagem de Consulta Kusto) para consultar mensagens do ILogger, geralmente armazenadas na tabela traces.
    • Consulta de exemplo: traces | where message contains "YourSearchTerm".
  4. Refine suas consultas para filtrar dados ILogger por severidade, intervalo de tempo ou conteúdo de mensagem específico.

No Visual Studio (Depurador Local):

  1. Inicie seu aplicativo em 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 você preferir sempre enviar TraceTelemetry, use este trecho de código:

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

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

O Application Insights captura e envia ILoggerlogs usando a mesmaTelemetryConfiguration informação usada para todas as outras telemetrias. Mas há uma exceção. Por padrão, o TelemetryConfiguration não é totalmente configurado quando você faz o log de Program.cs ou de Startup.cs. Os logs desses locais não têm a configuração padrão, portanto, não estão executando todas as instâncias de TelemetryInitializer e TelemetryProcessor.

Estou usando o pacote autônomo Microsoft.Extensions.Logging.ApplicationInsights e quero registrar manualmente uma telemetria personalizada adicional. Como posso fazer isso?

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

Observação

Se você usar o pacote Microsoft.ApplicationInsights.AspNetCore para habilitar o Application Insights, modifique esse código para obter 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 do ASP.NET Core. Como usar o novo provedor?

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 o seu aplicativo.

Próximas etapas