Провайдеры ведения журнала в ASP.NET Core

Далеко не всегда нам необходимо, чтобы приложение отправляло логи своей работы в множество мест. Вполне возможно, что вам будет достаточно вести журнал, например, только в консоли или только в окно отладки. В ASP.NET Core мы можем настроить необходимые нас провайдеры логирования.

Методы регистрации провайдеров логирования

Провайдеры логирования регистрируются в приложении с использованием методов расширения для ILoggingBuilder. Эти методы, обычно, имеют имена, соответствующие шаблону:

Add[ProviderName](Action<[TProviderOptions> configure])

или, начиная, с .NET 5:

Add[Format][ProviderName]( Action<[TProviderOptions> configure])

здесь

• ProviderName – имя провайдера (Debug, Console, EventLog или TraceSource)
• Action<[TProviderOptions]> – делегат, используемый для настройки провайдера. Этот параметр может отсутствовать или не использоваться в методах.
• [Format] – имя форматировщика, используемого в провайдере. Этот элемент названия используется для провайдера Console, например, могут использоваться такие имена методов: AddSimpleConsole() или AddJsonConsole().

Объектом, реализующим этот интерфейс выступает свойство WebApplicationBuilder.Logging. Например, чтобы зарегистрировать в приложении провайдер Debug, мы должны использовать следующий метод расширения:

builder.Logging.AddDebug();

Рассмотрим примеры добавления различных провайдеров логирования в приложение ASP.NET Core.

Провайдер Console

До выхода .NET 5 в ASP.NET Core для регистрации провайдера Console использовались методы расширения AddConsole(). Стоит отметить, что и сейчас, в .NET 8 и более поздних версиях мы можем воспользоваться этим методом, однако, если мы попытаемся использовать перегруженную версию метода с делегатом Action<ConsoleLoggerOptions>, то обнаружим, что большая часть свойств класса ConsoleLoggerOptions не рекомендуется использовать

Для нас это, как минимум, означает, что в следующих версиях .NET такие настройки могут, в принципе, исчезнуть и придется вносить правки в исходный код приложения. Поэтому лучше сразу использовать последние версии методов расширения:

Рассмотрим использование этих методов в приложении ASP.NET Core Web API

«Простой» провайдер Console

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Logging.ClearProviders();
builder.Logging.AddSimpleConsole(config=> 
{
    config.SingleLine = true;
    config.ColorBehavior = Microsoft.Extensions.Logging.Console.LoggerColorBehavior.Disabled;
    config.IncludeScopes = true;
    config.UseUtcTimestamp = true;
    config.TimestampFormat = "G";
});

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Во-первых, мы полностью удаляем все зарегистрированные провайдеры:

buildeor.Lgging.ClearProviders();

Затем мы добавляем «простой» провайдер с настройками:

builder.Logging.AddSimpleConsole(config=> 
{
    config.SingleLine = true;
    config.ColorBehavior = Microsoft.Extensions.Logging.Console.LoggerColorBehavior.Disabled;
    config.IncludeScopes = true;
    config.UseUtcTimestamp = true;
    config.TimestampFormat = "G";
});

Здесь для настройки провайдера мы используем делегат, который принимает объект класса SimpleConsoleFormatterOptions у которого, в свою очередь, определены следующие свойства

Для сравнения, на рисунке ниже показан лог в консоли с нашими настройками и по умолчанию:

Провайдер Console с форматированием сообщений в JSON

Для добавления такого провайдера нам необходимо использовать метод AddJsonConsole(). Стоит отметить, что если в приложении вызываются несколько методов Add[Format]Console(), то будет использоваться последний добавленный форматировщик. Рассмотрим следующий пример

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Logging.ClearProviders();
builder.Logging.AddSimpleConsole(config =>
{
    config.SingleLine = true;
    config.ColorBehavior = Microsoft.Extensions.Logging.Console.LoggerColorBehavior.Disabled;
    config.IncludeScopes = true;
    config.UseUtcTimestamp = true;
    config.TimestampFormat = "G";
});

