Поставщики логирования в .NET

2023-06-23

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

Стандартные шаблоны рабочих приложений .NET:

используют универсальный узел;
Вызов CreateApplicationBuilder, который добавляет следующие поставщики ведения журнала:
- Консоль
- Отлаживать
- 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, использующих обобщенного узла.

Чтобы переопределить набор поставщиков ведения журналов, добавленных 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. Таким образом можно обращаться к любым зарегистрированным службам.

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

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

Консоль
Отлаживать
EventSource
EventLog

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

AzureAppServicesFile и AzureAppServicesBlob
ApplicationInsights

Консоль

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

Отладка

Поставщик Debug записывает данные журнала, используя класс System.Diagnostics.Debug, конкретно метод Debug.WriteLine, и только если отладчик присоединен. DebugLoggerProvider создает экземпляры класса логгера, который реализует интерфейс 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 отправляет выходные данные журнала в журнал событий Windows. В отличие от других поставщиков, поставщик EventLogне наследует параметры по умолчанию, не относящиеся к поставщику. Если параметры журнала EventLog не указаны, то принимается значение по умолчанию LogLevel.Warning.

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

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

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

LogName: "Приложение"
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 . Дополнительные значения по умолчанию зависят от поставщика:

Ведение журнала приложений (файловая система): имя файла файловой системы по умолчанию —diagnostics-yyyymmdd.txt. Максимальный размер файла по умолчанию составляет 10 МБ, а максимальное количество сохраняемых по умолчанию файлов равно 2.
Ведение журнала приложений (BLOB-объект): имя BLOB-объекта по умолчанию — {app-name}/yyyy/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 для журналов ILogger в .NET Core. Начните здесь, если вы хотите реализовать провайдер журналирования без остальной телеметрии Application Insights.
Адаптеры ведения журналов в Application Insights.
Установка, настройка и инициализация пакета SDK Application Insights — интерактивное руководство по сайту Microsoft Learn.

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

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

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

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

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

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