Ошибки: Err, Stack и AnErr

Метод Event.Err(err) — главный способ положить ошибку в запись: поле получает имя zerolog.ErrorFieldName, по умолчанию error, и значение err.Error(). Нулевая ошибка пропускается целиком — поля error":null в ленте не появится, и это поведение стоит помнить при цепочках, где err может быть nil. Внутри метода стоит проверка на nil, поэтому вызов безопасен в любом месте цепочки и не стоит ничего. Работает Err и на других уровнях: Warn().Err(err) — нормальная форма для «упало, но пережили». Сокращение Logger.Err(err) сразу поднимает уровень до error и добавляет поле одним вызовом — удобно наверху обработки. Нюанс из док-комментария: «error-уровень с полем, если err не nil, иначе — info», то есть при nil-ошибке отдаётся Info-событие без поля, и ветка остаётся читаемой записью даже без сбоя. Главная ловушка — err.Error(): метод возвращает склеенную цепочку «outer: middle: root», и в JSON уезжает вся строка целиком. Для поиска по корню это боль: фильтр error"deadline не найдёт запись с текстом charge" timeout" deadline. Поэтому либо кладите причину отдельным ключом через AnErr, либо разматывайте цепочку errors.Is и errors.As и логируйте её явно. Для глобальной настройки есть zerolog.ErrorMarshalFunc — функция, через которую проходит каждая ошибка перед записью; ей можно вернуть структуру с типом и кодом вместо сырого текста. Сама механика полей события разобрана в уроке про поля, а правило «не склеивать ошибку в текст сообщения» — из антипаттернов логов: строка в Msgf не фильтруется, поле фильтруется.

AnErr(key, err) — тот же Err, но под вашим ключом: cause, db_err, remote_err. Зачем второй ключ: фильтры по error ловят всё подряд, а по cause — только то, что вы пометили как причину; текст верхнего уровня и корень живут раздельно, и дашборд по cause не всплывает от посторонних ошибок. Нулевая ошибка пропускается: AnErr("cause", nil) не оставит в записи следа, поэтому условная цепочка AnErr без if работает безопасно. Errs(key, errs) — для коллекций: слайс ошибок уезжает JSON-массивом под заданным ключом, и в v1.34.0 nil-элементы сериализуются как null, а пустой слайс — пустым массивом; учитывайте это, собирая мульти-ошибку из валидации. Сценарий у Errs один — «набор проблем одного события»: список причин отказа, накопленные ошибки ретраев, итог батча. errors.Join из стандартной библиотеки вписывается в эту картину с оговоркой: он склеивает ошибки в одну, и Err покажет весь список текстом — если нужна структура массивом, держите слайс и пишите Errs. Для одиночной ошибки Err и AnErr остаются основными вызовами, а Logger.Err стоит держать в голове как короткую форму: уровень и поле одним вызовом, без отдельной цепочки.

Стек вызовов в лог zerolog не пишет сам: у события есть метод Stack(), но он лишь ставит флаг, а поле добавляет глобальный маркер zerolog.ErrorStackMarshaler. По умолчанию маркер nil, и Stack() без настройки ничего не делает — самая тихая ловушка урока. Маршрут из коробки: zerolog.ErrorStackMarshaler = pkgerrors.MarshalStack из пакета github.com/rs/zerolog/pkgerrors — он работает с ошибками github.com/pkg/errors, которые захватывают стек в момент создания. Тип маркера — func(err error) interface{}: собственная реализация на runtime.Callers или debug.Stack встраивается одной функцией, если тянуть pkg/errors в проект не хочется. MarshalStack разматывает цепочку через Unwrap, находит ошибку с методом StackTrace() и сериализует кадры массивом объектов с ключами source, line и func под именем zerolog.ErrorStackFieldName — по умолчанию stack. Порядок вызовов важен: Stack() ставит флаг, Err читает его, поэтому цепочка собирается как Error().Stack().Err(err) — наоборот флаг опоздает. Стек переживает обёртывание: fmt.Errorf("%w") поверх pkg/errors-ошибки не рвёт цепочку, и MarshalStack докопается до оригинала — потому стек захватывается там, где ошибка рождается, а сколько слоёв её потом обернули — неважно.

Стек — инструмент программных ошибок: паника, нарушенный инвариант, невозможная ветка. Для доменных отказов он почти всегда шум: «пользователь не найден» — это данные ответа, а не сбой, и кадры на двадцать строк лишь раздувают лог. Спорное мнение, которое сэкономит вам гигабайты: если ошибка — ожидаемая часть бизнес-логики, стек ей не нужен, хватит текста и причин в отдельных полях. Условие, при котором я прав: ожидаемые ошибки вы различаете типом или errors.Is, а не разбором строки — иначе без стека не поймёте, откуда взялся unexpected EOF. Вторая ловушка — переиспользуемые ошибки: синглтон errNotFound из пакета захватил стек при инициализации, и MarshalStack честно покажет кадры package init — правды о месте отказа там нет. Поэтому стеки имеет смысл включать там, где ошибки создаются локально на каждый вызов, а для сентинелов — ошибок-констант — стек бессмыслен с рождения. Практический компромисс: Stack() на Error-событиях, Warn и ниже — без кадров, и объём лога под контролем. Кадр стека весит заметно больше остальной записи — объект с source, line и func на каждый кадр, — и на шумном Error-потоке эти сотни байт на событие превращаются в гигабайты за месяц.

Ошибка в JSON — уже половина диагностики; курс доводит её до конца. Производительность покажет, сколько стоит событие с Err на горячем пути и где включать Disabled, урок про структуру JSON — как устроены вложенные объекты и массивы вроде поля stack, а тесты логов научат проверять error и cause в тестах буфером. Справочное закрепление: соберите три слоя — репозиторий, сервис, хендлер — и проведите одну ошибку через все, обёртывая в каждом fmt.Errorf с %w; в access-логе должен остаться один Error с текстом цепочки и причинами в отдельных полях.