Условные поля и Any

Каждый метод уровня в zerolog возвращает *zerolog.Event — мутируемый аккумулятор записи. Цепочка из одного урока про поля — это просто короткая форма; ничто не мешает разбить её на шаги и пропускать шаги по условию. Паттерн условного логирования выглядит так: evt := logger.Info(), затем evt.Str("user", id), затем сколько угодно проверок с evt.Str или evt.Err внутри if, и в конце — evt.Msg(...), который завершает сборку и пишет запись. До Msg ничего никуда не уходит: буфер события живёт в памяти, порядок полей в JSON остаётся порядком вызовов, а пропущенные шаги не оставляют в записи следов. На практике паттерн применяется шире, чем кажется: условным бывает не только поле, но и уровень — единая точка сборки позволяет выбрать Info или Warn до добавления полей, и каркас при этом один. Часть условий zerolog делает сам: Err и AnErr молча пропускают nil — запись с ошибкой и без неё собирается одной и той же цепочкой, и условие писать не нужно. Errs устроен иначе: он пишет слайс ошибок массивом под заданным ключом, и nil-элементы внутри этого массива сериализуются как null. Поэтому для одиночной необязательной ошибки Err и AnErr остаются главным инструментом, а Errs берут, когда ошибок действительно несколько и их состав известен заранее. Для всего остального — строки, числа, флаги — условие на поле пишется обычным if, и это честная плата за то, что в записи оказываются только существующие значения. Различие между типизированными методами и универсальным Any, который часто тянется сюда же, — тема следующего раздела; база из урока про поля события предполагается знакомой.

Метод zerolog any — обёртка над Interface: он принимает значение произвольного типа и маршалит его рефлексией, через тот же json.Marshal, что и стандартная библиотека. Отсюда цена: типизированные поля вроде Str и Int дописывают в буфер готовые байты без единой аллокации, а Any проходит по значению рефлексией и аллоцирует — на порядок и больше, в зависимости от глубины структуры. Есть и обходной путь: если тип реализует интерфейс LogObjectMarshaler с методом MarshalZerologObject, Any направит его в Object, который пишет поля без рефлексии. Когда Any оправдан: разовые дампы на Debug — слепок конфига, содержимое сообщения из очереди, паника с картой состояния. Когда нет: горячий путь, где типы полей известны на этапе компиляции — там Str, Int и Float64 и дешевле, и честнее по типам в системе сбора. Отдельный случай — значение уже сериализовано где-то ещё: RawJSON принимает байты готового JSON и дописывает их в запись как есть, без повторного маршалинга; валидировать байты приходится вам — zerolog вставит их в запись доверчиво. Оценка цены на конкретных числах — тема урока про производительность, там Any и типизированные поля встают в один бенчмарк.

Bool(key, b) дописывает в запись JSON-значение true или false — тип события в системе сбора станет булевым, и фильтр admin=true отработает без приведений. Вокруг этого метода выросла маленькая дисциплина, потому что флаги логируют тремя разными способами. Первый — Bool: честно, типизировано, фильтруется везде. Второй — строка: Str("admin", "1") или "yes" — тогда каждый потребитель описывает своё преобразование, а админство внезапно оказывается и строкой, и числом в разных местах логов. Третий — числовые маяки вроде Int("admin", 1): они конфликтуют с настоящими счётчиками, у которых 0 и 1 — значения, а не флаги. Я за Bool везде, где значение действительно бинарное, и за именование без отрицаний: флаг not_admin=true читается на инциденте как ловушка, admin=false — мгновенно. Хелперы есть и на контексте: Context.Bool задаёт флаг всем событиям логгера — например, dry_run для режима примерки, — а Bools добавляет слайс булевых значений целиком. По цене Bool не отличается от Str: один append байтов, ноль аллокаций. И последнее: bool-хелперы закрывают и обратную задачу — читать флаги из конфига в контекст, поэтому признак окружения или фича-флага задаётся один раз на base и едет во все записи сервиса без единого повторного вызова.

Как только событие стало последовательностью вызовов, к нему применимы обычные конструкции языка. Вложенность собирает Dict: logger.Info().Dict("http", zerolog.Dict().Str("method", "POST").Int("status", 201)).Msg(...) — внутри записи появится объект http с полями method и status; Dict не требует собственной структуры и живёт целиком в вызове. Слайд значений добавляет Array с zerolog.Arr() или типом, реализующим LogArrayMarshaler. Набор пар, известный только в рантайме, — Event.Fields: он принимает map или слайс чередующихся ключей и значений и добавляет их все разом; ключи карты сортируются по алфавиту, слайс — в порядке следования. Это удобно для метаданных, которые пришли конфигом или ответом системы: не размечать каждое поле руками. Держите рамку: условная сборка — это то же самое событие с тем же контрактом ключей, а не способ менять схему записи от вызова к вызову. Потребители логов должны знать заранее, какие ключи вообще бывают в записях этого логгера, поэтому набор условных полей фиксируют в документации модуля так же, как фиксировали бы схему ответа API. Дёшево и полезно сверяться со списком ключей на ревью: пять минут против сюрприза в системе сбора через месяц.

Условные поля стоят вплотную к трём темам курса. Основа — типизированные методы из урока про поля события: условная сборка использует их же, просто под if. Экономика подсказана в уроке про производительность: там Any и Enabled встречаются в бенчмарках, и видно, сколько наносекунд стоит универсальное поле. А если поток записей с условными полями разрастается в спам — например, ретраи с полным payload на каждой попытке, — прореживание разберёт урок про sampling. Практический тест после этого урока: откройте свои вызовы логирования и найдите записи, которые пишут пустые строки и нули. Их нет? Отлично. Есть — вы знаете, что с ними делать: убрать пустые значения под условие, ошибки собрать через AnErr и перепроверить, что ни один тяжёлый payload не считается зря без Enabled.