Логирование (ведение журналов, журналирование) — это процесс записи наиболее значимой информации о работе системы с возможностью быстрого доступа к этой информацией в случае необходимости.
Общие сведения о логировании
В ASP.NET Core имеется достаточно мощная система логирования. Так, когда мы вызываем метод WebApplication.CreateBuilder()
, то в наше приложение автоматически добавляются следующие поставщики (провайдеры) логирования:
- Console – выводит выходные данные в консоль.
- Debug – записывает выходные данные журнала с помощью класса
System.Diagnostics.Debug
. - EventSource – записывает выходные данные журнала в кроссплатформенный источник событий с именем
Microsoft-Extensions-Logging
. - EventLog (только в Windows) – отправляет выходные данные журнала в журнал событий Windows.
ASP.NET Core использует сервис, представленный интерфейсом ILogger
(или его универсальным наследником ILogger<T>
), который является единым интерфейсом для ведения журнала. Условно, использование ILogger
при работе приложения можно представить так (см. Рисунок 84):
При вызове одного из методов ILogger
для ведения лога производится запись с использованием всех поставщиков, зарегистрированных в приложении. Например, если запустить наше приложение и посмотреть куда выводятся сообщения, которые мы видим в консоли, то можно увидеть, что приложение выводит сообщения как в консоль, так и в окно Debug (“Отладка»).
Однако, как мы увидим далее, каждый провайдер логирования можно настроить по нашему усмотрению на вывод любых сообщений.
Сообщение в консоли состоит из нескольких частей
Рассмотрим, как мы можем вести журнал работы приложения в ASP.NET Core.
Интерфейс ILogger
Итак, ILogger
– это сервис, благодаря которому нам не приходится задумываться о том, какой провайдер логирования и как использовать. Достаточно зарегистрировать необходимые провайдеры в приложении и вызвать необходимый метод ILogger
, чтобы запись была опубликована в том или ином журнале. У этого интерфейса для нас наибольший интерес представляет следующий метод:
public void Log<TState> (LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter);
Этот метод выводит в лог форматированное сообщение. Основные параметры этого метода:
state
– тип объекта, который будет использоваться для записи.eventId
– идентификатор сообщения.exception
– исключение, связанное с сообщением лога.formatter
– функция, используемая для форматирования строки логаlogLevel
– уровень лога. Это перечисление, которое может принимать следующие значения:
Значение | Описание | |
Trace |
0 |
Журналы, содержащие наиболее подробные сообщения. Такие сообщения могут содержать конфиденциальные данные приложения и отключены по умолчанию. Такой уровень лога никогда не должен включаться в рабочей среде. |
Debug |
1 |
Журналы, которые используются для интерактивного исследования во время разработки. Эти журналы в первую очередь должны содержать информацию, полезную для отладки |
Information |
2 |
Журналы, отслеживающие общий поток работы приложения (именно эти сообщения мы видим в консоли, когда запускаем приложение) |
Warning |
3 |
Журналы, которые указывают на ненормальное или неожиданное событие в потоке работы приложения, но в остальном не приводят к остановке выполнения приложения. |
Error |
4 |
Журналы, в которых указывается, когда текущий поток выполнения останавливается из-за сбоя. Они должны указывать на сбой в текущем действии, а не на сбой всего приложения. |
Critical |
5 |
Журналы, описывающие неустранимый сбой приложения или системы или катастрофический сбой, требующий немедленного внимания |
None |
6 |
Не используется для записи сообщений журнала. Указывает, что категория ведения журнала не должна записывать никаких сообщений. |
Воспользуемся этим методом и посмотрим на результат его работы. Объект, реализующий этот интерфейс мы можем получить, используя свойство WebApplication.Logger
. Например:
var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); var app = builder.Build(); app.Logger.Log(LogLevel.Critical, "Сообщение с уровнем Critical"); app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();
Здесь мы выводим сообщение с уровнем Critical. Если запустить приложение, то в консоли мы увидим следующее информационное сообщение
Следует отметить, что для нашего удобства, у ILogger
имеется большое количество методов расширения, упрощающих вывод в лог сообщений. В таблице ниже представлены только основные из них и каждый из этих методов имеет ряд перегруженных версий, отличающихся другого от друга количеством используемых параметров.
Метод расширения | Описание |
Log(ILogger, LogLevel, String, Object[]) |
Выводит в лог уровня LogLevel форматированную строку |
LogCritical(ILogger, EventId, String, Object[]) |
Выводит в лог уровня Critical форматированную строку |
LogDebug(ILogger, EventId, String, Object[]) |
Выводит в лог уровня Debug форматированную строку |
LogError(ILogger, EventId, String, Object[]) |
Выводит в лог уровня Error форматированную строку |
LogInformation(ILogger, EventId, String, Object[]) |
Выводит в лог уровня Information форматированную строку |
LogTrace(ILogger, EventId, String, Object[]) |
Выводит в лог уровня Trace форматированную строку |
LogWarning(ILogger, EventId, String, Object[]) |
Выводит в лог уровня Warning форматированную строку |
Интерфейс ILogger<T>
Интерфейс ILogger<T>
наследует ILogger
и содержит похожие методы расширения, например LogInformation()
, LogTrace()
и так далее. Работа с объектами, реализующими этот интерфейс, ничем не отличается от работы с объектами, реализующими ILogger
за одним исключением – параметр T
у интерфейса ILogger<T>
выступает в качестве категории лога. Именно объекты, реализующие этот интерфейс, чаще всего используются в приложениях ASP.NET Core Web API. Вот, например, как используется этот интерфейс в контроллере WeatherForecastController
в шаблонном приложении ASP.NET Core Web API на основе контроллеров:
private readonly ILogger<WeatherForecastController> _logger; public WeatherForecastController(ILogger<WeatherForecastController> logger) { _logger = logger; }
Здесь запрашивается сервис ILogger<WeatherForecastController>
. В качестве параметра выступает непосредственно тип контроллера – WeatherForecastController
. Если воспользоваться этим сервисом в контроллере, то мы увидим в консоли сообщение следующего формата
Итого
Ведение журналов в ASP.NET Core осуществляется с использованием сервиса ILogger
. Вызывая методы ILogger
или его наследника ILogger<T>
мы производим запись сообщения сразу во все зарегистрированные источники, используя провайдеры логирования (консоль, окно Debug и т.д.)