Реестры и namespace метрик

Итоговое имя метрики собирается из трёх частей: Namespace, Subsystem и Name, склеенных подчёркиваниями — пустые части пропускаются. В GaugeOpts и CounterOpts поля называются именно так, и это единственный легальный способ получить префикс: имя не склеивают конкатенацией строк, потому что Help и настройки принадлежат метрике целиком. Зачем префикс: в /metrics смешиваются go_-метрики рантайма, process_-метрики процесса, метрики библиотек и ваши собственные, и без доменного префикса grep по нужной группе превращается в чтение сотен строк. Префикс службы — скажем, shop_ — сразу отделяет метрики домена от чужих, а второй уровень subsystem_ группирует их внутри: shop_orders_queue_depth читается как маршрут к владельцу кода. Тот же словарь используется в PromQL из двенадцатого урока и в переменных дашборда: грамотный префикс экономит минуты на каждом разборе. Словарь живёт рядом с кодом метрик: две строчки в комментарии пакета — какой префикс у домена и какие суффиксы единиц — экономят час обсуждения на каждом код-ревью.

Реестр — это словарь коллекторов, и в client_golang он реализован интерфейсами Registerer и Gatherer. Дефолтный реестр глобален: DefaultRegisterer принимает всё, что зарегистрировали через prometheus.MustRegister, а promhttp.Handler() собирает метрики из DefaultGatherer. Свой реестр создаётся одной строкой — prometheus.NewRegistry() — и живёт по тем же правилам: MustRegister добавляет коллекторы и паникует на дубликате, Register возвращает ошибку вместо паники. Два следствия, о которых забывают. Первое: в новом реестре нет ничего, включая go_- и process_-метрики, — их вносит вручную NewGoCollector() и NewProcessCollector(), если они нужны. Второе: promhttp.Handler() дефолтный реестр не увидит — на HTTP выставляют HandlerFor(reg, promhttp.HandlerOpts{}). Для сокращения записи есть promauto.With(reg): конструкторы сразу регистрируют метрику в вашем реестре и возвращают готовый объект.

Тесты метрик на дефолтном реестре ломаются двумя способами: значения накапливаются между тестами, потому что глобальный регистр один на процесс, и параллельные пакеты паникуют на дубликатах имён. Лечение — новый реестр на каждый тест: конструктор приложения получает его параметром, тест создаёт свежий, регистрирует свои метрики и проверяет значения через reg.Gather(). Gather возвращает срез семейств метрик в protobuf-структурах — из него берут значение нужного счётчика и сравнивают с ожиданием; это тот же интерфейс, которым Prometheus собирает данные по сети, только без HTTP. Для строгой проверки есть NewPedanticRegistry(): он дополнительно проверяет согласованность коллектора — тот же набор серий в Describe и Collect, что ловит расхождение декларации и реальности, о котором восемнадцатый урок писал применительно к своим коллекторам; pedantic-режим включают в CI на пакете метрик, где цена расхождения выше скорости. Бюджет прост: реестр в тесте — одна строка, а расхождение значений между тестами ищется час; Unregister существует, но в тестах им пользуются редко — новый реестр дешевле и чище, чем разрегистрация половины коллекторов.

Namespace работает, когда словарь префиксов один на команду. Верхний уровень — домен сервиса: shop_, billing_, notifications_; он же совпадает с job_name в конфиге скрейпа из следующего урока, и по графику сразу ясно, чей это сервис. Второй уровень — модуль: orders_, payments_, auth_. Дальше — имя с единицей по конвенции Prometheus: счётчики заканчиваются на _total, латентности на _seconds, размеры на _bytes, а базовые единицы не множатся: миллисекунды не пишут в имя, значение переводят в секунды. Лейблы не дублируют имя: route у счётчика запросов — да, но node или env в лейбле сервиса обычно избыточны, это та же кардинальная дисциплина, что в уроке семнадцатом. Практическая проверка словаря — тест на пять секунд: по одному имени метрики в /metrics должно быть видно, какой модуль отвечает, и в каких единицах значение.

Спорная часть урока: для монолита с одним приложением свой реестр часто лишний. Дефолтный регистр даёт ноль строк конфигурации, promhttp.Handler() работает из коробки, и пока в процессе живёт только ваш код, риск дубликата остаётся штатной паникой при старте — шумной, но честной: она падает в момент запуска, а не в разгар дня. Граница проходит там, где появляется второй владелец метрик: общая библиотека, встраиваемый модуль, несколько инстансов одного клиента, тесты. Тогда глобальное состояние перестаёт принадлежать вам, и свой реестр становится способом явной передачи владения. Отсюда практика, которая не спорит ни с одной стороной: приложению можно жить на дефолте, но каждый публичный пакет обязан принимать Registerer параметром — тогда переезд на свой реестр занимает одну строку в конструкторе, а не переписывание половины зависимостей.

Переезд занимает один коммит, если приложение собирало метрики через публичные конструкторы. Шаги: создать реестр, заменить prometheus.MustRegister на reg.MustRegister для всех объявлений, поменять promhttp.Handler() на HandlerFor(reg, ...) и прогнать тесты — они ловят глобальное состояние первым. Затем инвентаризация: curl по старому хендлеру показывает пустоту, и это правильно — метрики переехали, а не пропали; убедитесь зелёным up на новом пути из конфига скрейпа. Две ловушки переезда стоят отдельного абзаца. Первая — библиотеки, написанные в глобальный регистр: их вызовы продолжают складывать метрики в DefaultRegisterer, и на дашборде возникает расщепление половин; лечится параметром Registerer в конструкторе, как в warn-врезке выше. Вторая — забыть о go_-коллекторе: новый реестр пуст, и привычные go_goroutines исчезают, пока NewGoCollector не внесён вручную. Обе ловушки видны на первой странице /metrics, поэтому переезд проверяется глазами, а не только зелёными тестами.