Общий обзор

Общий обзор#

Логирование в проекте выполняется с использованием Logback (XML-конфигурация). Настройки логирования размещаются в каталоге {{workspace}}/application/config/ и разделяются на:

  • системные логи (контекст LoggerContext);

  • логи сессий (контекст LoggerContext-session).

Для внесения изменений предусмотрен механизм расширения: основные файлы подключают отдельные -ext файлы через директиву <include .../>. Такой подход позволяет вносить проектные изменения без модификации базовой поставки.

Структура конфигурационных файлов#

{{workspace}}/
└── application/
    └── config/
        ├── logback-LoggerContext.xml                 # Основной файл конфигурации системных логов
        ├── logback-LoggerContext-ext.xml             # Проектные настройки системных логов (дополнения/переопределения)
        ├── logback-LoggerContext-session.xml         # Основной файл конфигурации логов сессии
        └── logback-LoggerContext-session-ext.xml     # Проектные настройки логов сессии (дополнения/переопределения)

Важно

Логирование в проекте настроено с учетом системных и сессионных логов.
Изменение основных файлов конфигурации запрещено, но пользователь может вносить свои изменения через файлы logback-LoggerContext-ext.xml и logback-LoggerContext-session-ext.xml.

Источники логов и каналы доставки#

В инфраструктуре обычно одновременно используются несколько источников/каналов:

  1. STDOUT/STDERR процессов global3 и globalscheduler
    В Standalone такие сообщения попадают в systemd-journald и далее (в зависимости от конфигурации ОС) могут быть экспортированы в syslog.
    В Kubernetes сообщения из STDOUT/STDERR доступны через kubectl logs и стандартные механизмы контейнерного логирования.

  2. Syslog
    В конфигурацию можно добавить SyslogAppender (отправка на <ip_addr_server>:<port> с указанным facility).
    Следует учитывать, что syslog может получать сообщения как:

    • напрямую через SyslogAppender (на уровне приложения),

    • так и косвенно через цепочку stdout/stderr - journald - rsyslog (на уровне ОС).

  3. Файлы логов на диске
    В зависимости от настроек и окружения логи могут дополнительно сохраняться в файловую систему, например в /opt/global/globalserver/logs.
    При необходимости следует настроить ротацию (см. раздел «Ротация и хранение логов»).

Описание основных конфигурационных файлов#

1) logback-LoggerContext.xml - системные логи (основной файл)#

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

Характерные элементы (по текущей конфигурации):

  • Типовые аппендеры:

    • STDOUT_DEFAULT - вывод в консоль (ConsoleAppender);

    • OUT_SSH - вывод в SSH-консоль (SshConsoleAppender), если используется;

    • SYSLOG - отправка в syslog (SyslogAppender).

  • Корневой логгер обычно настроен на уровень INFO и вывод в консольные аппендеры.

  • Отдельный логгер для событий ИБ (примерно как InfoSecLogger) может направляться в syslog.

Рекомендация:

  • Для штатной эксплуатации использовать уровень INFO на root, а повышение детализации выполнять точечно (по пакетам/логгерам) через -ext файл.

2) logback-LoggerContext-ext.xml - проектные настройки системных логов#

Назначение: точка расширения для проектных изменений системного логирования.

Обычно в данном файле выполняются следующие действия:

  • добавление файловых аппендеров (в том числе с ротацией);

  • включение/отключение логгеров отдельных подсистем;

  • временное повышение уровня логирования для диагностики.

Примечания:

  • -ext файл должен быть оформлен как <included>...</included>.

3) logback-LoggerContext-session.xml - логи сессий (основной файл)#

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

Особенности:

  • В конфигурации могут присутствовать фильтры (например, EvaluatorFilter), которые ограничивают детализацию по отдельным логгерам, чтобы «по умолчанию» не генерировать избыточный поток сообщений.

  • Как правило, для ключевых логгеров (ru.bitec...) устанавливаются уровни INFO/WARN, что соответствует штатному режиму.

4) logback-LoggerContext-session-ext.xml - проектные настройки логов сессий#

Назначение: точка расширения для изменения логирования сессий.

Типовые сценарии:

  • включение дополнительной диагностики для конкретной подсистемы (операции/скрипты/датастор);

  • вывод сессионных сообщений в отдельный файл;

  • временное включение расширенного SQL-логирования (при необходимости и с учётом объёма).

Пример добавления пользовательского логгера#

Ниже показан пример добавления отдельного логгера и записи его сообщений в отдельный файл с ротацией (пример предназначен для размещения в соответствующем -ext файле).

<included>
    <appender name="CUSTOM_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>/opt/global/globalserver/logs/custom.log</file>

        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>/opt/global/globalserver/logs/custom.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>14</maxHistory>
            <totalSizeCap>2GB</totalSizeCap>
        </rollingPolicy>

        <encoder>
            <pattern>[%-5level] %d{dd-MM-yyyy HH:mm:ss.SSS} [%thread] %logger - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="ru.company.product" level="INFO" additivity="false">
        <appender-ref ref="CUSTOM_FILE"/>
    </logger>
</included>

Уровни логирования#

Уровни Logback (от меньшей детализации к большей):

  • ERROR - ошибки;

  • WARN - предупреждения и ошибки;

  • INFO - штатные события (рекомендуемый уровень для постоянной эксплуатации);

  • DEBUG - расширенная диагностика;

  • TRACE - максимальная детализация;

  • OFF - отключение логирования.

Рекомендации по эксплуатации:

  • Уровень DEBUG/TRACE следует включать только на время диагностики, по конкретным пакетам/логгерам.

  • Для обычной работы достаточно уровня INFO (в большинстве случаев - «максимум» для постоянного режима).

  • При включении DEBUG/TRACE существенно возрастает объём сообщений и нагрузка на I/O; при файловом логировании это может привести к быстрому заполнению диска.

Ротация и хранение логов#

Ротация логов должна быть настроена обязательно. Возможные варианты:

  • ротация средствами Logback (RollingFileAppender с политикой по времени/размеру);

  • ротация средствами ОС (например, logrotate для файлов);

  • ограничение хранения системных логов (journald/rsyslog);

  • в Kubernetes - ротация контейнерных логов на стороне kubelet/контейнерного рантайма.

Содержание