JSON или console: выбор энкодера

Запись лога в zap проходит два этапа: сначала формируется entry — время, уровень, сообщение, место вызова — и к нему прикладываются ваши поля; потом энкодер сериализует всё это в байты. Именно энкодер решает, будет ли время дробными секундами от эпохи, окажется ли уровень строчными или заглавными и куда денутся поля. Встроенных энкодера два: json — однострочный JSON-объект на запись, и console — колонки через табуляцию для терминала. Оба настраиваются через zapcore.EncoderConfig — набор ключей и правил сериализации, который мы ниже только покажем, а полностью разберём в уроке про конфиг и отдельно в zapcore, где энкодеры собираются руками. Важно понимать: пресеты NewProduction и NewDevelopment — это не два разных логгера, а два готовых набора настроек: уровень, энкодер и его конфиг. Поменяли энкодер — поменялся формат вывода при неизменных полях, уровнях и приёмниках.

console-вывод устроен просто: время, уровень, имя логгера если есть, место в коде, сообщение — и JSON-объект с полями в хвосте, всё через табуляцию. Ключи из EncoderConfig — timeKey, levelKey и прочие — на колонки не влияют: console-энкодер печатает части записи по позициям, а ключи потратил бы только JSON. Поэтому в development-пресете ключи названы коротко — T, L, M — и это не влияет на вывод: колонки те же. Если часть записи не нужна, ей просто оставляют пустой ключ — колонка исчезает. Стек-трейс печатается отдельным блоком после строки: консольные записи остаются построчными, а трейс уезжает ниже — удобно в терминале, терпимо в файле. Разделитель меняется опцией ConsoleSeparator: таб по умолчанию, но можно поставить « | » для тех, кто читает логи в редакторе с узкой колонкой. Если логгер получил имя через Named, оно встаёт отдельной колонкой между уровнем и caller-ом — в JSON то же самое лежит под ключом logger. Мелочь, а глаз экономит.

JSON-логирование — это контракт: каждая запись самодостаточна и парсится без знания о сервисе, который её написал. Система сбора разворачивает объект в поля, и любое поле становится фильтром, графиком или алертом — ровно то, о чём был первый урок про структурные логи. jq читает поток как таблицу: select по уровню, group по коду ошибки, счётчики за минуту — всё без регулярок. Числа остаются числами: duration 0.045 сортируется и агрегируется, а не превращается в строку «45ms». Кавычки и переводы строк внутри значений экранируются — запись не развалится на две строки посреди поля, что для построчных парсеров вопроса жизни и смерти. Цена тоже есть: JSON многословнее консоли процентов на двадцать-тридцать на той же записи, и человеком читается хуже. Но прод — не место для чтения глазами: там логи фильтруются запросами, и многословность окупается за неделю. Последнее преимущество скромное, но приятное: JSON-логи версионируются схемой — добавили поле, обновили схему в сборщике, и старые записи продолжают читаться по-старому без единой правки парсеров.

Разница между форматами обнажается на неудобных значениях. Возьмите стек-трейс из ошибки: это сотни строк одним куском. JSON-энкодер экранирует управляющие символы — перевод строки становится \n внутри одной строки, и запись остаётся однострочной: парсер извлечёт трейс и покажет его с переносами в интерфейсе. console-энкодер трейс печатает отдельным блоком после колонок: в терминале это красиво, в файле записи перестают быть построчными, и наивный парсер склеит пятьдесят строк трейса в чужую запись. То же с кавычками и табуляцией внутри значений: JSON гарантирует целостность, колонки — нет. Отсюда практическое правило для смешанных систем: в файл, который будет парситься, — только JSON; console живёт либо в терминале, либо в файле, который читают глазами. И проверьте это на своей инфраструктуре: скормите сборщику обе записи из урока, одну — с трейсом, и посмотрите, что он сделал с каждой. Десять минут теста экономят неделю разбора, почему половина записей помечена битой.

Правило, которое у меня прижилось: console — везде, где логи читает человек в момент написания кода; JSON — везде, где логи читает машина или другой человек позже. Локальная машина — консоль. Тесты — console, чтобы падение прогона показывало читаемый контекст. Прод — JSON, без вариантов. Спорные места: staging, на котором бывает и то и другое — демо для продукта требует колонок, а сбор логов уже настроен; здесь выручает мультиплекс из следующего раздела — один логгер, два приёмника, каждый со своим форматом. Контейнеры — отдельный вопрос: docker logs отдаёт сырой stdout, и на локальном контейнере консольный вывод приятнее; но если stdout контейнера уезжает в сборщик, внутри должен быть JSON, иначе сборщик получает колонки и страдает. Спор о том, что удобнее, я закрываю вопросом: кто будет читать эти логи через месяц — вы сейчас или запрос к системе сбора? Для первого — консоль, для второго — JSON, и это почти всегда решает спор без обид. Отдельный кейс — миграция со старого текстового формата: включите JSON у нового логгера заранее, на тестовом стенде, и дайте сборщику месяц на параллельный приём. Формат — самая дешёвая часть переезда на zap: поля переносятся один в один, а старые парсеры текста просто выключаются.

zapcore.EncoderConfig — набор настроек, из которых энкодер собирает запись. Ключи решают, какие имена получат части записи: messageKey — ключ сообщения в JSON (в проде msg), timeKey (ts), levelKey (level), callerKey (caller), stacktraceKey (stacktrace). Правила сериализации решают, как эти части выглядят: encodeTime — время эпохой или ISO-строкой (EpochTimeEncoder против ISO8601TimeEncoder), encodeLevel — строчными или заглавными (LowercaseLevelEncoder против CapitalLevelEncoder), encodeDuration — длительность числом секунд или строкой «45ms», encodeCaller — полный путь или короткий файл:строка. Пустой ключ — часть записи пропускается: не хотите caller в JSON — оставьте callerKey пустым. Полный обход полей EncoderConfig с примерами — в уроке про zap.Config; пресеты, кстати, это просто предзаполненные EncoderConfig плюс уровень и приёмник. Меняя эти настройки, вы меняете словарь логов — а он, как мы обсуждали в уроке про поля, контракт на годы, поэтому правки конфига не делаются между делом.

Формат выбран — следующий вопрос, куда физически уезжают записи: приёмники, файлы и мультиплексирование — тема восьмого урока. А конфигурация целиком — уровень, энкодер, приёмники, стартовые поля в одной структуре — разбирается в уроке про zap.Config. Карта курса — на его странице: после энкодеров начинается инженерия вывода — файлы, ротация и сэмплирование.