Логирование backend-приложений¶

Требования этого документа применяются к диагностическим логам backend-приложений, API, worker-процессов, consumer-процессов и data pipelines. Аудит-логи регулируются документом audit-logging.md. Уровни обязательности определены в корневом README.md.

OBS-LOG-001. Структурированный однострочный формат¶

Уровень: MUST

Применяется к: всем диагностическим логам приложения

Каждая запись должна быть самостоятельным JSON-объектом в кодировке UTF-8 и занимать ровно одну строку. Переносы строк внутри значений должны экранироваться. Текстовые префиксы, цветовые коды и смешение JSON с неструктурированным текстом запрещены.

Обоснование¶

Vector должен однозначно разделять поток на записи без многострочного парсинга и эвристик.

Проверка¶

проверка каждой строки стандартного вывода JSON-парсером;
интеграционный тест сбора логов через Vector;
проверка отключения цветного и текстового формата в production-конфигурации.

Исключения¶

Не допускаются для логов приложения. Вывод среды выполнения до инициализации приложения должен нормализоваться на уровне Vector либо учитываться отдельным источником.

OBS-LOG-002. Единственный транспорт логов приложения¶

Уровень: MUST

Применяется к: диагностическим логам во всех средах выполнения приложения

Приложение должно записывать логи только в stdout и stderr. Доставка выполняется по маршруту приложение → stdout/stderr → Vector → OpenObserve. Прямая отправка логов из приложения в OpenObserve, запись в локальные файлы и использование сетевого logging appender запрещены.

Обоснование¶

Единый транспорт отделяет бизнес-приложение от платформы хранения и предотвращает потерю данных из-за нескольких конкурирующих каналов.

Проверка¶

review конфигурации логирования и зависимостей;
проверка отсутствия файловых и сетевых обработчиков логов;
интеграционная проверка появления записи в OpenObserve через Vector.

Исключения¶

Только через утверждённый ADR для среды, в которой stdout и stderr технически недоступны.

OBS-LOG-003. Обязательные поля записи¶

Уровень: MUST

Применяется к: каждой записи лога

Запись должна содержать:

timestamp в UTC в формате RFC 3339 с долями секунды;
severity_text со значением TRACE, DEBUG, INFO, WARN, ERROR или FATAL;
severity_number по модели OpenTelemetry;
message с кратким описанием события;
service.name;
service.version;
deployment.environment.name;
event.name как стабильный машинно-обрабатываемый идентификатор типа события.

severity_number должен соответствовать severity_text: TRACE — 1–4, DEBUG — 5–8, INFO — 9–12, WARN — 13–16, ERROR — 17–20, FATAL — 21–24.

Обязательное строковое поле не должно быть пустым или состоять только из пробельных символов.

Имена и семантика стандартных полей должны соответствовать зафиксированной проектом версии OpenTelemetry Semantic Conventions.

Обоснование¶

Единая схема обеспечивает поиск, маршрутизацию, агрегацию и сопоставление записей разных сервисов.

Проверка¶

автоматическая проверка JSON Schema или эквивалентным валидатором;
негативный тест несовпадающих severity_text и severity_number;
запрос в OpenObserve на отсутствие обязательных полей;
contract-тест конфигурации логгера.

Исключения¶

Для сообщений среды выполнения, которые приложение не контролирует, допускается обогащение отсутствующими resource-атрибутами в Vector.

OBS-LOG-004. Корреляция с операцией и трассой¶

Уровень: MUST

Применяется к: логам внутри входящего запроса, сообщения, job или другой отслеживаемой операции

Запись должна содержать trace_id и span_id активного span. trace_id должен быть 32-значным, а span_id — 16-значным lowercase hexadecimal значением без префикса.

Если протокол или локальный контракт использует request_id либо correlation_id, соответствующее значение также должно присутствовать. request_id идентифицирует один запрос или сообщение, а correlation_id — связанную бизнес-операцию, которая может включать несколько запросов. Эти идентификаторы не должны подменять друг друга или trace_id.

