Logger.With: контекстные поля

В zerolog With() — метод логгера, который возвращает zerolog.Context, накопитель предзаданных полей. Вы цепочкой добавляете в него Str, Int, Bool, Timestamp — что угодно из того же набора, что и у события, — и финализируете вызовом Logger(): на выходе новый логгер, у которого в контексте лежат все выбранные поля. Ключевая деталь механики: контекст хранится уже сериализованным — готовыми JSON-фрагментами вроде "service":"billing" — поэтому на каждое событие zerolog просто дописывает этот готовый кусок в буфер записи: без перечитывания полей, без рефлексии и без аллокаций. Отсюда и порядок в итоговом JSON: уровень, ключ time, если он в контексте, затем поля контекста в порядке их добавления, затем поля самого события, и последним — message: он дописывается при финализации, после всех полей. Контекстное поле легко узнать в записи по позиции — оно стоит раньше всего, что добавлено в цепочке события. Метод работает и от глобального логгера пакета log — log.With().Str("service", "api").Logger() — хотя в приложениях чаще собирают собственный базовый логгер при старте и раздают его по зависимостям, как мы разбирали в уроке про первый лог.

Набор методов у zerolog.Context почти тот же, что у события: Str и Strs, Int и все целочисленные вплоть до Uint64, Float32 и Float64, Bool, Bytes, Hex, Dur, Time, Err — он, как и у события, молча пропускает nil, — AnErr, Errs, Interface и Any, RawJSON, Dict. Плюс служебные методы, которым в контексте самое место. Timestamp() добавляет ко всем событиям ключ time — так собирают базовый логгер с самого первого урока. Caller() добавляет файл и строку вызова, Stack() — стек при ошибках. Fields принимает map или слайс пар ключ-значение и добавляет их все разом; деталь, о которой мало кто читает в документации: ключи карты zerolog сортирует по алфавиту, чтобы вывод не зависел от случайного порядка обхода в Go, — так что для критичных к порядку полей пишите отдельные Str. Reset() очищает контекст. Всё это задаётся один раз на логгер, поэтому сюда переезжают и Timestamp, и общие Err — то, что раньше повторялось в каждом вызове из урока про поля события. Отдельно упомяну экзотику, которая прячется в конце списка методов: IPAddr и MACAddr для сетевых адресов, Stringer для любого значения с методом String() — удобно для типизированных ID из enum-подобных типов, Type для имени типа значения. Всё это — одни и те же байты контекста, и все они доступны ровно там, где есть zerolog.Context: и в With, и в цепочке события.

Из базового логгера вырастает целое дерево. Первый этаж — логгеры на модуль: base.With().Str("module", "auth").Logger() и рядом billing, payments, worker — каждая подсистема получает свою копию со своим module. Второй этаж — логгер на запрос: в начале обработки reqLog := base.With().Str("request_id", id).Logger(), и все записи обработчика, включая вложенные вызовы, куда reqLog передали аргументом, уже размечены идентификатором. Дочерние логгеры расширяются так же: auth.With().Str("component", "oauth").Logger() даст события с module=auth и component=oauth сразу. Такая разметка — это не украшение, а формат данных для системы сбора: графики по модулям и треки запросов строятся фильтром по одному ключу. Имена модулей держите в константах и придумывайте один раз — они станут координатами в каждой записи, и переименование после того, как на module настроены дашборды и алерты, обойдётся дороже, чем кажется. Полный разбор дерева сублоггеров с реестром и тестами — в отдельном уроке про сублоггеры, а middleware, который размечает запросы request_id автоматически, ждёт в уроке про HTTP-логи.

zerolog.Logger — тип-значение: структура с writer-ом, уровнем и байтовым контекстом. Все методы модификации — With, Level, Output, Sample, Hook — возвращают копию, а не меняют receiver. Из этого следуют три практических правила. Первое: дочерний логгер — это снимок родителя на момент создания; если позже пересобрать base с новым полем, уже созданные дети этого поля не увидят. Второе: копию можно свободно передавать в функции и горутины — никакой общей мутируемой нагрузки, кроме writer-а, у копии нет, а writer в zerolog рассчитан на параллельные вызовы. Третье: раз логгеры — значения, поля контекста лежат в каждой копии своими байтами, и на длинных цепочках With контекст растёт для всех потомков — ещё одна причина не складывать туда лишнее. Экономнее всего разметка живёт на длинных связках: одна и та же копия логгера прокидывается через конструкторы репозиториев и сервисов, и каждая запись на выходе самодостаточна. Глобальный порог zerolog.SetGlobalLevel при этом общий для всех копий — он проверяется на каждом событии поверх локального уровня. Есть и обратная операция: GetLevel() читает порог копии, что удобно в тестах конфигурации — собрали логгер для шума на Warn, проверили GetLevel, не разбирая JSON. Отличать поля контекста от полей события и выбирать, что куда, помогает навык из урока про поля события: там же и таблица типизированных методов.

Стоимость With раскладывается на две части. При создании логгера каждое поле контекста один раз сериализуется в байты и дописывается в буфер контекста — это единственная работа на всю жизнь копии. При каждом событии zerolog копирует готовые байты контекста в буфер события — по сути memcpy куска на десятки-сотни байт; аллокаций нет, рефлексии нет. Отключённое событие не копирует ничего: nil-событие получает не буфер, а отказ, и контекст остаётся не у дел. Сравните с альтернативой без With: те же поля дописываются в каждом вызове — больше кода, шанс пропустить и та же цена сериализации, только на каждом событии вместо одного раза. Так что With выгоднее и короче одновременно — редкий случай, когда лучший по читаемости вариант и самый быстрый совпадают. Замеры логгера в бенчмарках с контекстными полями и честные оговорки — в уроке про производительность. Проверить всё руками проще локально: песочница сайта — тематическая программа на чистом Go, а настоящий With с живым JSON запускается через go run за минуту.