zap.Config: полная настройка логгера

Поля zap.Config разбиты на четыре группы. Поведение: Level — минимальный включённый уровень, хранится как AtomicLevel, а значит, может меняться на живом процессе; Development — флаг режима разработки, который меняет поведение DPanic и щедрость стек-трейсов; DisableCaller и DisableStacktrace выключают соответствующие части записи; Sampling — политика сэмплирования, nil отключает. Формат: Encoding — строка «json» или «console» (плюс сторонние зарегистрированные), EncoderConfig — тот самый набор ключей и правил сериализации из урока про энкодеры. Вывод: OutputPaths — список путей или URL-схем, куда уходят записи; ErrorOutputPaths — куда zap пишет собственные ошибки. Контекст: InitialFields — карта полей, которая попадает в каждую запись от корневого логгера. Обратите внимание на типы: Level не число, а AtomicLevel, OutputPaths не строка, а срез — обёртка настроена на несколько приёмников с первого дня, и это не ошибка дизайна, а его суть.

Build — это фабрика: он разбирает Encoding, строит энкодер из EncoderConfig, открывает приёмники из OutputPaths через ту же механику, что и zap.Open, собирает ядро и оборачивает его в логгер с опциями — Development и сэмплирование прикладываются здесь же. Ошибка возвращается для всего, что нельзя распарсить: неизвестная схема пути, недопустимое Encoding, недоступный файл. Отсюда важное следствие: NewProduction() — это NewProductionConfig().Build(), и ничего больше. Пресеты не содержат магии, скрытой от вас: прод — это уровень Info, JSON, сэмплирование и стеки с Error; development — уровень Debug, консольный энкодер, стеки с Warn. Когда понадобится что-то между — конфиг пресета модифицируется по полям, как обычная структура. И раз пресеты — конфиги, их можно сравнивать: откройте NewProductionConfig и NewDevelopmentConfig в документации и увидите все различия списком — хороший способ убедиться, что никакой магии нет. Заметьте и цену: Build открывает файлы при старте и держит их открытыми — логгер, собранный в двух местах программы, откроет файл дважды; стройте один раз, как и всякий другой ресурс с состоянием.

Пути в конфиге — это URL или файловые пути: «stderr», «stdout», «logs/app.log» — схема по умолчанию файловая, зарегистрировать можно и свои через RegisterSink. OutputPaths — приёмники записей; ErrorOutputPaths — то, куда zap пишет собственные проблемы: не открылся основной файл, упала запись, кончился диск. Потоки принципиально разные, и смешивать их не стоит: если основной приёмник и error-приёмник — один и тот же файл, сбой этого файла съест и записи, и сообщения о том, почему их нет. Дефолт для внутренних ошибок — stderr, и это разумный минимум; в серьёзной конфигурации error-поток направляют туда, за которым присматривает мониторинг. Полная механика приёмников — файлы, мультиплекс, буферизация — следующий урок; здесь держите в голове разделение ролей: записи — это данные, ошибки логгера — служебный канал, и пути у них свои. Проверка путей при этом ранняя: Build вернёт ошибку на неизвестной схеме и недоступном файле ещё при старте, а не в момент первой записи — ловите её и падайте с понятным сообщением, а не обнаруживайте пустые логи в три ночи.

Самый частый сценарий настройки — не конфиг с нуля, а модификация пресета: cfg := zap.NewProductionConfig(), дальше правятся нужные поля, и вызывается Build. Такой подход безопаснее ручного заполнения: EncoderConfig уже на месте, сэмплирование и стеки — как в проде, и вы меняете ровно то, что хотите. Типовые правки: cfg.Level = zap.NewAtomicLevelAt(zap.DebugLevel) — включить отладку; cfg.OutputPaths = append(cfg.OutputPaths, "logs/app.log") — добавить файл к stdout; cfg.InitialFields = map[string]interface{}{...} — стартовые поля. Отдельная тонкость — флаг Development: он не про вывод, а про поведение — в true DPanic паникует и стеки идут с Warn. Меняя его, вы меняете семантику уровней, о которых договорились в третьем уроке.

У всех полей zap.Config есть теги json и yaml, поэтому конфиг логгера — обычная структура для маршалинга: её можно хранить в YAML-файле рядом с остальной настройкой сервиса и загружать при старте. Даже сложные правила сериализации описываются строками: encodeTime: "iso8601" или "epoch", encodeLevel: "lowercase" или "capital" — у этих типов есть UnmarshalText, и yaml-библиотека их разворачивает. Логгер при этом становится конфигурируемым без пересборки: поменяли файл — перезапустили сервис, формат и уровень новые. Это же дверь к строгой проверке: Decoder с KnownFields поймает опечатку в ключе yaml вместо молчаливого нулевого значения. А в реальных приложениях файлы конфигов читает Viper — он умеет YAML, TOML и env-переменные поверх; в курсе про Cobra этому посвящён целый урок, здесь достаточно идеи: конфиг логов — часть общей конфигурации, и живёт она не в исходниках.

InitialFields — карта any: эти поля попадают в каждую запись от построенного логгера и от всех его потомков через With. Типичное содержимое — app, version, env: метки, по которым в централизованном хранилище логи сортируются по сервисам и релизам ещё до фильтра по содержимому. Цена та же, что у zap.Any из урока про поля: значения едут как interface{}, и сериализация идёт через рефлексию — для полей, которые пишутся один раз на запись и известны при старте, это приемлемо, но горячие поля лучше добавлять типизированным With на построенном логгере. Отдельная история — альтернатива: logger.With("app", "shop") после Build даёт тот же эффект без карты any и прозрачнее в коде; InitialFields выигрывает там, где конфиг приходит из YAML — карту удобнее описывать рядом с остальной настройкой, а не дописывать в main.

Конфиг управляет приёмниками списком путей — но что физически происходит при открытии файла, как дублировать записи в stdout и файл и зачем нужна буферизация, разбирается в уроке про приёмники вывода. Смена уровня на живом процессе — тема урока про AtomicLevel: поле Level из этого урока там станет рулем без перезапуска. Карта курса — на странице курса.