Главная мысль
Связывайте каждую запись с диагностическим вопросом: какая операция не удалась, какой сервис затронут и когда это произошло? Не записывайте пароли, токены и ненужные персональные данные.
На какой вопрос отвечает журнал?
Журнал приложения сохраняет события, возникающие во время работы программы, с временными метками. Запуск и остановка, результат запроса, непредвиденная ошибка, сбой подключения к внешнему сервису и изменение конфигурации отвечают на разные вопросы при расследовании. Записи ОС и сервера описывают среду, а запись приложения может показать, какую операцию выполняла программа.
Операция
Начало и результат запроса, задания или интеграции.
Ошибка
Исключение, сбой зависимости или отказ, затронувший пользователя.
Изменение
Время и инициатор выпуска, изменения конфигурации или привилегий.
Выбирайте нужные поля события
Единые поля упрощают поиск и сравнение. Обычно полезны время, уровень, название сервиса и среды, тип события, результат, краткое сообщение, идентификатор запроса или трассировки, а при необходимости — безопасный код ошибки. Синхронизируйте часы и явно задавайте часовой пояс, чтобы сравнивать события между сервисами. Не нужно собирать весь возможный контекст для каждой записи.
Время и источник
UTC или явно указанная временная зона; сервис, версия и среда.
Событие и результат
Постоянное имя события, результат и выбранный уровень журнала.
Корреляция
ID запроса и, если есть, trace/span ID; сам идентификатор не должен быть секретом или данными учётной записи.
Используйте уровни последовательно
Уровень показывает срочность внимания, но названия и точный смысл зависят от библиотеки журналирования. Зафиксируйте короткий словарь команды: DEBUG — дополнительные сведения при разработке, INFO — штатный этап работы, WARN — неожиданная, но пока переносимая ситуация, ERROR — сбой операции, CRITICAL/FATAL — тяжёлый отказ компонента. Если одна проблема в разных сервисах получает разные уровни, правила оповещения становятся менее надёжными.
DEBUG / TRACE
Подробная диагностика; в рабочей среде ограничивайте объём и чувствительные поля.
INFO / WARN
Описывают штатную работу и условия, за которыми нужно следить, но которые ещё не являются отказом.
ERROR / CRITICAL
Обосновывают эскалацию из-за нарушения функции или более широкого воздействия.
Делайте структурированные записи понятными
Структурированный формат, например JSON, представляет каждое событие с постоянными ключами. Это позволяет искать текст и фильтровать или связывать записи по полям. Сохраняйте одинаковые имена и типы полей между сервисами. Пишите краткое сообщение, отдельно указывайте тип ошибки и контекст операции; при необходимости сохраняйте полный стек вызовов. JSONL — распространённый формат, в котором на строку приходится один JSON-объект.
{"timestamp":"2026-10-09T08:30:00Z","level":"ERROR","service":"billing-api","event":"payment_authorization_failed","request_id":"req-7f21","error_code":"upstream_timeout"}
Не храните секреты и лишние персональные данные
Текст запроса, параметры URL, cookie, токены, пароли и полные данные пользователя могут случайно попасть в журнал. Удаляйте или маскируйте чувствительные значения на входе и собирайте только поля, нужные для цели. Контролируйте доступ при передаче и хранении, ограничивайте права и сохраняйте историю изменений.
Нужно ли записывать все события?
Нет. Выбирайте важные операции и вопросы расследования: избыточный шум может скрыть полезные записи.
Одинаковы ли уровни во всех системах?
Нет. Библиотеки и платформы различаются; документируйте свою семантику и правила сопоставления.