Перейти к основному содержанию
`Ctrl`+`K`

# Общий обзор

Логирование в проекте выполняется с использованием 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/контейнерного рантайма.