Идентификаторы должны передаваться через контекст выполнения, а не формироваться заново в каждой записи.

Если активного span нет, поля trace_id и span_id должны отсутствовать; фиктивные, пустые и нулевые значения запрещены.

Обоснование¶

Корреляция позволяет перейти от записи лога к распределённой трассе и восстановить ход одной операции.

Проверка¶

интеграционный тест сквозного запроса и фоновой обработки;
сопоставление идентификаторов в логах и OpenObserve;
тест сохранения контекста при асинхронном и конкурентном выполнении.

Исключения¶

Не допускаются для кода, выполняемого внутри активного span.

OBS-LOG-005. Контекст события¶

Уровень: MUST

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

Контекст должен передаваться отдельными типизированными полями, а не встраиваться в message. Имена полей должны быть стабильными. Идентификаторы сущностей допускаются; полные тела запросов, ответов, сообщений и произвольные объекты по умолчанию логироваться не должны.

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

Обоснование¶

Структурированный контекст поддерживает точный поиск и ограничивает объём, стоимость и риск утечки данных.

Проверка¶

code review вызовов логгера;
проверка схемы и маппинга полей в OpenObserve;
тесты наиболее важных событий.

Исключения¶

Диагностическое логирование тела допускается только в изолированной непроизводственной среде, с синтетическими данными и явным ограничением объёма.

OBS-LOG-006. Защита чувствительных данных¶

Уровень: MUST

Применяется к: всем диагностическим логам и всем средам

Запрещено логировать секреты, пароли, токены, cookies, заголовки авторизации, приватные ключи, полные платёжные данные и персональные данные без утверждённого маскирования. Запрет распространяется на message, структурированные поля, URL, stack trace, тела запросов и ответов.

Фильтрация должна выполняться до записи в stdout или stderr. Фильтрация в Vector может использоваться только как дополнительный защитный слой.

Обоснование¶

После попадания в поток сбора чувствительные данные копируются, индексируются и становятся доступны более широкому кругу систем и пользователей.

Проверка¶

автоматические тесты редактирования чувствительных полей;
security review конфигурации логирования;
контролируемое сканирование OpenObserve на известные шаблоны секретов.

Исключения¶

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

OBS-LOG-007. Семантика уровней¶

Уровень: MUST

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

Уровни должны использоваться последовательно:

TRACE — детальная трассировка локального выполнения;
DEBUG — диагностическая информация для разработки и расследования;
INFO — ожидаемые значимые изменения состояния и жизненного цикла;
WARN — восстановимый сбой или аномальное состояние, требующее внимания;
ERROR — неуспешная операция, требующая расследования;
FATAL — невозможность продолжать работу процесса.

Ожидаемое отклонение клиентского ввода и штатный бизнес-результат не должны автоматически регистрироваться как ERROR.

Обоснование¶

Стабильная семантика уровней обеспечивает полезные оповещения и управляемое соотношение сигнала к шуму.

Проверка¶

code review;
проверка распределения уровней в OpenObserve;
тесты обработки типовых ошибок.

Исключения¶

Не допускаются. Дополнительные уровни библиотеки должны быть однозначно отображены на указанную шкалу.

OBS-LOG-008. Управление объёмом и отказами¶

Уровень: MUST

Применяется к: конфигурации логирования приложения

Production-уровень по умолчанию должен быть не подробнее INFO. Изменение уровня во время расследования должно быть ограничено по среде и времени. Высокочастотные повторяющиеся события должны ограничиваться агрегацией, sampling или rate limit без потери сообщений о существенных ошибках.

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

Обоснование¶

Неограниченный поток логов способен нарушить работу приложения и платформы наблюдаемости.

Проверка¶

нагрузочный тест;
тест недоступности или замедления получателя;
review лимитов буферов, sampling и временного изменения уровня.

Исключения¶

События аудита регулируются отдельным документом и не должны отбрасываться по правилам диагностического sampling.