Настройка логирования ПУИД

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

Общая схема

Логирование серверных сервисов ПУИД настраивается через файл logback.xml. Формат и доступные элементы конфигурации описаны в официальной документации Logback.

При развертывании на виртуальную машину logback.xml устанавливается в каталог настроек конкретного сервиса. Этот файл используется сервисом при запуске и является основной точкой настройки логирования.

При эксплуатации администратор редактирует установленный logback.xml конкретного компонента. После изменения файла перезапустите сервис, если в поставке не используется автоматическое перечитывание конфигурации.

Типовые операции администратора

Изменение уровня логирования

Для изменения уровня логирования необходимо:

1. Открыть logback.xml нужного сервиса из раздела Справочник путей к конфигурационным файлам.

2. Найти logger или root logger, для которого нужно изменить уровень.

3. Установить уровень INFO, DEBUG, TRACE, WARN или ERROR в зависимости от задачи диагностики.

4. Сохранить файл.

5. Перезапустить сервис, если конфигурация не перечитывается автоматически.

6. Проверить появление записей нужного уровня в журнале сервиса.

Для повседневной эксплуатации используйте INFO. Уровни DEBUG и TRACE включайте временно, потому что они увеличивают объем журналов и могут раскрывать диагностические детали.

Включение JSON Lines-вывод

Для включения JSON Lines-вывод необходимо:

1. Открыть logback.xml нужного сервиса.

2. Найти JSONL-appender и его привязку к logger или root logger.

3. Если привязка отключена комментарием, раскомментировать ее.

4. Сохранить файл и перезапустите сервис.

5. Проверить появление файла .jsonl в каталоге /var/log/<имя сервиса>.

JSON Lines-формат удобен для централизованного сбора и обработки логов, потому что каждая строка является отдельным JSON-событием.

Поиск журналов сервисов на VM

Чтобы найти журналы сервисов на VM необходимо:

1. Определить имя сервиса.

2. Найти основной журнал в подразделе Справочник путей к конфигурационным файлам.

3. Для HTTP-компонентов дополнительно проверить access log, если он настроен.

4. Для диагностики запуска сервиса также проверить системный журнал ОС для unit-файла сервиса.

Что можно настраивать

Основной файл журнала

Каждый сервис пишет основной журнал приложения в файл с расширением .log. В записи обычно включаются время события, уровень, поток выполнения, имя логгера, сообщение и диагностические поля, например идентификатор запроса, имя компонента, хост, система и пользователь.

Ротация логов

Для файловых журналов настроена ротация. В компонентах из справочника используются два основных подхода:

• ротация по размеру с ограниченным числом архивных файлов;

• ротация по дате и размеру с хранением архивов за заданный период.

Архивные файлы обычно сжимаются в .gz или .zip. Это ограничивает рост каталога логов, но не заменяет контроль свободного места на диске или настройки внешнего сборщика логов.

Access log

В компонентах, которые принимают HTTP-трафик, может быть отдельный access log. Например, в API Gateway предусмотрен отдельный файл access_log.log, куда пишутся события HTTP-доступа. Такой журнал удобен для разбора входящих запросов отдельно от прикладных сообщений.

Формат .log и .jsonl

Для ряда сервисов помимо обычного текстового .log подготовлен JSON Lines-вывод в файл .jsonl. Если такой appender есть в logback.xml, его можно включить для интеграции с системой централизованного сбора логов.

Интеграция с системным логгером ОС

Сервисы также могут писать часть сообщений в стандартный вывод. При запуске через systemd эти сообщения могут попадать в системный журнал ОС или в инфраструктурный сборщик логов. Для такой интеграции необходимо проверить, что в logback.xml включен вывод в консоль, а unit-файл сервиса собирает stdout/stderr.

Справочник путей к конфигурационным файлам

Компонент	Файл настройки логирования при развертывании на виртуальную машину
API Gateway WTL	/opt/roox-api-gateway-wtl/conf/roox-api-gateway-wtl/logback.xml
Audit Search API	/opt/roox-audit-search-api/conf/roox-audit-search-api/logback.xml
Audit Writer	/opt/roox-audit-writer/conf/roox-audit-writer/logback.xml
Certificate Service	/opt/roox-certificate-service/conf/roox-certificate-service/logback.xml
Federation WebAPI	/opt/roox-federation/conf/roox-federation/logback.xml
IAM Scheduler Service	/opt/roox-iam-scheduler-service/conf/roox-iam-scheduler-service/logback.xml
Identity Storage WTL	/opt/roox-identity-storage/conf/roox-identity-storage/logback.xml
Radius Server	/opt/roox-radius/conf/roox-radius/logback.xml
SSO Server WTL	/opt/roox-sso/conf/roox-sso/logback.xml
Sync Service WTL	/opt/roox-sync-service/conf/roox-sync-service/logback.xml
Token Storage	/opt/roox-token-storage/conf/roox-token-storage/logback.xml
WebAPI Customer WTL	/opt/roox-webapi-customer/conf/roox-webapi-customer/logback.xml
WebAPI Notifier WTL	/opt/roox-webapi-notifier/conf/roox-webapi-notifier/logback.xml
WebAPI OTP Settings	/opt/roox-webapi-otp-settings/conf/roox-webapi-otp-settings/logback.xml

Справочник путей логов по умолчанию

При установке пакета на виртуальную машину создается символическая ссылка из каталога логов установленного сервиса в стандартный каталог /var/log/<имя сервиса>. Поэтому при эксплуатации журналы удобнее искать и передавать в системы сбора логов именно по пути /var/log.