builder.Logging.AddJsonConsole(config => 
{
    config.JsonWriterOptions = new()
    {
        Indented = true,
    };
    config.UseUtcTimestamp = true;
    config.TimestampFormat = "G";
});

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Так как последним вызывается метод AddJsonConsole(), то будет использоваться форматировщик в JSON. Для настройки провайдера используется класс JsonConsoleFormatterOptions у которого определено свойство JsonWriterOptions – настройки форматирования в JSON. В нашем примере мы указали, что при форматировании необходимо использовать отступы, то есть, при запуске приложения мы увидим следующий вывод лога

Провайдер Console с форматированием для systemd

Systemd — подсистема инициализации и управления службами в Linux. Для вывода в консоль лога в формате, подходящем для systemd необходимо добавить провайдер Console с использованием метода расширения AddSystemdConsole(). В итоге, лог будет выглядеть следующим образом:

Провайдер Debug

Этот провайдер выводит лог в окно отладки (Debug). В отличие от предыдущего провайдера, Debug не имеет никаких дополнительных настроек и, поэтому, его регистрация осуществляется с использованием единственного метода – AddDebug() без каких-либо параметров:

builder.Logging.ClearProviders();
builder.Logging.AddDebug();

Так как мы больше не используем никакие провайдеры ведения журнала, кроме Debug, то после запуска приложения консоль приложения останется пустой, а лог можно будет увидеть в окне «Отладка» Visual Studio

Провайдер EventLog

Этот провайдер ведет запись в журнал событий Windows и поэтому доступен только в этой операционной системе.  Как говорилось ранее, по умолчанию, приложение ASP.NET Core выводит сообщения в журнал событий Windows только уровня Warning и выше. Поэтому, чтобы воспользоваться этим провайдером для ведения журнала, нам необходимо выполнить два действия:

1. Добавить в приложение необходимую конфигурацию провайдера EventLog (например, с использованием json-файла), если мы планируем выводить в лог сообщения с уровнем ниже, чем Warning, например, Information.
2. Вызвать одну из версий метода расширения AddEventLog() для регистрации провайдера в приложении.

Например, создадим следующую конфигурацию провайдера EventLog в файле appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft.AspNetCore": "Trace"
    },
    "EventLog": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "AllowedHosts": "*"
}

И добавим провайдер EventLog в список провайдеров:

builder.Logging.ClearProviders();
builder.Logging.AddEventLog();

По умолчанию все сообщения от нашего приложения попадают в журнал Windows со следующими параметрами:

1. Источник «.NET Runtime»
2. Имя журнала «Приложение» (Application)

Запустим приложение и откроем журнал событий Windows, чтобы убедиться, что все сообщения лога с уровнем Information и выше попадают в журнал

Уровень журнала по умолчанию

По умолчанию, когда мы создаем приложение ASP.NET Core Web API, Visual Studio самостоятельно создает необходимую конфигурацию приложения и нам остается только внести в эту конфигурацию какие-либо изменения в зависимости от наших потребностей.

Что касается ведения журналов, то, обычно, их конфигурация хранится в файлах appsettings.json или appsettings.{Environment}.json. При этом мы можем установить для всех провайдеров минимальный уровень ведения журнала, если по каким-либо причинам нам станет недоступна конфигурация из JSON-файлов.

Рассмотрим пример. Создадим новое приложение ASP.NET Core Web API на основе контроллеров и удалим из проекта файлы appsettings.json и appsettings.Development.json. Теперь запустим приложение. Вы увидите, что ASP.NET Core по умолчанию установила для журналов минимальный уровень Information

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

builder.Logging.SetMinimumLevel(LogLevel.Warning);

Этот метод программно устанавливает минимальный уровень журнала для всех используемых в приложении провайдеров. Так, если мы воспользуемся приведенным выше кодом в нашем приложении, то при запуске консоль останется пустой, так как все передаваемые сообщения имеют уровень Information (ниже, чем Warning).

Итого

При необходимости, мы можем указывать в приложении ASP.NET Core только те провайдеры ведения логов, которые нам необходимы. Провайдер Console может выводить сообщения в одну строку, с цветовым оформлением или без него, а также в форматах JSON и systemd.