Ошибки и стек-трейсы: zap.Error

Поле zap error появляется в записи через конструктор zap.Error(err) — это короткая форма zap.NamedError с ключом error. Кодировка честная: err.Error() уходит строкой, и на этом базовый путь заканчивается. Три нюанса, которые стоит знать до прод-инцидента. Нил-ошибка кодируется пусто: zap.Error(nil) не даст ни error: null, ни пустой строки — поля в записи просто не будет. Если ошибка реализует fmt.Formatter, zap пишет второе поле errorVerbose с результатом err.Format("%+v") — так работают пакеты вроде pkg/errors, у которых подробный вывод с местом возникновения. И поле error — обычное поле: оно фильтруется, индексируется и считается в дашбордах как любой string в JSON, а не магический объект.

fmt.Errorf с %w строит цепочку, и err.Error() склеивает все слои через двоеточие — «checkout: charge: connection refused». В лог это идёт одной строкой в поле error, и цепочка читается глазами сверху вниз: что делали, на каком шаге, чем кончилось. Проверки через errors.Is и errors.As по цепочке проходят свободно. Где граница пользы: когда слоёв становится пять-шесть, строка превращается в простыню, которую тяжело грепать — регулярка по одному слою начинает ловить чужие записи. Мой рабочий предел — три слоя: выше этого проще дать промежуточному слою осмысленное сообщение или сразу пустить поля в лог отдельно. Это вкусовщина, но ограничение стоит поставить заранее, а не после третьей ночи с grep.

error — одна строка в JSON, и соблазн вычленять из неё коды регэкспом в системе сбора велик. Я не люблю такой разбор: одна переформулировка сообщения — и дашборд по кодам ошибок умирает, а никто этого не заметит до следующего инцидента. Надёжнее вытащить структуру в коде — errors.As по своему типу — и уложить в отдельные поля: code, reason, order_id. Тогда уровни, алерты и графики строятся по полям, а строка error остаётся для человека. Ради этого не нужно заворачивать каждую ошибку в собственный тип: двух-трёх типов на границах модуля — платёж, внешний вызов, база — хватает на весь дашборд. Остальные ошибки честно пишутся строкой в zap.Error, и это нормально.

Стек-трейс в логах go получает опция zap.AddStacktrace(zapcore.LevelEnabler): записи выбранного уровня и выше уходят с полем stacktrace — срезом кадров на момент записи. Пресеты уже настроены: production пишет стек с Error, development — с Warn, потому что флаг Development опускает границу. Опцией границу двигают руками: AddStacktrace(zapcore.ErrorLevel) — стек только на настоящих авариях, AddStacktrace(zapcore.WarnLevel) — тоже на подозрительном. Не путайте со стеком-паникой: то, что runtime печатает при панике, — отдельный вывод, а поле stacktrace пишет сам логгер, и видно в нём именно место вызова logger.Error, со всеми промежуточными кадрами вашего кода.

Стек — дорогой и громоздкий снимок: двадцать кадров на запись, десятки строк в хранилище, обход стека через runtime на каждый вызов. Для неожиданных аварий это золото: Internal без стека — загадка. Но у большинства записей в живом сервисе стек не нужен: NotFound в базе, валидация формы, отказ шлюза — ожидаемые ветки, место их возникновения известно заранее, потому что там стоит лог. Живое правило: стек включают на уровне, который означает «такого не должно быть», и это почти всегда Error. Ожидаемое уходит на Warn без стека, неожиданное — на Error со стеком. Тогда stacktrace в записи — сам по себе сигнал: если он появился, дежурный знает, что код пришёл туда, куда идти не должен.

Паника, которую никто не поймал, печатает стек сам runtime: текстовый вывод в stderr, мимо JSON-конвейера, без request_id и без полей — система сбора увидит его разве что отдельным потоком контейнера. Это второй канал стеков, параллельный логам, и смешивать их при разборе неудобно. Практика: на границах — HTTP-посредник из урока про middleware, перехватчик gRPC, верх горутин — ставят recover, и паника попадает в zap уже структурно: zap.Any("panic", err), поле stack через debug.Stack(), поля запроса рядом. runtime-вывод остаётся страховкой для падений до этого рубежа: сбой при инициализации, ошибка в самом логгере.

Три старших уровня меняют поведение процесса, и стек у них особая история. DPanic пишет Error, а при включённом режиме Development паникует: инвариант, нарушенный в тестах на локальном окружении, роняет процесс и виден сразу, а в проде остаётся Error-записью. Panic пишет запись и вызывает panic — поверх поля stacktrace от логгера добавится стек самой паники от runtime. Fatal пишет запись и вызывает os.Exit(1): defer не выполнится, logger.Sync() в defer main не сработает, и хвост буферизованного вывода может не дожить до диска — это та же цена буферизации, что и в уроке про выводы. Поэтому Fatal оставляют для ситуаций, где продолжать действительно нельзя: невозможная конфигурация при старте, а не упавший запрос.

Цену поля stacktrace в цифрах — обход стека, аллокации — разбирает урок про производительность; тесты на поля ошибки удобно писать через zaptest и observer. Как ошибки проходят по цепочке Gin-обработчиков и где их логировать — в уроке про ошибки Gin; карта остальных тем — на странице курса.