Журналы: что писать и как читать

Зачем это

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

Журнал — это память программы о том, что с ней происходило.

Уровни

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

• Отладочный — подробности, нужные только при разборе. В обычной работе выключен.
• Информационный — важные события: запустились, обработали заказ, отправили письмо.
• Предупреждение — что-то пошло не так, но программа справилась: не отвечал сторонний сервис, попробовали ещё раз.
• Ошибка — операция не выполнена. Пользователь пострадал.
• Критический — программа дальше работать не может.

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

Что писать обязательно

Запуск и остановку. С версией и основными настройками. Первое, что смотрят при разборе: а та ли вообще версия работает.

Ошибки целиком. С цепочкой вызовов, а не только текстом. Сообщение «ошибка при сохранении» без подробностей бесполезно.

Внешние обращения. К базе, к чужим службам: что запросили, сколько ждали, что ответили. Большинство проблем в реальных системах — на границах.

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

Чего писать нельзя

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

Персональных данных. Полных номеров карт, паспортов, адресов. Если нужно связать записи с человеком — пишите идентификатор, а не имя.

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

Как писать полезно

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

Пишите структурно. Не просто текст, а поля: событие, идентификатор, длительность, результат. Такие записи можно фильтровать и считать.

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

Указывайте, что произошло, а не что вы чувствуете. «Не удалось подключиться к базе, попытка 3 из 5» полезно. «Что-то пошло не так» — нет.

Как читать

Начинайте от времени сбоя и идите назад, а не с начала файла.

Ищите первую ошибку, а не последнюю. Часто одна поломка вызывает цепочку следствий, и последнее сообщение — самое бесполезное.

Смотрите на пропуски. Иногда важнее то, чего в журнале нет: если события «начали обработку» есть, а «закончили» нет, ясно, где искать.

Полезные команды для просмотра:

tail -f app.log              смотреть в реальном времени
grep ERROR app.log           только ошибки
grep -A5 -B5 "текст" app.log с окружением

Про ротацию

Журналы растут и однажды забивают диск — это классическая причина ночного падения сервера. Настройте ограничение размера и удаление старых записей сразу, а не когда место кончится.