В настоящее время даже самое простое приложение тем или иным образом регистрирует данные, но что должно быть наилучшей практикой для записи ваших журналов, чтобы получить от них максимальную отдачу, не тратя слишком много вашего драгоценного времени (или денег).
В этой статье дается краткая справочная информация о практике структурированного ведения журнала и проводится пошаговая инструкция по включению структурированного ведения журнала в вашем приложении с помощью красивой панели инструментов.
Что мы хотим от наших журналов?
Что ж, это может варьироваться от приложения к приложению или от разных компаний, но вот 5 общих вещей, которые большинство из нас хочет получить из наших журналов:
- Помогите устранить неполадки и диагностировать проблемы в приложении как можно быстрее
- Аудит значимых действий и событий в приложении
- Мониторинг использования системы для предотвращения потенциальных проблем до их возникновения
- Анализировать использование системы для повышения удобства использования приложения
- Использовать другие инструменты анализа данных для поддержки принятия решений на основе данных
Как структурированное ведение журнала может в этом помочь?
Структурированное ведение журнала - это практика обработки журналов как данных, которые мы собираемся запрашивать и анализировать. Для поддержки этого журнал приложения спроектирован так, чтобы иметь согласованную структуру с ранней стадии разработки с определенными свойствами для ваших точек интереса в соответствии с потребностями вашего приложения.
Большинство языков программирования имеют библиотеки для поддержки структурированного ведения журнала, что делает реализацию более плавной и быстрой. Соответственно, с этими библиотеками интегрировано множество отличных инструментов, обеспечивающих интерфейс управления журналами. Эти инструменты в полной мере используют преимущества структурированного ведения журнала - дайджеста и обслуживают журналы в удобочитаемом интерфейсе, который упрощает задачу устранения неполадок. Большинство инструментов также позволяют вам устанавливать важные события (на основе тех свойств, которые вы определили) для аудита и мониторинга, а также отправки предупреждений при необходимости. В этой статье мы увидим такую библиотеку и инструмент для управления журналами.
Со временем вы узнаете больше о своем приложении и своих пользователях, вы будете отслеживать потенциальные узкие места и получать аналитическую информацию на основе данных, которая поможет вам принимать более обоснованные решения для следующих версий / обновлений и т. Д.
Пример использования ASP.NET Core (3.1), Serilog и Seq - шаг за шагом
.NET Core имеет встроенный API ведения журналов, который можно использовать как есть, но также можно аккуратно интегрировать со сторонними платформами ведения журналов. Дополнительную информацию о ведении журнала по умолчанию можно найти в этой подробной статье Microsoft docs.
В этом случае я использовал Serilog для своей структуры структурированного ведения журнала и Seq в качестве инструмента управления журналом. Есть много других вариантов.
Настройка Serilog в вашем приложении для реализации структурированного ведения журнала
Serilog - это сторонняя библиотека с открытым исходным кодом для ведения журналов .NET Core. Его легко настроить в приложении и переопределить встроенное ведение журнала Microsoft, он ориентирован на структурированное ведение журнала, имеет большое сообщество пользователей и относительно хорошую документацию.
Приемники Serilog. Помимо всех вышеперечисленных преимуществ этой библиотеки, она поддерживает очень широкий спектр так называемых приемников - готовых к использованию интеграций для записи событий журнала в другие инструменты / платформы / хранилище. Насколько велик этот диапазон? На момент написания этих строк доступно более 90 раковин, полный список вы можете найти в этой статье о предоставленных раковинах. Один из этих приемников предназначен для инструмента управления журналами Seq, который мы будем использовать.
Настраиваемые свойства Serilog. При регистрации будут присутствовать некоторые предопределенные свойства, которые являются частью структуры и будут заполняться автоматически. Одна из реальных сильных сторон Serilog заключается в простоте определения пользовательских свойств в вашем коде. Следуя требуемому синтаксису шаблона сообщения, вы можете просто регистрировать различные свойства, в зависимости от вашей конкретной функции или возможности. Найдите имя настраиваемого свойства в квадратных скобках {} в строке сообщения и передайте значения в качестве параметров. Ниже вы увидите несколько примеров.
Шаги по настройке Serilog -
Первым шагом будет добавление нескольких пакетов Serilog в наш проект. В моем случае я добавил следующие.
/*csproj file*/ <PackageReference Include="Serilog.AspNetCore" Version="3.4.0" /> <PackageReference Include="Serilog.Enrichers.Environment" Version="2.1.3" /> <PackageReference Include="Serilog.Enrichers.Process" Version="2.0.1" /> <PackageReference Include="Serilog.Enrichers.Thread" Version="3.1.0" /> <PackageReference Include="Serilog.Settings.Configuration" Version="3.2.0-dev-00244" /> <PackageReference Include="Serilog.Sinks.Seq" Version="5.0.0-dev-00174" />
Теперь, перейдя к нашему JSON-файлу app.settings, мы удалим стандартные параметры ведения журнала Microsoft и установим наши собственные конфигурации Serilog, включая переопределение Microsoft, конфигурации приемника Seq и некоторые дополнительные параметры и свойства (которые являются необязательными).
/*app.settings (JSON file)*/
"Serilog": {
"Using": [],
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Warning"
}
},
"WriteTo": [
{
"Name": "Seq",
"Args": { "serverUrl": "MY_SEQ_SERVER_URL" }
}
],
"Enrich": [
"FromLogContext",
"WithMachineName",
"WithProcessId",
"WithThreadId"
],
"Properties": {
"ApplicationName": "MY_APP_NAME"
}
}
Затем нам нужно будет изменить наш файл проекта Program.cs, чтобы использовать Serilog в качестве регистратора по умолчанию для нашего приложения, и инициализировать глобальный экземпляр регистратора Serilog с конфигурациями из нашего файла app.settings.
/*PROGRAM.CS*/
//Main function
var config = new ConfigurationBuilder()
.AddJsonFile("appsettings.json")
.Build();
Log.Logger = new LoggerConfiguration()
.ReadFrom.Configuration(config)
.CreateLogger();
CreateHostBuilder(args).Build().Run();
//CreateHostBuilder function
Host.CreateDefaultBuilder(args)
.UseSerilog() //<-Add this row
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Мы сделали. Теперь в каждом классе, который мы хотели бы использовать наш регистратор, все, что нам нужно сделать, это внедрить класс интерфейса Microsoft ILogger (используя внедрение зависимостей) и использовать его функции API. Поскольку мы уже настроили переопределение регистратора по умолчанию, будет использоваться Serilog. Существует несколько уровней журнала, наиболее часто используемые: «Информация», «Предупреждение», «Ошибка» и «Критический». Ниже приведен пример внедрения зависимостей и регистрации ошибок.
/*Class (.cs file)*/
private readonly ILogger log;
//Constructor
public CLASS_NAME(ILogger<CLASS_NAME> logger)
{
log = logger;
}
private void Func()
{
log.LogError("The user {Username} could not authenticate." +
" Error message: {Error}", Username, ExceptionMsg);
}
Ниже приведен еще один пример внедрения атрибутов в приложение .NET Core Blazor, ведение журнала уровня информации.
/*Blazor component base class (.cs file)*/
[Inject]
ILogger<CLASS_NAME> log { get; set; }
private void Func()
{
log.LogInformation("Resource was loaded for user {Username}", username);
}
Настройка Seq для управления журналами и визуализации
Seq - это бесплатный (однопользовательский) инструмент для управления журналами. Ниже представлена информация о компании.
Seq обеспечивает прозрачность, необходимую для быстрого выявления и диагностики проблем в сложных приложениях и микросервисах.
Я склонен согласиться и думаю, что это может помочь улучшить ваше приложение, помимо задач по устранению неполадок. Вот некоторые из его замечательных особенностей -
Seq Stream - Seq полностью использует структурированное ведение журнала, он обеспечивает поток всех журналов с четким указанием различных уровней журналов. После развертывания определенного события вы получаете отображение всех свойств, а еще через 2 щелчка мыши вы уже запрашиваете по свойству весь поток. Вы также можете фильтровать и писать свои собственные SQL-запросы поверх потока. Более интуитивно понятного и быть не может.
Seq Dashboards. Кому не нравятся модные информационные панели? Это, наверное, самая сильная сторона Seq. Его очень наглядно и легко настроить в соответствии с вашими потребностями, добавив любой ценный фильтр / запрос потока одним щелчком мыши прямо на панель инструментов. Это позволяет вам проверять важные события вашего приложения и отслеживать использование (например, на скриншоте ниже я установил виджет «Новые ссуды», чтобы отслеживать новые события ссуды на книги в моем приложении библиотеки). Щелкнув любое значение на панели инструментов, вы сразу же перейдете к подробным результатам соответствующего потока.
Вы можете установить временной диапазон приборной панели от 5 минут до 1 года .. и установить автоматическое обновление экрана. Поставляется с 6 различными типами графиков. Расположение виджетов, их размеры и цвета можно настроить.
Seq Apps. Приложения - это плагины, которые обрабатывают события и предупреждения или принимают события из внешнего источника. В настоящее время существует около 70 доступных подключаемых модулей, некоторые из них действительно полезны, и если вы не нашли нужный, вы можете написать свой собственный подключаемый модуль с их пакетом .NET. Вы можете проверить список доступных плагинов. В конце статьи я продемонстрирую, как использовать один из них для реализации предупреждений.
Шаги по настройке Seq -
Seq получает свои журналы из нескольких библиотек журналов, которые реализовали эту интеграцию, которые доступны на разных языках, таких как .NET, Python, Node.js, Java, Ruby и Go, а также поддерживает использование API приема HTTP. В нашем случае библиотека Serilog отлично работает с Seq.
Как вы видели ранее, мы уже настроили приемник Seq в нашем JSON-файле app.settings. Итак, да, с этими двумя строками кода все, что нам нужно, это загрузить и развернуть наш экземпляр Seq, и он будет работать. Это так просто. Не забудьте обновить app.settings, указав URL-адрес сервера вашего экземпляра Seq.
Что касается установки инструмента, согласно их отличной документации, в настоящее время он поддерживает развертывание в Windows, Docker, Kubernetes и Azure. Выбрав предпочтительное развертывание и следуя их инструкциям, все будет в порядке.
Теперь вы можете запустить свое приложение и обновить поток Seq, запросить его, создать свои персональные информационные панели и приступить к настройке подключаемых модулей, необходимых для архивирования, настройки предупреждений и интеграции с платформами вашей компании. Позже добавьте больше своих приложений в новый инструмент Seq и создайте разные панели мониторинга для управления журналами всех приложений из одного места.
Бонус - интеграция журналов Seq с вашими командами Microsoft
В этой последней главе я продемонстрирую, как настроить подключаемый модуль MS Teams для Seq и настроить оповещения непосредственно с панели управления Seq на эту популярную коммуникационную платформу. В этом случае в мои команды MS будет отправляться предупреждение для каждого события журнала уровня ошибки.
Шаги по настройке интеграции Seq-MS Teams -
Перейдите в «Настройки» и выберите вкладку «ПРИЛОЖЕНИЯ» на левой панели навигации. Под идентификатором пакета вы найдете список популярных приложений, одно из которых - Microsoft Teams - нажмите на него и установите.
После завершения установки нажмите Добавить экземпляр. Есть 2 обязательных поля - заголовок и URL-адрес веб-перехватчика Teams. Откройте MS Teams и настройте пользовательский входящий веб-перехватчик, следуя инструкциям в этой статье Microsoft docs. Скопируйте уникальный URL-адрес веб-перехватчика и вставьте его в соответствующее поле настроек Seq. В моем случае я настроил его в группе Журнал в моих командах MS. После настройки вы должны увидеть Входящий веб-перехватчик в меню настроенных коннекторов.
Перейдите на панель управления Seq. Один из стандартных виджетов - «Ошибки и исключения». Разверните его и выберите вкладку ПРЕДУПРЕЖДЕНИЯ, щелкните значок добавления, заполните форму настроек и сохраните изменения панели управления. Ниже приведен пример настроек, которые будут отправлять журнал любого уровня ошибок с интервалом в 15 минут в MS Teams.
Это все. Теперь ваши журналы уровня ошибок будут отправлены вашим командам MS. Настройка предупреждений для коммуникационной платформы вашей компании - отличный способ быстрее получать уведомления о критических проблемах. Есть много других доступных приложений для интеграции с вашим почтовым сервером, Slack, Azure DevOps, Trello и другими.
Конец.
Став Софер, ноябрь 2020 г.
