Логирование с помощью Application Insights в .NET

Из этой статьи вы узнаете, как собирать логи в приложениях .NET, используя Application Insights и пакет поставщика Microsoft.Extensions.Logging.ApplicationInsights. Используя этого поставщика, вы сможете выполнять запросы к журналам и их анализ с помощью средств Application Insights.

Приложения ASP.NET Core

Чтобы добавить логирование через Application Insights в приложения ASP.NET Core:

1. Установите Microsoft.Extensions.Logging.ApplicationInsights.

2. Добавить 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();

После установки пакета NuGet и регистрации поставщика с помощью внедрения зависимостей приложение готово к ведению логов. При использовании внедрения через конструктор требуется либо ILogger, либо альтернатива универсального типа ILogger<TCategoryName>. Когда эти реализации будут решены, ApplicationInsightsLoggerProvider предоставит их. Зарегистрированные сообщения или исключения отправляются в Application Insights.

Рассмотрим следующий пример контроллера.

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" };
    }
}

Дополнительные сведения см. в разделе "Ведение журнала" в ASP.NET Core и тип телеметрии Application Insights, создаваемый из журналов ILogger? Где можно увидеть журналы ILogger в Application Insights?.

Консольное приложение

Чтобы добавить ведение журнала Application Insights в консольные приложения, сначала установите следующие пакеты NuGet:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

В следующем примере используется пакет Microsoft.Extensions.Logging.ApplicationInsights и демонстрируется поведение по умолчанию для консольного приложения. Пакет Microsoft.Extensions.Logging.ApplicationInsights следует использовать в консольном приложении или всякий раз, когда требуется минимальная реализация Application Insights без полного набора функций, таких как метрики, распределенные трассировки, выборки и инициализаторы телеметрии.

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

Для получения дополнительной информации см. Какой тип телеметрии Application Insights создается из журналов ILogger? Где можно посмотреть журналы ILogger в Application Insights?.

Области ведения журнала

ApplicationInsightsLoggingProvider поддерживает области журналов. Область включены по умолчанию.

Если тип области — IReadOnlyCollection<KeyValuePair<string,object>>, каждая пара "ключ — значение" в коллекции добавляется в данные телеметрии Application Insights в качестве пользовательских свойств. В следующем примере журналы записываются как TraceTelemetry и имеются ("MyKey", "MyValue") в свойствах.

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

Если в качестве области используется любой другой тип, он сохраняется в свойстве Scope телеметрии Application Insights. В следующем примере TraceTelemetry имеет свойство Scope, которое содержит область.

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

Часто задаваемые вопросы

Какой тип телеметрии Application Insights создается из журналов ILogger? Где можно просмотреть журналы ILogger в Application Insights?

ApplicationInsightsLoggerProvider ведет журналы ILogger и создает на их основе TraceTelemetry. Если объект Exception передается в метод Log в ILogger, вместо ExceptionTelemetry создается TraceTelemetry.

Просмотр телеметрии ILogger

На портале Azure выполните следующие действия:

1. Перейдите к портал Azure и получите доступ к ресурсу Application Insights.
2. Выберите раздел "Журналы" в Application Insights.
3. Используйте язык запросов Kusto (KQL) для запроса сообщений ILogger, хранящихся в traces таблице. Пример запроса: traces | where message contains "YourSearchTerm".
4. Уточняйте запросы, чтобы фильтровать данные ILogger по серьезности, диапазону времени или определенному содержимому сообщения.

В Visual Studio (локальный отладчик):

1. Запустите приложение в режиме отладки в Visual Studio.
2. Откройте окно средств диагностики во время запуска приложения.
3. На вкладке "События " журналы ILogger отображаются вместе с другими данными телеметрии.
4. Чтобы найти определенные сообщения ILogger, используйте функции поиска и фильтрации в окне средств диагностики.

Если вы предпочитаете всегда отправлять TraceTelemetry, используйте следующий фрагмент кода.

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

Почему некоторые журналы ILogger не имеют тех же свойств, что и другие?

Application Insights записывает и отправляет журналы ILogger, используя ту же информацию TelemetryConfiguration, которая применяется для всех остальных данных телеметрии. Но есть исключение. По умолчанию TelemetryConfiguration не полностью настраивается при регистрации из Program.cs или Startup.cs. Журналы из этих источников не имеют конфигурации по умолчанию, поэтому они не выполняют все TelemetryInitializer и TelemetryProcessor экземпляры.

Я использую изолированный пакет Microsoft.Extensions.Logging.ApplicationInsights и хочу записывать дополнительные пользовательские данные телеметрии вручную. Как это сделать?

При использовании автономного пакета TelemetryClient не инъецируется в контейнер инъекции зависимостей. Необходимо создать новый экземпляр TelemetryClient и использовать ту же конфигурацию, которую использует поставщик средства ведения журнала, как показано в следующем коде. Это требование гарантирует, что одна и та же конфигурация будет использоваться как для всех пользовательских данных телеметрии, так и для телеметрии из 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;
   }  
}

Я не установил (-а) пакет SDK и использую расширение для веб-приложений Azure, чтобы включить Application Insights для моих приложений ASP.NET Core. Как мне использовать нового поставщика?

Расширение Application Insights в веб-приложениях Azure использует новый поставщик. Правила фильтрации для вашего приложения можно изменить в файле appsettings.json.

Следующие шаги

• Ведение журнала в .NET
• Вход в ASP.NET Core
• Просмотр журналов трассировки .NET в Application Insights