Поделиться через

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

  • Статья

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

Примечание.

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

Примечание.

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

Совет

Пакет NuGet Microsoft.ApplicationInsights.WorkerService, используемый для включения Application Insights для фоновых служб, не рассматривается. Дополнительные сведения см. в разделе 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.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, вместо TraceTelemetry создается ExceptionTelemetry.

Просмотр телеметрии 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;
   }  
}

Примечание.

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

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

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

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