Provision
—— XP

Как писать журналы, по которым можно искать

теория~7 минут+200 XP

«Вчера продали много гвоздей» и «12.09, гвозди 100 мм, 4 кг, 920 ₽, кассир Петрова» — обе записи в амбарной книге правдивы, но посчитать выручку за месяц можно только по второй. С журналами программ то же самое, и урок о том, какая строка журнала полезна при разборе аварии и как попросить у разработчиков именно такую. Пишут журнал разработчики в коде, но DevOps настраивает журналы nginx, баз и прочих готовых программ, и он же первым видит, что по журналу ничего нельзя найти.

Ответ современных систем — структурированный журнал: каждая строка состоит не из фразы, а из отдельных полей — время, уровень, событие, код ответа, длительность. Чаще всего каждая строка — маленький JSON-объект. Такой формат стал стандартом вместе с контейнерами: когда журналы читает не человек глазами, а хранилище запросами, поля важнее красивых предложений. Чего структура не даёт: она не сделает полезной строку, в которой нет нужных сведений.

Строка для человека и строка для поиска

Вот как обычно выглядит журнал, написанный «для себя»:

плохо
2026-10-01 14:30:07 Пользователь 8123 купил товар 44 за 2499.00 руб.

Человек прочитает её без труда. Хранилище — нет: чтобы найти покупки дороже тысячи, придётся писать регулярное выражение, а стоит разработчику переформулировать фразу, все сохранённые запросы сломаются. Та же запись в структурированном виде:

хорошо
{"time":"2026-10-01T14:30:07Z","level":"info","event":"purchase",
 "user_id":8123,"item_id":44,"price_cents":249900,
 "request_id":"9f4c2a7e1b3d8055"}

Разберём, что изменилось. event — короткое стабильное имя события вместо фразы: по нему можно искать годами. Числа записаны числами, цена — целыми копейками, без валюты в строке, поэтому их можно сравнивать и складывать. request_id связывает строку с остальным путём запроса. Время — в зоне UTC, с буквой Z на конце: иначе строки двух серверов в разных поясах не сопоставить.

Loki умеет разбирать такую строку на поля одним словом в запросе — это будет в уроке про LogQL. Кроме формы у каждой строки есть важность.

Уровни

Почти любая программа помечает строки уровнем. Полезных в работе четыре.

  ERROR  человек обязан отреагировать: база не ответила, платёж потерян
  WARN   что-то не так, но обошлись: повторили запрос, и он прошёл
  INFO   вехи нормальной работы: старт, обработан заказ
  DEBUG  подробности для разработки, в проде выключен

Главное правило: ERROR — только то, из-за чего кто-то должен встать ночью. Неверный пароль пользователя, ссылка на несуществующую страницу, неправильно заполненная форма — это нормальная работа сервиса, а не его ошибка. Если писать их в ERROR, уровень перестанет что-либо значить, и настоящая авария утонет в тысячах ложных.

Второе правило — DEBUG в проде выключен. Он легко даёт в десять раз больше строк, а платить за их хранение придётся тебе.

Идентификатор запроса

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

В nginx для этого есть готовая переменная $request_id — случайная строка на каждый запрос. Её передают приложению заголовком и пишут в свой журнал:

фрагмент nginx.conf
proxy_set_header X-Request-Id $request_id;
log_format main_id '$remote_addr "$request" $status '
                   '$request_time req=$request_id';
access_log /var/log/nginx/access.log main_id;

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

Если журнал nginx нужен сразу в JSON, у log_format есть параметр escape=json. Готовые форматы есть в документации nginx; сочинять свой с нуля не нужно.

Чего в журнал не пишут

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

Самый частый способ протечь — записать в журнал запрос целиком, со всеми заголовками: туда попадает заголовок Authorization с токеном. Если видишь такое в журнале — это не мелочь, а повод сменить токен и попросить разработчиков вычищать заголовки перед записью.

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

Размер журналов на машине

Пока журналы не уехали в Loki, они лежат на диске машины: Docker по умолчанию копит вывод каждого контейнера в файл без ограничения размера. Болтливая служба за несколько недель заполняет им весь диск, и тогда падает уже всё остальное, включая базу.

Лечится тремя строками в описании службы:

compose.yaml, в описании службы
    logging:
      options:
        max-size: "10m"
        max-file: "3"

max-size — размер одного файла журнала, max-file — сколько файлов хранить. Когда файл дорастает до десяти мегабайт, Docker начинает новый, а самый старый из трёх удаляет. На машине остаётся не больше тридцати мегабайт на контейнер, а вся история при этом лежит в Loki.

У самого Loki по умолчанию строки не удаляются никогда. Срок хранения задают в его конфиге, когда стенд становится рабочим; обычная раскладка — две недели для журналов приложения и месяц для журналов доступа.

Словарь урока

Структурированный журнал
Журнал из полей вместо фраз. Обычно каждая строка — JSON-объект. ↩ к тексту
Уровень
Пометка важности строки: ERROR, WARN, INFO, DEBUG. ↩ к тексту
Идентификатор запроса
Случайная строка, общая для всех записей одного запроса во всех службах.
UTC
Всемирное время без часового пояса. В журналах пишут его, чтобы строки разных серверов сходились. ↩ к тексту
max-size
Настройка Docker: предельный размер файла журнала контейнера на диске.

Что спросят на собеседовании

  • Что такое структурированное логирование?
    Запись событий полями, обычно в JSON: время, уровень, событие, идентификатор запроса, числовые значения. По полям можно фильтровать и считать без регулярных выражений.
  • Что должно попадать в ERROR?
    Только то, на что обязан отреагировать человек. Неверный ввод пользователя — не ошибка сервиса.
  • Как связать строки одного запроса из разных сервисов?
    Идентификатором запроса: его заводит первая служба, например nginx через $request_id, передаёт заголовком X-Request-Id, и все пишут его в свои строки.

Что дальше

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

Проверь себя+200 XPдве попытки
1
Структура
Чем строка {«event»:«purchase»,«price»:2499} лучше строки «Пользователь купил товар за 2499»?
2
Уровни
Пользователь ввёл неверный пароль. Какой это уровень?
3
Идентификатор запроса
Зачем в каждой строке журнала идентификатор запроса?
4
Чего не писать
Что из этого нельзя писать в журнал?
5
Размер
Что делают настройки max-size и max-file в разделе logging службы Compose?
ответь на все вопросы, чтобы проверить

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.