Поля события в zerolog: Str, Int, Err, Dur

Поле в zerolog — это метод события, который дописывает в буфер готовые JSON-байты: ключ с кавычками, двоеточие и значение в правильном для типа виде. Тип известен на этапе компиляции — метод Int не может принять строку, — поэтому сериализация обходится без рефлексии и без упаковки в interface{}: число ложится в JSON числом, булево значение словами true или false, строка строкой. Порядок ключей в записи равен порядку вызовов: если вам важно, как поля выглядят глазами или в diff-ах, просто вызывайте методы в нужном порядке. Сообщение живёт отдельно от полей — оно дописывается при финализации и оказывается последним ключом. Для систем сбора типизированные поля — главный аргумент: Elasticsearch и ClickHouse получают числовые значения числами и умеют по ним агрегировать, тогда как строка «items: 3» внутри message остаётся мусором, из которого данные приходится доставать регуляркой. Проверить всё это проще всего локально: zerolog в песочнице сайта не исполняется, она показывает тематическую программу на чистом Go, а библиотека ждёт вас в терминале. Цепочка при этом не создаёт объектов: каждый метод поля дописывает байты и возвращает тот же указатель события, поэтому десять полей стоят структурно столько же, сколько одно. Из типизации следует и безопасность рефакторинга: переименование ключа компилятор не заметит — это просто строка, — а вот смену типа значения поймает сразу. И автодополнение работает за типизацию: редактор предлагает ровно те методы полей, что подходят значению, — опечатка в имени метода ловится до запуска, а не на ревью вывода.

Метод Dur принимает time.Duration и по умолчанию пишет значение числом миллисекунд: 317time.Millisecond превращается в "elapsed":317. За единицу отвечает глобальная переменная zerolog.DurationFieldUnit — по умолчанию time.Millisecond; если вашим дашбордам нужны секунды, поставьте её равной time.Second при старте, а DurationFieldInteger=true отрежет дробную часть у целых значений. Почему за дефолт взяты миллисекунды: это единица латентностей — HTTP-запросы, запросы к базе и кэшу живут в десятках и сотнях миллисекунд, и именно в этих единицах построены графики p50 и p99. Дробные доли миллисекунды Dur тоже пишет: 500time.Microsecond даст 0.5. Если дроби не нужны, DurationFieldInteger=true пишет целые миллисекунды без хвоста — для индексов это дешевле. Ошибка новичка — логировать длительность строкой через .Str("elapsed", d.String()): получившаяся «317ms» не сортируется и не агрегируется, а число из миллисекунд — сразу готовая метрика в системе сбора. Канонический замер живёт рядом с операцией: start := time.Now() на входе, дальше Dur("elapsed", time.Since(start)) в записи — поле показывает полную жизнь запроса, а замерять куски удобнее отдельными полями: db_ms и render_ms расскажут больше, чем один elapsed, который придётся объяснять.

Метод Err — самый частый гость в боевом коде. Вызов .Err(err) кладёт в запись ключ error со значением err.Error() — текстом ошибки. Ключевое поведение: если err равен nil, ключ не добавится вовсе — цепочка просто продолжится без поля, поэтому не надо строить if err != nil вокруг логов «на всякий случай». Ошибка в поле — это данные: система сбора строит по error частоты, группирует тексты, ищет всплеск одинаковых провалов, тогда как ошибка, вклеенная в message, остаётся текстом без индекса. Родственники Err закрывают остальные случаи: AnErr кладёт ошибку, умеющую сериализоваться объектом — метод MarshalZerologObject у ошибок с деталями; Errs пишет слайс ошибок одним полем; Stack() добавляет к ошибке стек, если настроен ErrorStackMarshaler — вся механика стека в уроке про логирование ошибок. Рабочее правило: каждый вызов Error несёт .Err(err), иначе запись объясняет, что провалилось, но не объясняет почему. Обёрнутые через %w ошибки Err печатает целиком: err.Error() склеивает тексты цепочки через двоеточие — читаемо, но не индексируемо по частям, поэтому детали для графиков лучше выводить отдельными полями. Если у ошибки есть данные — код ответа шлюза, идентификатор транзакции, — им место рядом, самостоятельными ключами.

Метод Any принимает interface{} и умеет закодировать почти всё — но делает это рефлексией в рантайме, а рефлексия стоит: аллокации и десятки раз более медленный путь, чем у типизированных полей. Это не повод запретить Any, а повод понимать, где он уместен: разовые записи со сложными структурами, редкие пути вроде отчётов о панике, прототипы, где сначала смотрят на данные, а потом размечают поля. На горячем пути — в обработчике HTTP или внутреннем цикле — Any заменяется типизированными методами, а вложенные структуры пишутся Dict и Array: они собирают подобъекты и списки без выхода в рефлексию. Средняя позиция — поля, которые пишутся только при условии: zerolog позволяет собирать событие по частям, и этот приём с bool-хелперами разбирается в уроке про условные поля. Каждая аллокация в логе на высоких RPS — аллокация, которая досталась логам, а не бизнесу: тема целиком раскрывается в уроке про производительность. Типичный примиряющий сценарий: Any живёт в обработчике паники и в дампе конфига при старте — два места на весь сервис, оба не на горячем пути. Как только такой вызов переезжает в хендлер запроса, он становится долгом: каждое событие платит рефлексией за данные, у которых были имя и тип ещё на этапе компиляции.

Следующий урок — Logger.With: поля, которые есть у каждого события, от имени модуля до request_id запроса. Затем — условные поля: собирать событие по частям и платить только за нужное. Для ошибок глубже — урок про логирование ошибок со стеком и обёртками, а про то, как поля едут в Loki и ELK, расскажет урок про структуру JSON.