Карта метрик (metrics.path)¶
Карта метрик — объявление всех метрик, которые сервису разрешено эмитить. С ней закрываются три вещи сразу: метрики описаны в одном месте, дев-дашборд показывает данные, а «сервис эмитит незаявленную метрику» становится невозможным по построению, а не по договорённости.
Карта не указана — ничего не включается: ни сгенерированного пакета, ни валидатора, ни панелей. Поведение проекта остаётся прежним.
Подключение¶
Карта — контрактный артефакт, поэтому живёт в контрактном репозитории, а project.yaml несёт только ссылку на неё. Форма ссылки та же, что у rest[].path (см. Удалённые спеки): локальный путь, https://, git+ssh://, git+https://.
# project.yaml
metrics:
path: "git+https://github.com/org/contracts.git@v1.4.0#common/metrics-map.yaml"
Локально — для проб и для тестов:
Карта читается во время генерации и в проект не копируется: ничего ниже по цепочке её не читает, артефактом является сгенерированный пакет коллекторов. Второй копии, которая молча расходится с контрактом, не возникает.
Формат карты¶
Плоский список. Минимально достаточны четыре поля:
# common/metrics-map.yaml
metrics:
- name: spawn_errors_total
type: CounterVec
labels: reason, stage
help: >-
Spawn attempts that failed, by reason and stage.
name — полное имя метрики¶
В name пишется то имя, которое увидит Prometheus, целиком. Разбиения на namespace / subsystem / name (как в prometheus.CounterOpts) здесь нет, и это осознанно: имя, собираемое в рантайме, — это имя, которого нет в исходниках, поэтому его не находит ни поиск по коду, ни ревью, ни дашборд, ни алерт. Карта обязана нести имя, по которому метрику реально ищут.
Допустимы символы Prometheus: [a-zA-Z_:][a-zA-Z0-9_:]*. Дополнительно имя должно давать корректный Go-идентификатор, потому что из него строится переменная коллектора (var SpawnErrorsTotal = …). _ и : при этом сворачиваются, поэтому требуется, чтобы первый символ после ведущих _ и : был буквой:
"_"или"::"— после сворачивания не остаётся идентификатора;"_123_total"— Prometheus такое имя примет, но идентификатор получился бы123Total, а Go не разрешает начинать его с цифры.
Оба случая — ошибка генерации с указанием объявления, а не синтаксическая ошибка в сгенерированном пакете.
type — конструктор¶
type |
Коллектор | Метки |
|---|---|---|
Counter |
prometheus.Counter |
нет |
CounterVec |
prometheus.CounterVec |
обязательны |
Gauge |
prometheus.Gauge |
нет |
GaugeVec |
prometheus.GaugeVec |
обязательны |
Histogram |
prometheus.Histogram |
нет |
HistogramVec |
prometheus.HistogramVec |
обязательны |
Summary |
prometheus.Summary |
нет |
SummaryVec |
prometheus.SummaryVec |
обязательны |
Метки у не-Vec типа и отсутствие меток у Vec — ошибка генерации, а не молчаливое исправление.
labels — метки серии¶
Принимаются обе формы:
Проверяются: грамматика Prometheus ([a-zA-Z_][a-zA-Z0-9_]*), отсутствие дублей, отсутствие префикса __ (зарезервирован самим Prometheus).
help — текст для Prometheus¶
Обязателен. Это проза, которая уезжает в чужой Prometheus и которую читает человек, не знающий ваш трекер: номерам задач и внутренним сокращениям здесь не место. Карта — заодно и то место, где такой текст видно и можно отревьюить; в конструкторе посреди кода его не видит никто.
buckets — только для Histogram / HistogramVec¶
- name: task_duration_seconds
type: HistogramVec
labels: kind, outcome
help: Wall-clock duration of a task.
buckets: [0.05, 0.25, 1, 5, 30]
Не указаны — используется prometheus.DefBuckets. Указаны у не-гистограммы — ошибка. Значения должны строго возрастать.
objectives — только для Summary / SummaryVec¶
Отображение «квантиль → допустимая погрешность», как в prometheus.SummaryOpts:
- name: batch_size
type: Summary
help: Number of records in a processed batch.
objectives: {0.5: 0.05, 0.99: 0.001}
Не указаны — nil, то есть поведение client_golang по умолчанию: метрика несёт только _sum и _count, без квантилей. Выдумывать квантили за вас генератор не станет — это такое же решение, как порог алерта.
external — метрика из сторонней библиотеки¶
- name: otel_sdk_exporter_spans_total
type: CounterVec
labels: outcome
help: Spans handed to the OTLP exporter, by outcome.
external: true
external: true означает «метрику эмитит библиотека, не сервис». Коллектор не генерируется, но запись:
- занимает своё имя в общем пространстве имён (то есть сервис не сможет его затенить);
- попадает в дашборд.
Это нужно для метрик OTEL SDK, драйверов БД и всего остального, что инструментирует себя само. Без этого поля такие метрики пришлось бы прятать от карты, и карта перестала бы быть полным списком.
Сгенерированный пакет коллекторов¶
Генерируется в internal/pkg/metrics/psg_metrics_gen.go — по одной экспортируемой переменной на объявленную метрику:
// SpawnErrorsTotal — Spawn attempts that failed, by reason and stage.
//
// Metric: spawn_errors_total (CounterVec), labels: reason, stage
var SpawnErrorsTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "spawn_errors_total",
Help: "Spawn attempts that failed, by reason and stage.",
},
[]string{"reason", "stage"},
)
Имя переменной — name в PascalCase: spawn_errors_total → SpawnErrorsTotal. Символ : свёртывается так же, как _; если два объявленных имени свернутся в один Go-идентификатор, генерация падает, а не создаёт одну переменную на двоих.
Использование в коде сервиса:
import "github.com/org/myservice/internal/pkg/metrics"
metrics.SpawnErrorsTotal.WithLabelValues("timeout", "init").Inc()
metrics.QueueDepth.Set(float64(len(queue)))
Регистрация¶
Пакет отдаёт три функции:
func Collectors() []prometheus.Collector
func Register(reg prometheus.Registerer) error
func Unregister(reg prometheus.Registerer)
Registerer явный, а коллекторы создаются через prometheus.New*, не через promauto — то есть сами в дефолтный регистр не лезут. Это то, что нужно тестам (свой выбрасываемый registry на кейс) и нескольким приложениям в одном бинарнике.
Вызов проставляется автоматически в cmd/<app>/psg_main_gen.go рядом с существующим application.InitMetrics — для приложений, у которых есть sys-транспорт (то есть эндпоинт /metrics):
В тестах:
reg := prometheus.NewRegistry()
require.NoError(t, metrics.Register(reg))
defer metrics.Unregister(reg)
Валидатор¶
Объявление становится несущим только вместе с парным запретом: конструкторы метрик вне сгенерированного пакета запрещены. Иначе рядом со сгенерированными переменными всегда можно объявить ещё один promauto.NewCounter, и карта вырождается в договорённость.
Запрет реализован правилами forbidigo и генерируется в двух местах:
configs/golangci-metrics.yml+ цельmake metrics-validate— основной гейт;configs/golangci-lint.yml— те же правила, чтобыmake lintловил типовой случай сразу.
internal/app/svc/svc.go:9:14: use of `prometheus.NewCounter` forbidden because
"metric constructors are not allowed here: declare the metric in the metrics
map instead — the generated collector package is the only place metrics are
constructed" (forbidigo)
Что запрещено¶
| Форма | Пример |
|---|---|
| Конструкторы коллекторов | prometheus.NewCounter, NewGaugeVec, NewHistogram, NewSummaryVec, NewCounterFunc, … |
| Низкоуровневые конструкторы | prometheus.NewDesc, NewConstMetric, NewConstHistogram, NewConstSummary, … |
promauto целиком |
promauto.NewCounter, promauto.With(reg).NewCounter |
prometheus.NewDesc в списке не случайно: это позиционная форма (NewDesc(name, help, …)), которой пользуются кастомные коллекторы со своими Collect/Describe. Правило, знающее только prometheus.CounterOpts{…}, оставляло бы дыру ровно там, где пишут нестандартное.
Почему правила не обходятся алиасом импорта¶
Оба конфига ставят forbidigo: analyze-types: true. Это не косметика: по умолчанию forbidigo сравнивает паттерн с текстом вызова, как он написан, а паттерны называют пакет (^prometheus\.New…). Без резолва типов мимо запрета проходят обе переименованные формы:
import prom "github.com/prometheus/client_golang/prometheus"
var sneaky = prom.NewCounter(prom.CounterOpts{Name: "undeclared_total", Help: "…"})
import . "github.com/prometheus/client_golang/prometheus"
var sneaky = NewCounter(CounterOpts{Name: "undeclared_total", Help: "…"})
С analyze-types: true вызов резолвится до настоящего пакета, и обе формы ловятся тем же правилом. Гейт, который обходится переименованием импорта, гейтом не является, — поэтому флаг относится к сути запрета, а не к его настройкам.
Побочное следствие: валидатору нужна информация о типах, то есть проект должен компилироваться. Для make metrics-validate это не ограничение — цель и так запускается после генерации, как и make lint.
Что НЕ запрещено и почему¶
Литералы опций — prometheus.CounterOpts{Name: …, Help: …} — не запрещены намеренно: сами по себе они ничего не эмитят. Без вызова конструктора коллектора метрики из них не получится, поэтому запрета вызовов достаточно, чтобы закрыть дыру полностью.
Исключения¶
Из проверки выведены два пути, и только они:
internal/pkg/metrics/— сгенерированный пакет, где метрики и должны конструироваться;pkg/drivers/kafka/— сгенерированный драйвер Kafka-продюсера: имя продюсера тамConstLabel, поэтому каждому продюсеру нужны свои коллекторы, а не общая переменная уровня пакета.
Оба файла генерируются целиком из объявления — руками их не правят.
configs/golangci-metrics.yml ставит exclusions.generated: disable, а не lax, как основной конфиг. Это и есть смысл отдельного конфига: при lax из проверки выпадает любой psg_*_gen.go, включая секцию ручного кода ниже disclaimer-маркера, — а это ровно то место, где пишут хэндлеры. Поэтому гейт — make metrics-validate, а не make lint.
make metrics-validateстоит подключить в CI-пайплайн проекта. Объявляемый список CI-проверок ведётся отдельно (TOOLS-10).
Дашборд¶
В дев-дашборд (configs/grafana/dashboards/<app>.json) добавляется свёрнутый ряд Service Metrics с канонической панелью на каждую объявленную метрику:
| Тип | Запрос |
|---|---|
Counter / CounterVec |
rate(...), с разбивкой по объявленным меткам |
Gauge / GaugeVec |
само значение |
Histogram / HistogramVec |
histogram_quantile p99 и p95 по _bucket |
Summary / SummaryVec с objectives |
серия по метке quantile |
Summary / SummaryVec без objectives |
среднее rate(_sum) / rate(_count) — это всё, что метрика несёт |
«Канонический» — значит «та форма, которая следует из типа метрики». Больше без знаний об инсталляции сказать нельзя, поэтому пороги и алерт-правила не генерируются: порог завязан на ёмкость конкретной инсталляции, и сгенерированный был бы выдуманным.
Метрики, у которых уже есть рукописный ряд — go_*, process_*, ogen_server_*, ogen_client_* — в Service Metrics не дублируются: те ряды знают о своих метриках больше, чем форма, выведенная из типа. Объявить их в карте всё равно полезно (имя занято, help отревьюен), просто второй, более бедной панели они не получают.
Внутренний набор генератора¶
Свои метрики go-project-starter описывает той же картой, внутри себя (internal/pkg/metricsmap/embedded/internal-metrics.yaml): Go-рантайм, инструментирование ogen, метрики Kafka-продюсера. Форма объявления одна на всех, а не две.
Наборы складываются в одно пространство имён, и совпадение имён — ошибка генерации, а не переопределение:
metrics map: metric name collision:
"go_goroutines" declared by both go-project-starter internal metrics[0]
and service metrics map[3]
Молчаливое переопределение означало бы, что имя в /metrics зависит от порядка слияния, — а имя метрики это то, на что смотрят дашборды и алерты.
Внутренний набор фильтруется по тому, что в проекте реально есть: без Kafka-продюсера метрики kafka_producer_* не объявляются вовсе. Это работает в обе стороны — метрика, которую в этом проекте нечем эмитить, не занимает имя против сервиса и не получает панель, которая может только пустовать.
Поля owner и requires, которыми это выражено, зарезервированы за внутренней картой и в карте сервиса отвергаются.
Чего генератор не делает¶
Намеренно вне scope:
- Пороги и алерт-правила. Порог завязан на ёмкость конкретной инсталляции, а обоснование порога — это решение, и его место рядом с решением.
- Прод-дашборды. Они живут в мониторинг-репозитории потребителя, их правят руками и осознанно. Сгенерированный, но редактируемый артефакт — это «второй дом»: его правят на месте, и он расходится с генератором молча.
- Доставка админской части наружу (складывать дашборды в
etc/для инфраструктурного репозитория).
Полный пример¶
# project.yaml
metrics:
path: git+https://github.com/org/contracts.git@v1.4.0#common/metrics-map.yaml
# common/metrics-map.yaml в контрактном репозитории
metrics:
- name: spawn_errors_total
type: CounterVec
labels: reason, stage
help: >-
Spawn attempts that failed, by reason and stage.
- name: queue_depth
type: Gauge
help: Number of tasks currently waiting in the queue.
- name: task_duration_seconds
type: HistogramVec
labels:
- kind
- outcome
help: Wall-clock duration of a task, by kind and outcome.
buckets: [0.05, 0.25, 1, 5, 30]
- name: batch_size
type: Summary
help: Number of records in a processed batch.
objectives: {0.5: 0.05, 0.99: 0.001}
- name: otel_sdk_exporter_spans_total
type: CounterVec
labels: outcome
help: Spans handed to the OTLP exporter, by outcome.
external: true
Диагностика¶
| Сообщение | Причина |
|---|---|
invalid metrics map: the file is empty |
карта пустая (или в ней только пробелы) |
invalid metrics map: metrics[2]: name "has-a-dash" is not a valid Prometheus metric name |
дефис в имени метрики |
invalid metrics map: metrics[0]: name "_" leaves no Go identifier once '_' and ':' are folded away |
имя из одних разделителей: Prometheus такое примет, а Go-идентификатора не остаётся |
invalid metrics map: metrics[0]: name "_123_total" generates the Go variable 123Total, which starts with a digit |
ведущий _ или : перед цифрой: после сворачивания идентификатор начинается с цифры |
invalid metrics map: metrics[1]: type CounterVec requires labels; use Counter for a metric without labels |
Vec-тип без labels |
invalid metrics map: metrics[0]: buckets are only valid for Histogram/HistogramVec, not Counter |
buckets не у гистограммы |
invalid metrics map: metrics[4]: help is required |
нет help |
invalid metrics map: line 7: unknown field "lables" |
опечатка в имени поля: молча проигнорированный ключ — это объявление, которое не действует |
metric name collision: "x" declared by both …internal metrics[n] and service metrics map[m] |
имя уже занято внутренним набором генератора |
metric variable name collision: "queue:depth" and "queue_depth" both generate the variable QueueDepth |
два имени сворачиваются в один Go-идентификатор |
invalid metrics map: metrics[0] (x):owneris reserved for the generator's internal map |
owner/requires в карте сервиса |
Валидация сообщает все проблемы сразу: починка плохой карты занимает один проход, а не по одному на запись.