Поставщики ведения журнала в NET

Статья
06/23/2023

Поставщики ведения журналов сохраняют журналы, за исключением поставщика Console, в котором журналы отображаются только в стандартном выводе. Например, поставщик Azure Application Insights хранит журналы в Azure Application Insights. Вы можете включить несколько поставщиков.

Шаблоны приложений .NET Worker по умолчанию:

используют универсальный узел;
Вызов CreateApplicationBuilder, который добавляет следующие поставщики ведения журнала:
- Консоль
- Debug
- EventSource
- EventLog (только для Windows)

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

В предыдущем коде показан класс Program, созданный с использованием шаблонов приложений .NET Worker. В следующих разделах приводятся примеры, которые построены на основе шаблонов приложений .NET Worker и используют универсальный узел.

Чтобы переопределить заданный по умолчанию набор поставщиков ведения журнала, добавленных с помощью Host.CreateApplicationBuilder, вызовите метод ClearProviders и добавьте необходимых поставщиков. Например, приведенный ниже код

вызывает метод ClearProviders для удаления всех экземпляров ILoggerProvider из построителя;
добавляет поставщик ведения журнала Console.

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

Сведения о других поставщиках см. в следующих статьях:

Встроенные поставщики ведения журнала.
Сторонние поставщики ведения журнала.

Настройка службы, зависящей от ILogger

Чтобы настроить службу, зависящую от ILogger<T>, используйте внедрение конструктора или предоставьте фабричный метод. Подход к методу фабрики рекомендуется только в том случае, если нет другого варианта. Например, рассмотрим службу, которой требуется экземпляр ILogger<T>, предоставляемый путем внедрения зависимостей:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExampleService>(
    container => new DefaultExampleService
    {
        Logger = container.GetRequiredService<ILogger<IExampleService>>()
    });

Предыдущий код — это Func<IServiceProvider, IExampleService> , который запускается при первом запуске контейнера DI, который должен создать экземпляр IExampleService. Таким образом можно обращаться к любым зарегистрированным службам.

Встроенные поставщики ведения журнала.

Расширения Майкрософт включают в себя следующих поставщиков ведения журналов в составе библиотек среды выполнения:

Консоль
Debug
EventSource
EventLog

Следующие поставщики ведения журналов поставляются корпорацией Майкрософт, но не в составе библиотек среды выполнения. Их необходимо устанавливать в виде дополнительных пакетов NuGet.

AzureAppServicesFile и AzureAppServicesBlob
ApplicationInsights

Консоль

Поставщик Console выводит выходные данные в консоль.

Отладка

Debug Поставщик записывает выходные данные журнала с помощью класса, в частности с помощью System.Diagnostics.Debug Debug.WriteLine метода и только при присоединении отладчика. DebugLoggerProvider создает экземпляры DebugLogger, которые являются реализациями интерфейса ILogger.

Источник событий

Поставщик EventSource выполняет запись в кроссплатформенный источник событий с именем Microsoft-Extensions-Logging. В Windows поставщик использует ETW.

Средства трассировки dotnet

Средство dotnet-trace — это универсальное кроссплатформенное средство командной строки, которое выполняет сбор трассировок .NET Core для запущенного процесса. Средство собирает данные поставщика Microsoft.Extensions.Logging.EventSource с помощью LoggingEventSource.

Инструкции по установке см. в статье dotnet-trace. Руководство по диагностике с использованием dotnet-trace см. в разделе Отладка высокой загрузки ЦП в .NET Core.

Windows EventLog

Поставщик EventLog отправляет выходные данные журнала в журнал событий Windows. В отличие от других поставщиков, поставщик EventLogне наследует параметры по умолчанию, не относящиеся к поставщику. Если параметры журнала EventLog не указаны, то принимается значение по умолчанию LogLevel.Warning.

Чтобы регистрировать события с уровнем ниже LogLevel.Warning, следует явно задать уровень ведения журнала. В следующем примере для журнала событий по умолчанию задается уровень LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Перегрузки AddEventLog позволяют передавать EventLogSettings. Если null или не указан, используются следующие параметры по умолчанию:

LogName: "Application"
SourceName: ".NET Runtime"
MachineName: используется имя локального компьютера.

Следующий код изменяет SourceName со значения по умолчанию ".NET Runtime" на CustomLogs:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(
    config => config.SourceName = "CustomLogs");

using IHost host = builder.Build();

host.Run();

Служба приложений Azure

Пакет поставщика Microsoft.Extensions.Logging.AzureAppServices записывает журналы в текстовые файлы в файловой системе приложения службы приложений Azure и в хранилище больших двоичных объектов в учетной записи хранения Azure.

Пакет поставщика не входит в библиотеки среды выполнения. Чтобы использовать поставщик, добавьте пакет поставщика в проект.

Для настройки параметров поставщика используйте AzureFileLoggerOptions и AzureBlobLoggerOptions, как показано в следующем примере:

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

При развертывании в службе приложений Azure ваше приложение использует параметры в разделе Журналы службы приложений на странице Служба приложений на портале Azure. При обновлении следующих параметров изменения вступают в силу немедленно без перезапуска или повторного развертывания приложения:

Расположение по умолчанию для файлов журналов находится в папке D:\home\LogFiles\Application . Дополнительные значения по умолчанию зависят от поставщика:

Ведение журнала приложений (файловая система): имя файла файловой системы по умолчанию — диагностика-yyyymmdd.txt. Максимальный размер файла по умолчанию составляет 10 МБ, а максимальное количество сохраняемых по умолчанию файлов равно 2.
Ведение журнала приложений (BLOB-объект): имя большого двоичного объекта по умолчанию — {app-name}/yyy/mm/dd/hh/{guid}_applicationLog.txt.

Этот поставщик работает только при выполнении проекта в среде Azure.

Потоковая передача журналов Azure

Потоковая передача журналов Azure позволяет просматривать активность журнала в реальном времени из следующих источников:

сервер приложений;
веб-сервер;
Трассировка неудачно завершенных запросов

Настройка потоковой передачи журналов Azure

Со страницы портала приложения перейдите на страницу Журналы службы приложений.
Установите для параметра Вход в приложения (файловая система) значение Вкл.
Выберите уровень ведения журнала. Этот параметр применяется только к потоковой передаче журналов Azure.

Перейдите на страницу Поток журналов, чтобы просмотреть журналы. Сообщения записываются в журнал с помощью интерфейса ILogger.

Azure Application Insights

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

Дополнительные сведения см. на следующих ресурсах:

Общие сведения об Application Insights
ApplicationInsightsLoggerProvider for .NET Core ILogger logs (Поставщик ведения журналов Application Insights для журналов .NET Core ILogger) — начните изучение с этой статьи, если вы хотите внедрить поставщика ведения журналов, не используя остальные возможности Application Insights для телеметрии.
Адаптеры ведения журналов в Application Insights.
Инструментирование серверного кода веб-приложения с помощью Application Insights — интерактивный учебник на сайте Microsoft Learn.

Сторонние поставщики ведения журналов

Ниже приведены некоторые сторонние платформы ведения журналов, которые работают с различными рабочими нагрузками .NET:

Некоторые сторонние платформы выполняют семантическое ведение журналов, также известное как структурированное ведение журналов.

Использование сторонней платформы аналогично использованию одного из встроенных поставщиков:

Добавьте пакет NuGet в проект.
Вызовите метод расширения ILoggerFactory или ILoggingBuilder, предоставляемый платформой ведения журналов.

Дополнительные сведения см. в документации по каждому поставщику. Сторонние поставщики ведения журналов не поддерживаются корпорацией Майкрософт.