Подсистема журналирования

Описание подсистемы журналирования

Подсистема журналирования Comindware Platform использует библиотеку NLog (с открытым исходным кодом), которая записывает данные в файлы журналов.

Полная документация по настройке NLog для журналирования в файлы представлена по адресу: https://github.com/NLog/NLog/wiki/File-target

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

• Linux
  • /var/www/<instanceName>/logs.config — конфигурация всех журналов экземпляра ПО, включая журналы встроенных адаптеров;
  • /var/www/<instanceName>/data/Plugins/Agent/logs.config — конфигурация журналов пользовательских адаптеров.
• Windows
  • C:\ProgramData\Comindware\Instances\<instanceName>\Config\logs.config — конфигурация всех журналов экземпляра ПО, включая журналы встроенных адаптеров;
  • C:\ProgramData\Comindware\Instances\<instanceName>\Config\data\Plugins\Agent\logs.config — конфигурация журналов пользовательских адаптеров.

Здесь и далее <instanceName> — имя экземпляра ПО.

Подробное описание структуры конфигурационного файла см. в документации NLog по адресу: https://github.com/NLog/NLog/wiki/Tutorial

По умолчанию файлы журналов хранятся на сервере с экземпляром ПО в следующей директории:

• Linux
  • /var/log/comindware/<instanceName>/Logs
• Windows
  • C:\ProgramData\comindware\Instances\<instanceName>\Logs

Сведения о фактическом расположении файлов см. в статье «Пути и содержимое папок экземпляра ПО».

Файловые журналы

ПО поддерживает следующие файловые журналы:

• Адаптеры
• Аудит
• Интеграция
• Интеграция — сырые данные
• Исправность ПО
• Обновление
• Ошибки
• Процессы
• Системный журнал
• Резервное копирование
• Трансфер — в составе журнала ошибок

Каждый из перечисленных журналов представляет собой структурированный текстовый файл с пробелами в качестве разделителей.

В качестве инструментов чтения и анализа файлов журналов можно использовать любой инструмент, представленный на рынке. Например, есть мощный инструмент Kibana https://www.elastic.co/products/kibana, который обладает широким спектром функций по сбору журналов с различных ресурсов и их глубокому анализу с различными визуальными представлениями, в том числе в виде графиков.

Правила формирования и архивирования файлов журналов

Каждый журнал (кроме журнала обновления) формируется как один файл на каждый день.

Журнал обновления формируется при выполнении обновления версии ПО и заменяет предыдущий файл журнала обновления.

В конце дня файлы журналов архивируются в папку \Archive в архивы вида CBAP_ГГГГ-ММ-ДД.

По умолчанию ПО сохраняет в архиве до 5 файлов журнала каждого типа (кроме журнала интеграции с сырыми данными, см. «Журнал интеграции с сырыми данными»), т. е. за день в архиве будет храниться не более 5 файлов каждого журнала, а остальные будут удаляться в очерёдности их создания.

Типы событий в журналах

В журналах предусмотрены следующие типы событий:

• Fatal — критическая ошибка в работе ПО;
• Error — ошибка в работе ПО;
• Warn — некорректное поведение, но ПО продолжает свою работу;
• Info — обычное событие, например отправка письма, обновление данных аккаунта;
• Debug — выполнение запросов, аутентификация пользователей;
• Trace — запуск методов, завершение методов.

Журнал аудита

Журнал аудита содержит перечисленные ниже события:

• Неуспешные попытки входа в Систему.
• Успешный вход в Систему.
• Выход из Системы.
• Веб-запросы клиента, отправляемые пользователями на сервер (запрос данных или сохранение данных).
• Изменения системных ролей и ролей в приложениях.
• Попытки несанкционированного доступа для просмотра, создания, редактирования и удаления данных в следующих разделах:
  • API
  • Записи, экземпляры процессов, аккаунты
  • Прикреплённые к записям файлы
  • Страницы:
    • Администрирование системы
      • Темы
      • Дизайн страницы входа и регистрации
      • Приложения
      • Разделы навигации
      • Шаблоны
      • Функции
      • Пути передачи данных
      • Аккаунты
      • Группы
      • Системные роли
      • Аудит разрешений аккаунтов
      • Замещение
      • Регистрация и вход
      • Мониторинг
      • Журналы событий
      • Лицензирование
      • Резервное копирование
      • Управление системными службами
      • Подключения
      • Производительность
      • Конфигурация журналирования
      • Глобальная конфигурация
    • Администрирование приложения
      • Шаблоны
      • Роли
      • Разделы навигации
      • Функции
      • Переменные
      • Сценарии
      • Интернет-магазин
      • Интеграции
      • Пути передачи данных
      • Active Directory
      • Аудит разрешений аккаунтов
      • Активность компонентов
      • Управление версиями

