Знакомство с zap: зачем структурные логи

Идея структурного логирования проста до обидного: лог — это не текст, а данные. Каждая запись — событие с фиксированным набором полей: уровень серьёзности, время, сообщение и сколько угодно своих пар ключ-значение: user_id=42, order_id=100500, elapsed_ms=317. Формат записи машиночитаем — чаще всего это JSON, реже key=value в потоке. JSON-логи парсит любая система сбора: Loki, Elasticsearch, ClickHouse — им не нужна регулярка под каждый сервис, схема полей и так известна. Взамен вы получаете фильтры, которых grep не даёт никогда: все ошибки за последний час, где user_id=42 и elapsed_ms больше 500; частоты кодов ошибок; графики по любому полю. Человек это тоже читает — JSON не поэзия, но при аккуратных полях дежурный разберётся быстрее, чем в трёх форматах трёх сервисов. Сегодня структурное логирование — дефолт индустрии, а не экзотика: в Go его долго олицетворял logrus, теперь — zap, slog и zerolog, и с первым из них мы и знакомимся.

В 2017 году логгером по умолчанию в Go был logrus: удобный, с хуками и форматтерами — и медленный. Запись лога в logrus — это рефлексия по полям, сборка строки и приличная пачка аллокаций на каждое событие. Для обычного CRUD это невидимо, но Uber гонял тысячи сервисов с высокими RPS, где логи пишутся на горячем пути каждого запроса, и профилирование показывало: на логирование уходят проценты CPU и горы мусора для сборщика. Ответом стал zap: типизированные конструкторы полей вместо рефлексии, пул записей и буферов, ноль аллокаций на отключённых уровнях. По данным репозитория, на их бенчмарке с сообщением и десятью полями zap пишет лог более чем в семь раз быстрее logrus и примерно вдвое быстрее slog из стандартной библиотеки — цифры синтетические, но порядок верный: разницу видно и без бенчмарков, на графике p99. С тех пор API стабилен: версия 1.x, и код из туториалов 2017-го компилируется сегодняшним компилятором без правок.

С августа 2023 в Go есть slog — логгер в стандартной поставке, и первый честный вопрос: зачем тогда zap? Для многих проектов — незачем: slog с JSONHandler закрывает структурное логирование без единой зависимости, и на новом маленьком сервисе я бы начинал именно с него. Zap выигрывает там, где логи — часть горячей нагрузки: быстрее (по данным всё того же репозитория), с сэмплированием из коробки, с динамической сменой уровня на живом процессе, с богатым ядром zapcore, на котором собирают кастомные энкодеры и приёмники. Плюс экосистема: zap умеет быть бэкендом для интерфейса logr — так логирует Kubernetes через мост zapr; у него зрелый инструментарий тестов и observer для проверки записей. Моё правило: микросервис на сотню RPS — slog; сервис с десятками тысяч запросов в секунду, где каждая микросекунда overhead-а читается на графике, — zap. Всё, что разбирается дальше, про второй случай, но API slog и zap так похожи, что знания переносятся почти без потерь.

Главное возражение против JSON-логов я слышу на каждом ревью: в них невозможно читать. Возражение устарело лет на десять. Во-первых, zap умеет console-энкодер: тот же логгер, те же поля, но вывод колонками для человека — его включают в development-окружении и на локальной машине. Во-вторых, JSON парсится одной командой: jq '.msg' по потоку — и вы видите только сообщения; jq 'select(.level=="error")' — и перед вами одни ошибки. В-третьих, системы сбора показывают записи таблицей: поля разворачиваются в колонки, и читать их удобнее, чем сплошной текст, где нужное значение прячется между словами. Боль реальна только у тех, кто открывает сырой поток логов в notepad — так открывать и текстовые логи тоже больно. Итог: человек читает логи через инструмент, машина — через поля, и JSON обслуживает обоих дешевле, чем любой самодельный текстовый формат, который придётся ещё и парсить.

zap ставят быстро, а мышление меняется медленно. Классика переходного периода: logger.Info(fmt.Sprintf("order %s not found", id)) — JSON снаружи, grep-мир внутри. Запись выглядит структурной, но фильтру в системе сбора ловить нечего: все данные спрятаны в msg, поле одно на всю запись, дашборд по ней не построишь. Я ловил такое в ревью у людей, которые месяцем раньше клялись структурными логами: привычка склеивать строки живёт дольше, чем кажется. Приём для самопроверки простой: посмотрите на запись и спросите, что в ней можно посчитать — частоту событий, долю промахов, медиану времени. Если ответ «только количество строк», данные надо выносить в поля: zap.String("order_id", id) — и сообщение сокращается до факта «order not found», а идентификатор становится фильтром. Что будет, если ошибку не заметить: через квартал команда обнаруживает, что платит за систему сбора логов, а ищет всё равно grep-ом по JSON — только теперь регулярки ломаются ещё и о кавычки. Отдельный случай — строка, собранная для человека: читаемость в консоли обеспечивает console-энкодер, а не Sprintf внутри msg; форматом управляет энкодер, и это тема урока, где мы сравним JSON и console во всей красе.

Логгер — одна треть обсервабельности: рядом живут метрики (числа: RPS, латентности, коды ответов) и трейсинг (путь запроса через сервисы). Логи отвечают на вопрос «что именно случилось», метрики — «насколько плохо», трейсы — «где по пути». Связывает их поле: если каждая запись несёт request_id или trace_id, то по алерту на графике вы за секунду находите конкретные записи в Loki или Kibana. JSON-логи zap для этого и созданы: trace_id станет обычным ключом, по которому системы сбора связывают записи тысяч запросов. В курсе мы доведём это до практики: в уроке про middleware подключим zap к HTTP-роутеру так, чтобы каждый запрос логировался со своим идентификатором — тот же приём, на котором построены middleware в Gin, если вы уже писали на фреймворках.

Во втором уроке — первый логгер: zap.NewProduction и zap.NewDevelopment, Sync и первые записи с полями, разбор JSON по ключам. Третий — уровни логов, четвёртый — поля во всей красе. Карта всех двадцати пяти тем — на странице курса. А пока установите zap локально и запустите пример из этого урока: первая JSON-строка в терминале стоит всех карточек этого урока.