Ротация логов: lumberjack

В седьмом уроке мы задавали приёмники через OutputPaths — это файлы, которые zap открывает и держит открытыми; менять их на лету он не умеет, да и не должен. Ротация логов go — задача уровня файловой системы, и zap принципиально её не тащит в ядро: вместо этого приёмником может быть любой объект с методом Write. Связка lumberjack zap устроена именно так: структура lumberjack.Logger реализует io.Writer, обёртывается в WriteSyncer одной строкой zapcore.AddSync и садится в ядро, которое мы собирали в уроке про zapcore. Получается честное разделение труда: zap решает, что логировать и в каком формате, lumberjack — куда физически кладутся байты и когда файл пора резать. Пара замечаний перед кодом. Первое: lumberjack не читает zap.Config — ручной конфиг из прошлого урока или WrapCore, третьего пути к нему нет. Второе: пакет не ведёт ротацию по времени и не умеет внешних сигналов — только размер, и это надо принимать как дизайн, а не бороться. Установка на вашем окружении: go get gopkg.in/natefinch/lumberjack.v2 — и для запуска примеров, как и со всем библиотечным курсом, понадобится локальный Go, в песочнице проекта zap не исполняется.

Вся конфигурация lumberjack — пять полей структуры, и у каждого есть нулевое значение, которое означает «правило не активно». Filename — базовый файл, в который пишется текущий поток; имя носит всегда именно он, а не бэкапы. MaxSize — предельный размер в мегабайтах: при превышении на очередной записи файл уезжает в архив и открывается новый; ноль или отсутствие поля означает дефолт в 100 МБ. MaxBackups — сколько старых файлов хранить, счёт идёт по архивам, текущий файл не считается; ноль означает хранить всё — и это ловушка новичков, которые читают ноль как «не хранить бэкапов вовсе». MaxAge — максимальный возраст архивов в днях: что старше, то удаляется при следующей ротации, независимо от MaxBackups. Compress — сжимать ли архивы gzip: файл получает суффикс .gz, и типичный лог сжимается в пять-десять раз. Есть и LocalTime — по умолчанию метки в именах архивов ставятся в UTC.

Механика простая и потому предсказуемая. Перед каждой записью lumberjack смотрит на текущий размер файла: если свежая запись перевалит за MaxSize, файл закрывается, переименовывается в logs/app-2024-11-02T15-04-05.312.log — в имя зашивается момент ротации, — и открывается новый app.log. Всё это происходит синхронно внутри вызова Write: между записями zap и архивом нет фонового демона, таймера или cron. Отсюда следствие, о котором редко думают: MaxSize проверяется не постфактум, а перед записью, поэтому файл может стать чуть больше лимита, но ровно на одну запись; и отдельная крайность — если одна запись сама длиннее MaxSize мегабайт, lumberjack вернёт ошибку, а не запишет её куском. Пропорции держите разумные: лимит в мегабайтах при записях в сотни байт даёт чистую картину. После ротации в каталоге лежат текущий app.log с постоянным именем и архивы с таймштампами — старое вычищается по MaxBackups и MaxAge уже при следующей ротации, не раньше. И ещё одна деталь на память: удаление архивов случается только в момент ротации — если поток записей встрял, aged-файлы будут лежать дальше, сколько бы дней им ни исполнилось.

lumberjack создаёт файлы с правами 0600 — читать и писать может только владелец, и это не баг, а консервативный дефолт. В реальной эксплуатации он бьёт больно: агент сбора логов (fluent-bit, promtail) часто работает под другим пользователем и молча не видит файл; скрипт дежурного с sudo требует для каждой проверки. Проблема усугубляется после ротации: вы дали chmod 0644 текущему файлу, а на следующий день он уехал в архив, и на его месте — новый 0600, собиратор снова не видно. Штатной ручки «права на файл» в lumberjack.v2 нет, поэтому варианты такие: гонять сборщик от того же пользователя, что и сервис; при старте выставлять umask, под которым размаскируются права группы; либо забрать каталог под контроль внешней ротации, отказавшись от lumberjack. Решение принимайте осознанно — молча нечитаемые файлы логов всплывают в самый неудобный момент расследования.

lumberjack ничего не экспортирует наружу — ни метрик, ни событий ротации, он просто режет файлы. Значит, мониторинг размера — ваша забота, и список проверок короткий. Во-первых, df на раздел с логами: даже при ротации архивы суммируются, а MaxAge не сработает, пока не случится следующая ротация — в спокойный сервис без ошибок каталог может молча накапливаться неделями. Во-вторых, du по каталогу логов как метрика: сумма размеров app.log и архивов в алерте — простейший экспортер на shell или Node exporter с textfile-коллектором. В-третьих, сами записи lumberjack: если файл не открылся или ротация упала, lumberjack вернёт ошибку из Write — zap уйдёт с ней в ErrorOutputPaths, и это единственный канал, где сбой ротации виден в логах. Не отправляйте ErrorOutputPaths в тот же lumberjack-файл: смерть диска убьёт оба канала разом. Отдельный вопрос — сжатие: Compress: true стоит CPU на gzip при каждой ротации, зато экономит диск кратно; на нагруженном сервисе это ощутимо в обе стороны, считайте при выборе.

Самая коварная ловушка — попытка починить заполненный диск руками. Открываете dmesg, видите, что app.log огромный, делаете rm logs/app.log — и df не двигается: место всё так же занято. Причина в том, что удаление имени не удаляет данные, пока на файл смотрит открытый дескриптор: процесс держит inode, lumberjack продолжает писать в «удалённый» файл, и место освободится только когда сервис перезапустят или случится ротация. С lumberjack это всё равно безопаснее, чем с классическим logrotate: ротация здесь — переименование собственным процессом, дескриптор переоткрывается внутри, ничего между сервисом и файлом не стоит. Но правило запомните: у долгоживущего процесса файлы сначала закрывают или ротируют, и лишь потом удаляют — lsof по имени покажет, кто держит дескриптор. И то же самое в обратную сторону: mv app.log куда-то не спасёт — записи полетят в переименованный файл, как ни называй.

Механику приёмников без ротации — stdout, файлы, мультиплекс и буферизацию — разбирает урок про приёмники вывода: lumberjack садится ровно на то же место WriteSyncer. Ротация режет объём по размеру, но не по смыслу: когда шумят ретраи, файл делится на сто кусков, каждый по 50 МБ, — здесь нужен следующий уровень, сэмплирование логов. Карта курса — на странице курса.