Например, для API Gateway WTL файл основного журнала доступен по стандартному пути /var/log/roox-api-gateway-wtl/roox-api-gateway-wtl.log. Тот же файл может быть виден и через каталог установленного сервиса: /opt/roox-api-gateway-wtl/logs/roox-api-gateway-wtl.log, потому что каталог /opt/roox-api-gateway-wtl/logs является ссылкой на /var/log/roox-api-gateway-wtl.

Компонент	Основной журнал	Дополнительные журналы, если настроены
API Gateway WTL	/var/log/roox-api-gateway-wtl/roox-api-gateway-wtl.log	/var/log/roox-api-gateway-wtl/access_log.log, /var/log/roox-api-gateway-wtl/roox-api-gateway-wtl.jsonl, /var/log/roox-api-gateway-wtl/roox-apache-httpclient.log, /var/log/roox-api-gateway-wtl/roox-catalina.log
Audit Search API	/var/log/roox-audit-search-api/roox-audit-search.log	/var/log/roox-audit-search-api/roox-audit-search.jsonl, /var/log/roox-audit-search-api/roox-apache-httpclient.log, /var/log/roox-audit-search-api/roox-catalina.log
Audit Writer	/var/log/roox-audit-writer/roox-audit-writer.log	/var/log/roox-audit-writer/roox-audit-writer.jsonl, /var/log/roox-audit-writer/messages.jsonl, /var/log/roox-audit-writer/hikari.log
Certificate Service	/var/log/roox-certificate-service/roox-certificate-service.log	/var/log/roox-certificate-service/roox-apache-httpclient.log, /var/log/roox-certificate-service/roox-catalina.log
Federation WebAPI	/var/log/roox-federation/roox-federation.log	/var/log/roox-federation/roox-federation.jsonl, /var/log/roox-federation/roox-apache-httpclient.log, /var/log/roox-federation/roox-catalina.log
IAM Scheduler Service	/var/log/roox-iam-scheduler-service/roox-iam-scheduler.log	/var/log/roox-iam-scheduler-service/roox-iam-scheduler.jsonl, /var/log/roox-iam-scheduler-service/hikari.log
Identity Storage WTL	/var/log/roox-identity-storage/roox-identity-storage.log	/var/log/roox-identity-storage/roox-identity-storage.jsonl, /var/log/roox-identity-storage/roox-apache-httpclient.log, /var/log/roox-identity-storage/roox-catalina.log
Radius Server	/var/log/roox-radius/roox-radius-server.log	/var/log/roox-radius/roox-apache-httpclient.log
SSO Server WTL	/var/log/roox-sso/roox-sso.log	/var/log/roox-sso/roox-sso-wso.log
Sync Service WTL	/var/log/roox-sync-service/roox-sync-service.log	/var/log/roox-sync-service/roox-sync-service-modules.log, /var/log/roox-sync-service/roox-sync-service.jsonl, /var/log/roox-sync-service/roox-apache-httpclient.log, /var/log/roox-sync-service/roox-catalina.log
Token Storage	/var/log/roox-token-storage/roox-token-storage.log	—
WebAPI Customer WTL	/var/log/roox-webapi-customer/roox-webapi-customer.log	/var/log/roox-webapi-customer/roox-webapi-customer.jsonl, /var/log/roox-webapi-customer/hikari.log
WebAPI Notifier WTL	/var/log/roox-webapi-notifier/roox-webapi-notifier.log	/var/log/roox-webapi-notifier/roox-webapi-notifier.jsonl, /var/log/roox-webapi-notifier/hikari.log
WebAPI OTP Settings	/var/log/roox-webapi-otp-settings/roox-webapi-otp-settings.log	/var/log/roox-webapi-otp-settings/roox-webapi-otp-settings.jsonl

Справочник параметров

Параметры логирования задаются средствами Logback в файле logback.xml. У Logback нет единого набора ключей формата *.properties, поэтому в таблице ниже перечислены эксплуатационные элементы, которые администратор обычно изменяет в XML-конфигурации.

Параметр	Значение по умолчанию	Пример	Описание
root.level	INFO	DEBUG	Уровень корневого logger. Допустимые значения: TRACE, DEBUG, INFO, WARN, ERROR. Используйте DEBUG и TRACE временно для диагностики
logger.<name>.level	наследуется от родительского logger	DEBUG	Уровень конкретного logger. <name> — имя logger из logback.xml. Позволяет включить подробную диагностику только для выбранной подсистемы
appender.file.path	путь основного журнала сервиса	/var/log/roox-sso/roox-sso.log	Путь файла, в который сервис пишет основной журнал. Для VM-поставки используйте путь в /var/log/<имя сервиса>/...
appender.rolling.maxFileSize	зависит от поставляемого logback.xml сервиса	100MB	Максимальный размер файла до ротации, если для appender используется ротация по размеру
appender.rolling.maxHistory	зависит от поставляемого logback.xml сервиса	30	Срок хранения архивных файлов при ротации по дате
appender.console.enabled	зависит от поставляемого logback.xml сервиса	true	Наличие вывода в stdout/stderr. При запуске через systemd такие сообщения может собирать системный журнал ОС
appender.jsonl.enabled	зависит от поставляемого logback.xml сервиса	true	Наличие привязки JSONL-appender к logger или root logger. Если привязка отключена комментарием, раскомментируйте ее для включения JSON Lines-вывода

Проверка после изменения

Для проверки после внесения изменений следует:

1. Проверить синтаксис измененного logback.xml по структуре XML.

2. Перезапустить измененный сервис, если конфигурация не перечитывается автоматически.

3. Проверить, что сервис успешно запустился.

4. Проверить основной журнал в /var/log/<имя сервиса>/.

5. Если включали JSONL-вывод, проверить появление и заполнение файла .jsonl.

6. Если меняли уровень логирования, проверить, что записи нужного уровня появились, а после завершения диагностики вернуть эксплуатационный уровень INFO.