Стандартное имя файла журнала аудита: audit_ГГГГ-ММ-ДД.log

Журнал сообщений аудита содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• IP-адрес клиента;
• адрес сервера;
• статус обработки запроса;
• длительность обработки запроса;
• запрос или текст сообщения;
• сведения об изменении роли.

Журнал интеграции

Журнал интеграции содержит информационные сообщения по событиям, возникающим в ходе работы интеграционных сервисов ПО (таких, как подключения и адаптеры).

Стандартное имя файла журнала ошибок: integration_ГГГГ-ММ-ДД.log

Журнал интеграции содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• имя сервера;
• порт сервера
• IP-адрес клиента;
• идентификатор интеграции;
• идентификатор подключения;
• текст сообщения.

Журнал интеграции с сырыми данными

Журнал интеграции с сырыми данными содержит те же сведения, что журнал интеграции, но с полным содержимым сообщений от внешних систем.

Стандартное имя файла журнала с сырыми данными: integration_raw_ГГГГ-ММ-ДД.log

По умолчанию для файла журнала интеграции с сырыми данными установлено ограничение на размер в 100 МБ. В случае превышения заданного размера, имя файла меняется на имяжурнала_ГГГГ-ММ-ДД.<порядковый номер файла>.log, а в каталоге журналов создаётся новый файл журнала со стандартным именем.

По умолчанию в архивах хранится максимум 50 файлов журнала интеграции с сырыми данными, т. е. за день в архиве будет храниться не более 50 файлов каждого журнала, а остальные будут удаляться в очерёдности их создания.

Журнал интеграции с сырыми данными содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• адрес сервера;
• порт сервера;
• IP-адрес клиента;
• текст сообщения.

Журнал исправности

Журнал исправности содержит сведения о состоянии экземпляра ПО: дисковом пространстве, использовании подключений, работе сервиса OpenSearch (Elasticsearch), работе подсистем, выполнении экземпляров процессов.

Стандартное имя файла журнала исправности: heartbeat_ГГГГ-ММ-ДД.log

Журнал исправности ПО содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• адрес сервера;
• порт сервера;
• IP-адрес клиента;
• текст сообщения.

Журнал обновления

Журнал обновления содержит сведения о результатах обновления версий ПО.

Журнал обновления разделён на два файла:

• UpgradeOntology.log — информация об обновлении структуры данных;
• update_ГГГГ-ММ-ДД.log — информация о ходе процесса обновления.

Журнал обновления содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• адрес сервера;
• порт сервера;
• IP-адрес клиента;
• текст сообщения.

Журнал ошибок

Журнал ошибок содержит данные обо всех ошибках, возникающих в ходе работы экземпляра ПО, а также об импорте и экспорте версий приложений.

Стандартное имя файла журнала ошибок: error_ГГГГ-ММ-ДД.log

Журнал ошибок содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• имя сервера;
• порт сервера;
• IP-адрес клиента;
• идентификатор события;
• имя подсистемы, в которой произошло событие;
• длительность обработки запроса;
• версия ПО;
• идентификатор интеграции;
• идентификатор подключения;
• сообщение об ошибке.

Журнал процессов

Журнал процессов содержит сведения о движении токенов по элементам экземпляров процессов.

Стандартное имя файла журнала процессов: process_ГГГГ-ММ-ДД.log

Журнал процессов содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• идентификатор экземпляра процесса;
• идентификатор токена;
• идентификатор элемента экземпляра процесса;
• текст сообщения;
• длительность выполнения.

Рекомендации по чтению журнала процессов

• В журнале процессов отражается факт создания экземпляра процесса с указанием его идентификатора.
• Чтобы журнал процессов содержал более наглядные сведения, при настройке диаграммы процесса давайте элементам понятные системные имена.
• Для элемента диаграммы процесса указываются сведения о трёх событиях:
  • создание токена или вход токена в элемент — строка с идентификатором элемента вида Enter(psa.XXX) by Flow:psf.XXX (при создании токена не указывается идентификатор потока);
  • выполнение элемента — строка с идентификатором элемента вида Execute или ContinueExecute;
  • выход токена из элемента — строка с идентификатором потока вида Exit by Flow:psf.XXX.
• В строке события могут быть указаны следующие сведения:
  • идентификатор экземпляра процесса вида PID:XXX;
  • идентификатор токена вида TID:ptkn.XX;
  • системное имя и идентификатор элемента вида (elementSystemName)psa.XXX;
  • системное имя и идентификатор потока вида psf.XXX;
  • идентификатор потока с идентификатором потока вида Flow:psf.XXX;
  • перечень последующих элементов, начинающийся с ключевого слова NextActions.

Журнал резервного копирования

Журнал резервного копирования содержит информационные сообщения по результатам резервного копирования экземпляра ПО.

Стандартное имя файла журнала резервного копирования: backup_ГГГГ-ММ-ДД.log

