Динамические уровни: AtomicLevel

zap.NewAtomicLevel() возвращает значение типа zap.AtomicLevel — тонкую обёртку над атомарным целым. Контракт у неё тот же, что у любого фильтра ядра: интерфейс zapcore.LevelEnabler с методом Enabled(zapcore.Level) bool — именно его ядро вызывает на каждой записи, решая, пропускать ли событие дальше. Внутри обёртки — указатель на atomic int32, поэтому все копии значения делят одну переменную: SetLevel с любой копии мгновенно виден всем логгерам, собранным на этом уровне. Это не случайность дизайна: поле cfg.Level в zap.Config имеет тип zap.AtomicLevel, а не числовой уровень, — конфиг задуман так, чтобы динамическая смена уровня логов была штатной опцией, а не хаком. По умолчанию NewAtomicLevel даёт Info; нужен другой старт — NewAtomicLevelAt(zap.DebugLevel). Пара zap AtomicLevel встречается в проекте дважды: в поле конфига при старте и в переменной, которую держат для ручки смены, — и оба раза это одно значение: логгер собирается на нём, а ссылка живёт рядом с конфигурацией.

Динамическая смена уровня логов — это один вызов level.SetLevel(zapcore.WarnLevel). Аргумент — обычный zapcore.Level: от Debug(-1) до Fatal(5). Текущее значение читается методом Level(), строковое имя для админки — методом String(). Момент применения стоит понимать точно: решение «пропускать ли запись» принимается в момент вызова Info или Debug, а не заранее, поэтому никаких перезагрузок и прогрева не существует — следующая же запись оценивается по новому порогу. При этом сам факт смены никуда не пишется: логгер не знает, что его фильтр изменили. Приучите себя логировать смену вручную: кто, когда и с какого уровня на какой перешёл. Без такой записи ночной Debug, забытый включённым до утра, превращается в загадку «почему диск кончился в четыре часа». Уровень при этом — операционный параметр, а не константа кода: он меняет поведение наблюдения, не трогая данные, поэтому и обращаться с ним стоит как с изменением конфигурации — с логом, автором и правом откатить.

Смена уровня по HTTP — самый практичный способ достать до ручки из админки или curl-а. Endpoint принимают методом POST: запрос меняет состояние сервиса, а GET по семантике обязан быть безопасным и его кешируют прокси. Тело — короткая строка уровня, которую разбирает zapcore.ParseLevel. Обязательные атрибуты: проверка прав (токен, mTLS, список адресов), ограничение размера тела и запись в лог самого факта смены с инициатором. Ниже — обработчик целиком; он маленький, но каждая его строчка отвечает за реальный инцидент, который где-то уже случался.

Сценарии, где ручка окупается сразу. Первый — локализация бага на живом трафике: гипотеза «падает валидация купонов» проверяется пятиминутным Debug-окном, а не полчаса выката. Второй — переходные периоды: миграция базы, смена балансера, свежий релиз — на час поднимается Debug, потом снимается. Третий, обратный: шумный модуль заваливает поток записями — на живом сервисе уровень поднимается до Warn без пересборки, пока команда готовит патч. Моё мнение, спорное для части команд: /loglevel должен быть в каждом сервисе по умолчанию — но закрытый авторизацией, с логированием смены и с таймером, который сам возвращает Info через десять минут, если оператор забыл. Без таймера ручка превращается в мину: Debug, включённый в марте, находят в декабре, когда кончается диск. Отдельный случай — многослойные сервисы: ручка меняет уровень только вашего процесса и на соседние не распространяется. Если трассировать нужно всю цепочку, endpoint ставят в каждый сервис либо выравнивают уровень через конфиг-сервис.

SetLevel меняет память процесса: рестарт вернёт уровень из YAML, переменных окружения или дефолта пресета. Это осознанный дизайн, и он удобнее, чем кажется: временный debug не прилипает к окружению навсегда, а постоянное желание «всегда видеть Debug у billing» — повод править конфиг, а не дёргать ручку. Если устойчивость нужна, уровень хранят снаружи: переменная окружения на старте или ключ в config-сервисе, который приложение читает при подъёме. Второй нюанс — несколько ядер: если логгеры собраны через tee, у каждого ядра свой LevelEnabler, и ваша переменная меняет только то ядро, которому её отдали. Держите один AtomicLevel как источник истины, если явно не хотите раздельных фильтров. Наследники тут без сюрпризов: потомки от With и Named делят ядро с родителем и собственных фильтров не имеют, поэтому одна смена уровня охватывает и их — модульных настроек по умолчанию не существует.

Отдельного разговора стоит связь динамического уровня с сэмплированием из урока про NewSamplerWithOptions. Сэмплер сидит над ядром и прореживает повторяющиеся сообщения по счётчику уровень-плюс-текст; включение Debug ручкой не трогает его правила. Итог честный: после подъёма уровня вы увидите первые записи каждого вида, а хвост — с пропусками. Для короткого окна это нормально: цель окна — подтвердить гипотезу, а не собрать полную выкладку. Если нужна полнота, соберите на время диагностики второй логгер без сэмплера в отдельный файл — и уберите, когда закончите. Обратная связка тоже полезна: ручка уровня — безопасный способ снизить шум, когда сэмплер настроить некогда. Практическое правило: Debug-окно оценивают по первым записям каждого вида, а не по полноте потока. Если гипотезе нужен полный массив — это работа для воспроизведения на стенде, а не для прод-ручки.

Ручка уровня живёт рядом с логирующим middleware: в уроке про логирование HTTP-запросов /loglevel встраивается в тот же роутер, что и админские маршруты. Цену лишнего Debug в цифрах — аллокации и пропускную способность — меряют и обсуждают в уроке про производительность zap, а про связь уровней с алертами и метриками честно сказано в материале про логи и наблюдаемость. Карта остальных тем — на странице курса. Ручка уровня — последний кирпич операционной зрелости логов: дальше идут перехватчики gRPC и эксплуатация, но с ней ночная смена уже проходит без рестартов.