Ведение журнала Application Insights в .NET

  • Статья

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

Примечание.

В следующей документации используется классический API приложения Аналитика. Долгосрочный план приложения Аналитика заключается в сборе данных с помощью OpenTelemetry. Дополнительные сведения см. в разделе "Включить Azure Monitor OpenTelemetry" для приложений .NET, Node.js, Python и Java.

Примечание.

Если вы хотите реализовать полный спектр данных телеметрии приложений Аналитика вместе с ведением журнала, см. статью "Настройка Аналитика приложения" для веб-сайтов ASP.NET или приложений Аналитика для приложений ASP.NET Core.

Совет

Пакет NuGet Microsoft.ApplicationInsights.WorkerService, используемый для включения Application Insights для фоновых служб, не рассматривается. Дополнительные сведения см. в разделе Application Insights для приложений службы рабочих ролей.

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

Чтобы добавить ведение журнала приложений Аналитика в приложения 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 этих реализаций предоставляет их. Зарегистрированные сообщения или исключения отправляются в приложение Аналитика.

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

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" и "Что такое тип телеметрии приложения Аналитика производится из журналов ILogger? Где можно просмотреть журналы ILogger в application Аналитика?.

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

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

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

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

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

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

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 Аналитика телеметрии. В следующем примере имеется свойство, 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, вместо TraceTelemetry создается ExceptionTelemetry.

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

На портале Azure.

  1. Перейдите на портал Azure и получите доступ к ресурсу приложения Аналитика.
  2. Щелкните раздел "Журналы" в приложении Аналитика.
  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;
   }  
}

Примечание.

Если вы используете пакет TelemetryClient для включения Application Insights, измените этот код, чтобы получать Microsoft.ApplicationInsights.AspNetCore непосредственно в конструкторе.

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

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

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