Инструментирование метрики

Открой исходники github.com/go-kit/kit/metrics — там три интерфейса, и весь дизайн наблюдаемости курса держится на них. Counter описывает монотонно растущую величину: Add(delta float64) и ничего больше — уменьшать счётчик нельзя по определению; типичный пример — число принятых запросов. Gauge принимает конкретные значения в моменте: Set(value) и Add(delta) — глубина очереди, число активных соединений, температура. Histogram повторяет наблюдения одного типа величины — Observe(value float64) — и сводит их в статистику: buckets или quantiles; штатный пример из доков — латентность HTTP-запросов. Каждый интерфейс начинается с метода With(labelValues ...string), возвращающего инструмент с привязанными метками — про него ниже. Почему это не интерфейсы prometheus напрямую: контракт go-kit метрики принадлежит твоему коду, а реализация — подключаемая. В пакете есть реализации для Prometheus, DogStatsD, InfluxDB, Graphite; stringsvc компилируется против любой из них, не меняя ни строки в middleware. Это тот же ход, что и endpoint: одна сигнатура — много транспортов, поэтому go kit метрики выглядят одинаково в любом бэкенде.

Метод With(labelValues...) возвращает новый инструмент с привязанными значениями меток, объявленных при создании: requestCount.With("method", "uppercase", "error", "false").Add(1) увеличит одну конкретную серию, не трогая остальные. Пары идут в том же порядке, что и fieldKeys при объявлении, — перепутал порядок, и error получит значение uppercase, без паники и без предупреждения. Метки — способ разрезать одну метрику на осмысленные срезы: по методу, по исходу, по коду ответа. А теперь правило, которое спасает от продовых инцидентов: кардинальность. Каждая уникальная комбинация значений меток — отдельная серия в памяти Prometheus и в твоём сервисе; label из user_id, IP или uuid превращает счётчик в миллионы серий, которые никто не читает, но все собирают. Метка должна быть категорией с коротким списком значений: method — два значения, error — два, статус-код — десяток. Если хочешь копнуть в конкретного пользователя — это работа логов из урока 06 и request_id, а не метрик. Граница простая: метрики отвечают «сколько и как быстро», логи — «что именно случилось».

Разберём middleware по косточкам, потому что здесь три решения, которые определяют качество всей наблюдаемости. Первое — что такое ошибка. Канал err endpoint'а несёт инфраструктурные сбои: дедлайн, недоступная база, сломанный декодер. Бизнес-ошибки из урока 02 едут в Err-поле response через Failer и по каналу err не проходят — middleware, считающая только err != nil, честно рапортует error=false клиенту, получившему 400. Проверка response.(endpoint.Failer) в defer закрывает дыру: failed — это объединение двух каналов. Второе — единицы латентности: time.Since(begin).Seconds() даёт float64 в секундах, и это конвенция Prometheus; суффикс _seconds в имени метрики не украшение, а обязательная часть контракта. Третье — где считать: на endpoint'е, а не в сервисе и не в декодере. Endpoint-middleware видит и request, и response, и err, транспорт-агностичен и одинаково работает для HTTP сегодня и gRPC из урока 13 завтра; сервисный уровень для метрик пригодится в уроке 15, когда захочется доменных величин вроде числа сохранённых профилей.

Смонтировали — посмотрим глазами Prometheus. request_count — счётчик, и его сырое значение почти бесполезно: интересен темп, поэтому в запросах к Prometheus счётчики оборачивают в rate(): rate(stringsvc_string_service_request_count[5m]) — среднее число запросов в секунду за пять минут; разделив по метке error=true, получишь долю сбоев без единой строчки своего кода. Гистограмма богаче: клиент Prometheus сам считает sum и count и раскладывает наблюдения по бакетам; запросы идут по серии _bucket с меткой le (less or equal). Латентность p90: histogram_quantile(0.9, sum(rate(stringsvc_string_service_request_duration_seconds_bucket[5m])) by (le)) — стандартное заклинание, которое стоит один раз записать в дашборд. Аптайм-алерты строятся на тех же сериях: резкий скачок p99 или обнуление rate() подскажут о деградации раньше пользователей. Почему гистограмма, а не среднее: среднее прячет хвосты, а хвосты — где страдают пользователи; p90 говорит «90 процентов запросов быстрее этого». Дефолтные DefBuckets покрывают диапазон от миллисекунд до десятков секунд — для старта достаточно, а под свой профиль бакеты настраиваются в HistogramOpts. Summary — альтернатива с готовыми квантилями на клиенте (NewSummaryFrom, его использует канонический stringsvc из репозитория go-kit), но summary нельзя агрегировать между инстансами — поэтому современный дефолт курсов и платформ: histogram.

Справедливый вопрос: клиент github.com/prometheus/client_golang и так умеет CounterVec и HistogramVec — зачем ещё один слой? Причин три, и все они видны в коде middleware. Первая — интерфейсы: instrumentingMiddleware принимает metrics.Counter, а не *prometheus.CounterVec; подменить бэкенд — заменить конструктор в main, middleware компилируется как есть. Вторая — единый With: в клиенте Prometheus метки передаются при каждом вызове cv.With(lvs).Inc(), и сигнатуры различаются между типами; в go-kit With возвращает новый инструмент — выражение requestCount.With(lvs...).Add(1) читается одинаково для counter, gauge и histogram. Третья — чистота слоёв: домен и endpoint не знают ни о prometheus, ни о любых других клиентах — зависимость от инфраструктуры живёт только в main, как и должно быть по слоям из урока 01. Плата честная: тонкая обёртка и один порядок лейблов, который надо соблюдать. Для микросервисной команды, где сервисов десятки, посредник экономит больше, чем стоит — а тестам он достаётся бонусом: подмени metrics.Counter фейковым счётчиком в памяти, и middleware проверяется без Prometheus и без сети.

Третий наблюдательный слой встал на место: три интерфейса, объявление серий в main, instrumenting middleware рядом с loggingMiddleware и /metrics для Prometheus. Обещание урока 04 про ServerAfter выполнено с запасом: считай хоть на endpoint-обёртке, хоть через хук транспорта — измеряется одно и то же. Освежить устройство обёрток можно в уроке 02-endpoint, опции транспорта — в уроке 04-http-transport, кодеки — в уроке 05-codeki, а пару к метрикам — в уроке 06-logirovanie; карта курса — на странице курса. Дальше — урок 08-tracing: трейсинг через endpoint middleware, Jaeger, спаны, которые свяжут все три слоя наблюдаемости одним trace id. А после трейсинга — расширенная механика поверх обёрток: rate limiting и circuit breaker, про которые endpoint из урока 02 уже намекнул.