Структура JSON: ключи и вложенность

Имена скелетных ключей — переменные пакета, а не константы: TimestampFieldName равен time, LevelFieldName — level, MessageFieldName — message, ErrorFieldName — error, CallerFieldName — caller. Их можно переопределить при старте: чужая система сбора, которая ждёт ts вместо time, — одна строка до создания логгера. Это обычные переменные без защиты: присваивайте до запуска горутин, чтобы не устроить гонку на горячем пути. Переопределение живёт в инициализации пакета логирования — первая строка main или func init, до первого события и до старта воркеров: переменные читаются на каждой записи, и менять их в рантайме — значит гонять присваивание наперегонки с записью, безо всякой синхронизации вокруг них. Значение уровня тоже настраивается — LevelFieldMarshalFunc превращает info в INFO, если формат вашей ленты требует верхний регистр. Время — TimeFieldFormat: RFC3339 по умолчанию, а TimeFormatUnix и TimeFormatUnixMs дают целые числа, что экономит байты и упрощает сортировку. Что важно понимать честно: API для массового переименования собственных полей в zerolog нет — ключ из Str("user_id") навсегда ваш строковый литерал. Имена фиксируются константами вашего пакета логирования, и их смена — осознанная миграция дашбордов, а не правка одной строки. Поле error из Err — часть того же скелетного словаря: алерты и дежурные ищут именно его, поэтому переопределять ErrorFieldName без крайней необходимости не стоит.

Два способа собрать вложенное. Dict: zerolog.Dict() создаёт безымянное событие, вы наполняете его обычными методами полей, а e.Dict(key, dict) закрывает его фигурной скобкой и вклеивает под вашим ключом; тот же метод есть у Context для контекста. Array: zerolog.Arr() создаёт массив с тем же словарём методов — Str, Int, Dur, Time, Object, Dict; e.Array(key, arr) записывает его значением ключа. Оба пути — типизированные методы, дописывающие байты: рефлексии нет, аллокаций почти нет, вложенность стоит примерно столько же, сколько плоские поля. Практический ориентир — группы, у которых есть смысл как целое: http с method, path и status, client с ip и версией приложения. Поля, которые фильтруются по отдельности, вложенности не просят: level, request_id и op живут наверху. Для структур с поведением есть Object: тип реализует LogObjectMarshaler с методом MarshalZerologObject(e *Event) и сам раскладывает себя по полям события; EmbedObject вклеивает те же поля без имени-обёртки. Третий путь — Interface: если значение не умеет MarshalZerologObject, оно уезжает через encoding/json с выключенным HTML-экранированием, и имена ключей определяют теги json структуры. Именно поэтому Object и Dict — инструменты горячего пути, а Interface — редких дампов: цена и предсказуемость различаются, экономику этого выбора разбирает урок про производительность.

Loki собирает ленту JSON-объектов: каждая строка — самостоятельный объект, и запросы LogQL разбирают его ключи. Практические следствия для zerolog. Первое: ключи верхнего уровня — ваши главные фильтры; json-парсер LogQL достаёт их и даёт фильтровать ленту по значению, поэтому service, op, level и request_id должны лежать наверху, а не внутри объектов. Второе: вложенные объекты парсер разворачивает в плоские имена с подчёркиваниями — method внутри объекта http станет http_method; один уровень вложенности переживается спокойно, но каждый следующий — место, где имена перестают быть очевидными. Третье: message остаётся текстом для полнотекстового поиска, а level — стандартным ключом для распределения по уровням; оба имени заданы скелетом zerolog, и это совпадает с ожиданиями сборщика. Четвёртое — время: если пайплайн не настроен взять time как метку события, запись получит время приёма, и при задержках доставки графики будут врать. TimeFieldFormat в виде Unix-миллисекунд упрощает разбор: число парсится однозначно, а RFC3339 со смещением требует явного формата. Типовой разбор глазами дежурного: селектор по service, затем json-парсер, затем фильтр по level — все три слова это ключи вашей записи, и ни одно не появилось бы там само. Плоская запись делает каждую строку самодостаточной для такого разбора: логи разных сервисов склеиваются в одну ленту, и фильтр отделяет чужое. Итог: глубина максимум один уровень, ключи наверху, message — факт, level — стандартный, время — машиночитаемое.

Вложенность не бесплатна до бесконечности. Каждая скобка — байты, каждый подобъект — вызовы методов и ветвления; на тысячах событий в секунду разница между плоским событием из шести полей и трёхуровневой конструкцией заметна в профиле — та же экономика, что и в производительности. Отдельно про значения-объекты в Interface: encoding/json упакует и слайсы, и вложенные структуры, но заплачено будет рефлексией на каждой записи; если такой дамп нужен раз в сутки при старте — цена незаметна, а если он переехал в обработчик запроса, профиль покажет рост аллокаций раньше, чем вы успеете удивиться. Читаемость страдает раньше скорости: вложенный объект занимает строку на каждый уровень и в консоли, и в дампе, и поиск глазами по ленте замедляется. Договоритесь в команде на одном правиле: два-три имени объектов максимум — например, http для запроса и client для источника, — внутри всё плоско. Err стоит отдельно: его ключ задаётся ErrorFieldName и по умолчанию равен error, значение — текст ошибки или пропуск при nil, как разобрано в уроке про поля. Этот ключ тоже часть словаря сборщика: алерты строятся по error, и переопределять имя стоит только вместе с ними. Поле Errs для слайса ошибок и AnErr для ошибки-объекта завершают семейство — оно целиком разобрано в уроке про логирование ошибок.

Следующий урок — тесты логов: bytes.Buffer вместо writer-а, разбор JSON в тесте и фиксация структуры из этого урока как контракта. После — логи и метрики Prometheus: ключи записи становятся колонками дашбордов, а счётчик рядом с событием превращает ленту в алерт. Структура, которую вы сегодня зафиксировали, — это и есть контракт, который будут защищать тесты.