Журнал резервного копирования содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• адрес сервера;
• порт сервера;
• IP-адрес клиента;
• текст сообщения.

Журнал сценариев

Журнал сценариев содержит сведения о ходе выполнения сценариев.

Стандартное имя файла журнала сценариев: trigger_ГГГГ-ММ-ДД.log

Журнал сценариев содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• инициатор вызова сценария;
• идентификатор сценария;
• тип события, запустившего сценарий;
• идентификатор шаблона записи;
• идентификатор записи;
• длительность выполнения;
• сведения о действиях, исполненных в ходе сценария:
  • идентификатор действия сценария;
  • тип действия;
  • идентификатор шаблона записи;
  • идентификатор записи;
  • длительность выполнения.

Системный журнал

Системный журнал содержит данные о событиях системного уровня в экземпляре ПО.

Стандартное имя файла системного журнала: system_ГГГГ-ММ-ДД.log

Системный журнал содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• ID сеанса;
• имя аккаунта, инициировавшего событие;
• адрес сервера;
• порт сервера;
• IP-адрес клиента;
• текст сообщения.

Журналы адаптеров

Журналы адаптеров содержат данные о событиях подключений и путей передачи данных, относящихся к адаптерам в экземпляре ПО.

Имена файлов журналов адаптеров формируются следующим образом:

• сервис встроенных адаптеров: adapter_internal_ГГГГ-ММ-ДД.log
• сервис пользовательских адаптеров: adapter_external_system_ГГГГ-ММ-ДД.log
• подключение встроенного адаптера: adapter_internal_<имя_подключения>_ГГГГ-ММ-ДД.log
• подключение заказного адаптера: adapter_external_<имя_подключения>_ГГГГ-ММ-ДД.log
• исправность заказного адаптера: adapter_external_heartbeat_ГГГГ-ММ-ДД.log
• подключение заказного адаптера к брокеру сообщений: adapter_external_kafkaClient_ГГГГ-ММ-ДД.log

Журнал адаптера содержит следующие сведения:

• дата события;
• время события;
• тип сообщения;
• описание события;
• контекст события;
• описание исключения (необязательно);
• текст сообщения (необязательно).

Перенаправление сообщений из файлов журналов в журнал событий Windows

Библиотека NLog позволяет записывать журналы помимо файлов в другие хранилища, например в службу «Журнал событий Windows» (EventLog), который можно просмотреть с помощью приложения Просмотр событий.

Полная документация по настройке журналирования в журнал событий Windows представлена по адресу:

https://github.com/NLog/NLog/wiki/EventLog-target

В данном разделе представлены инструкции по перенаправлению сообщений из файла журнала ошибок экземпляра ПО в журнал событий Windows.

1. Создайте в журнале событий Windows новый источник событий (EventSource), если его ещё нет.

2. Создайте скрипт по приведённому ниже образцу на языке VisualBasic и сохраните его в файл с расширением .VBS (например, CreateEventSource.vbs):

   Set Args = WScript.Arguments 
   If Args.Count < 1 then WScript.Echo "USAGE: CreateEventSource.vbs <EventSourceName>" 
       WScript.Quit 
   End If 
   EventSourceName = Args(0) 
   Set WshShell = WScript.CreateObject("WScript.Shell") 
   'Create event source 
   KeyName = "HKLM\SYSTEM\CurrentControlSet\Services\Eventlog\Application\" & EventSourceName & "\EventMessageFile" 
   'Change path to .NET Framework version used 
   WshShell.RegWrite KeyName,"%windir%\Microsoft.NET\Framework64\v2.0.50727\EventLogMessages.dll", "REG_EXPAND_SZ" 
   

3. Запустите скрипт, который создаст источник событий (EventSource) в журнале событий Windows.

   В качестве параметра передайте название источника событий, которое будет отображаться в разделе «Журналы Windows / Приложение» (Windows Logs / Application) приложения приложении «Просмотр событий».

   Пример команды запуска скрипта:

   CreateEventSource.vbs "CBAP" 
   

4. Создайте в файле logs.config в подразделе nlog.targets (с конфигурацией файловых журналов) подраздел target с параметрами записи данных в журнал событий Windows:

   <target xsi:type="EventLogCBAPErrors" name="eventlog" layout="${message}" 
   log="Application" source="CBAP"/> 
   

5. Создайте в файле logs.config правило (подраздел logger в разделе nlog.rules), которое будет определять сообщения, подлежащие записи в журнал событий Windows:

   <logger name="*" minlevel="Warn" maxlevel="Fatal" 
   writeTo="errorsFile,EventLogCBAPErrors"/> 
   

6. Перезагрузите экземпляр ПО, чтобы изменения вступили в силу. См. раздел «Настройка конфигурации Утилиты администрирования Comindware».