Первый логгер: NewProduction и NewDevelopment

Начните с пустого модуля: mkdir demo, cd demo, затем go mod init demo. Дальше — go get go.uber.org/zap: команда подтянет последний релиз ветки v1 и пропишет его в go.mod. На этом установка закончена — zap не требует инициализации, конфигов и внешних сервисов, логгер создаётся одним вызовом конструктора. Одна оговорка о формате курса: песочница сайта исполняет только чистый Go без сторонних модулей, поэтому zap-код здесь не запускается — держите терминал под рукой. Понимание проверяют quiz, predict, fill и order-задачи, а запускать примеры вы будете локально, где zap честно печатает свои строки в stdout. Это, кстати, лучший способ учиться: разница между двумя пресетами, о которой мы будем говорить, видна глазами за секунду.

Каждая запись production-пресета — однострочный JSON. level — серьёзность строчными: info, error. ts — время в секундах от эпохи, дробное число: так его дешевле сериализовать и хранить, а человеко-читаемый формат отдаётся интерфейсу, который показывает логи. caller — файл и строка, откуда произошёл вызов: без него «кто это залогировал» превращается в детектив. msg — ваше сообщение, короткая фраза-событие. Дальше идут ваши поля в том порядке, как вы их передали: port, order_id, error. На уровне Error и выше пресет добавит ключ stacktrace со стеком горутины — сразу видно, где именно случилось. Ещё в production-пресете спрятано сэмплирование: после ста одинаковых записей в секунду zap начинает прореживать поток, чтобы сервис при шторме ошибок не утонул в собственных логах — этой механике посвящён отдельный урок.

NewDevelopment — пресет для терминала разработчика. Энкодер console пишет запись колонками: время в ISO-формате, уровень заглавными, место в коде, сообщение и объект с полями — глаз цепляет это мгновенно, без парсера в голове. Уровень по умолчанию — Debug: вы видите всё, включая отладочные записи, которые в production были бы отсечены. Стек-трейсы прилагаются раньше — с Warn, а не с Error: на машине разработчика лишний стек помогает поймать источник, а в проде он шумел бы в каждой второй записи. Режим development меняет и поведение DPanic — уровня, который паникует только в этом режиме; его разбор — в уроке про уровни логов. Итого: разработка — NewDevelopment, прод — NewProduction, и это не два конкурирующих вкуса, а два режима одного и того же логгера. Обратная конфигурация — production-пресет на ноутбуке — тоже встречается и заканчивается всегда одинаково: Debug-записи молчат, и половина отладки не работает; вместо колонок — однострочный JSON, который человек парсит глазами; стек-трейс на Warn не приходит, хотя именно его хотелось увидеть. Со стороны выглядит как «логгер сломался», на деле — просто не тот пресет.

Пресет — не вкусовщина, а свойство окружения. Локальная машина и тестовый стенд живут на NewDevelopment: человеко-читаемый вывод, Debug включён, стеки с Warn. Production — NewProduction: JSON для систем сбора, Info по умолчанию, сэмплирование. Правильный сервис выбирает пресет при старте, а не правкой кода между деплоями. Классика — переменная окружения: APP_ENV=production go run . — и логгер соберётся нужным. Если пресетов нужно больше — staging со своим уровнем, запись в файл вместо stdout, — это уже не выбор между двумя функциями, а zap.Config: полная конфигурация, которую можно описать в YAML и менять без пересборки; ей посвящён отдельный урок, а пока двух готовых пресетов хватает с головой. Законное исключение из правила — утилиты командной строки. Для CLI пользователь — человек в терминале, систем сбора нет, и JSON-простыня в stdout ломает пайплайн: demo | jq перестаёт работать, если между данными въелись логи. Для таких программ NewDevelopment остаётся даже в «проде»: релиз утилиты — тот же бинарник на машине пользователя, только без терминала разработчика. Что будет, если оставить в CLI production-пресет: каждая ошибка печатается JSON-строкой со стеком на десяток строк, пользователь видит {"level":"error"...} вместо человеческого объяснения, а в issues заводится вопрос «что это значит». Пресет — это интерфейс, и для терминала этим интерфейсом остаётся console-формат; к разделению потоков — данные в stdout, диагностика в stderr — вернёмся в уроке про приёмники.

Тип *zap.Logger — иммутабельная структура: логгер хранит ядро (куда и как писать), уровень и набор опций вроде включённых вызовов. Иммутабельность даёт удобное свойство: логгер можно передавать по значению, держать в нескольких структурах и не бояться, что кто-то изменит его уровень под вами — With и Named не мутируют приёмник, а возвращают новый логгер с прицепленными полями или именем. Из этого следуют две практики. Первая: конструируйте логгер один раз в main и прокидывайте вниз — копирование дешёвое, пересоздание бессмысленное. Вторая: nil-логгер недопустим — если по пути зависимостей вместо настоящего логгера приехал nil, первая же запись упадёт с паникой; в тестах вместо nil подставляйте zap.NewNop() — заглушку, которая глотает записи. Кстати, именно иммутабельность делает безопасным выбор пресета по окружению из прошлого раздела: другой пресет — это другой логгер, а не перенастроенный старый.

Первая — потерянный Sync: программа пишет в файл, хвост записей пропадает при выходе, и виноватым назначают диск. Вторая — затенение логгера: logger, _ := zap.NewProduction() внутри ветки if создаёт локальную переменную, внешняя остаётся nil, и программа падает с паникой при первом же вызове — компилятор такое не ловит, а рантайм ловит редко и громко. Третья — логгер как глобальная переменная, присваиваемая из каждого пакета: настройки живут в трёх местах, тесты перезаписывают их друг у друга. Лечится просто: логгер рождается в main один раз и уезжает вниз через зависимости — структуру сервиса или параметр конструктора. Как безопасно пользоваться глобальным логгером, если без него никак, покажем в уроке про ReplaceGlobals — там же объясним, почему библиотечному коду он всё равно не нужен.

msg — короткая фраза-событие: что произошло, без данных внутри. «order created» — хорошо; «order A-1024 for user 42 created in 45ms» — плохо: данные в сообщении недоступны фильтрам, вы только что откатились в grep-мир из первого урока. Правило: факт — в msg, детали — в поля. «payment declined» плюс zap.String с причиной и zap.Int с суммой — запись и ищется, и считается, а не только читается. Из этого следует и дисциплина формулировок: одни и те же события во всём сервисе пишутся одинаково, иначе поиск по msg превращается в перечисление синонимов. Данные, которые нельзя утекать — пароли, номера карт, токены, — в лог не пишут вовсе: логи читает больше людей, чем кажется, и живут они дольше, чем хочется. zap честно напечатает всё, что вы ему отдали, — маскируйте чувствительное до вызова, а не после.

Следующий урок — уровни логов: что значит каждый из семи, почему Fatal — это os.Exit(1) и когда Warn, а когда Error. Потом — поля: zap.String, zap.Duration и отчего zap.Any дорогой. Если многословность конструкторов давит, загляните в урок про SugaredLogger — упрощённый интерфейс с Infow и парами ключ-значение. Карта курса — на его странице, а пример zap logger-а из этого урока — лучший стартовый шаблон для ваших программ.