Метрики, перцентили и SLO

Четыре типа метрик: бери тот, что отвечает на твой вопрос

Метрика — это не строка лога и не span. Это число, семплируемое во времени и агрегируемое на стороне сервера: дёшево хранить, дёшево запрашивать, и именно по нему ты строишь алерты. Prometheus даёт четыре типа, и неверный выбор — первая ошибка.

import { Counter, Gauge, Histogram } from 'prom-client';

// COUNTER: монотонен, только растёт (или сбрасывается в 0 при рестарте).
// Сырое значение не читают — запрашивают rate() по нему.
const httpRequests = new Counter({
  name: 'http_requests_total',
  help: 'Total HTTP requests',
  labelNames: ['method', 'route', 'status'] as const, // НИЗКАЯ кардинальность — см. ниже
});

// GAUGE: значение, которое растёт И падает — снимок «прямо сейчас».
const inFlight = new Gauge({
  name: 'http_requests_in_flight',
  help: 'Requests currently being served',
});

// HISTOGRAM: бакетизирует наблюдение (здесь — длительность) в заранее заданные бакеты,
// чтобы вычислять квантили НА СТОРОНЕ СЕРВЕРА по всем инстансам.
const httpDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'Request duration in seconds',
  labelNames: ['method', 'route', 'status'] as const,
  buckets: [0.01, 0.05, 0.1, 0.3, 0.5, 1, 2, 5], // boundaries decide p99 accuracy
});

Counter монотонен — суммы запросов, суммы ошибок. Ты никогда не рисуешь сырое число; ты рисуешь rate(http_requests_total[5m]), чтобы получить запросы-в-секунду. Gauge ходит в обе стороны — in-flight запросы, использование памяти, глубина очереди, размер пула соединений: снимок, который ты читаешь напрямую. Histogram кладёт каждое наблюдение в бакет; поскольку бакеты живут на сервере, ты можешь посчитать histogram_quantile(0.99, …) и, что критично, сначала сложить бакеты по всем своим инстансам, а потом взять квантиль. Четвёртый тип — summary — считает квантили на стороне клиента в каждом процессе, а значит, их нельзя агрегировать: p99 трёх инстансов — это не среднее их трёх p99. В любом мультиинстансном сервисе предпочитай гистограммы.

В Nest ты подключаешь это через @willsoto/nestjs-prometheus (или сырой prom-client), выставляешь эндпоинт /metrics для скрейпа Prometheus и записываешь длительности в интерсепторе, оборачивающем каждый запрос: запускаешь таймер в intercept, останавливаешь его в tap/finalize observable, размечая по методу, шаблону маршрута и статусу.

RED и golden signals: что на самом деле мерить

Ты не меряешь всё; ты меряешь горстку сигналов, которые говорят, здоров ли сервис. Для request-driven сервиса спина — это метод RED: Rate (запросов в секунду, из counter), Errors (упавших запросов в секунду, тот же counter, отфильтрованный по 5xx), Duration (распределение задержки, из histogram). Четыре golden signals от Google добавляют saturation (насколько полон самый загруженный ресурс) к latency, traffic и errors. USE (Utilization, Saturation, Errors) — это зеркало со стороны ресурсов: применяй к CPU, памяти, диску, пулу соединений. RED для пути запроса, USE для ресурсов, на которые он опирается.

Перцентили: среднее лжёт, меряй хвост

Вот ключевой инсайт, на котором держится инцидент из начала. Среднее время ответа прячет аварию, которую обнажает p99. Среднее в 80ms может сидеть поверх p99 в две секунды, потому что среднее доминируется массой быстрых запросов, и небольшой медленный хвост едва его подталкивает. Но этот хвост — не шум, это реальные пользователи, и это ровно та когорта, что упирается в таймауты, запускает ретраи и усиливает нагрузку. SLO на среднее — это SLO на неверное число.

# PromQL: p99 latency на маршрут, агрегированная по ВСЕМ инстансам.
# sum by (...) — ПЕРЕД histogram_quantile — именно поэтому histogram, а не summary:
# сначала складываем бакеты, потом берём квантиль.
histogram_quantile(
  0.99,
  sum by (le, route) (rate(http_request_duration_seconds_bucket[5m]))
)

Поэтому ты отслеживаешь p50 (типичный пользователь), p95 и p99 (хвост, который болит) и p999, когда трафик достаточно велик, чтобы один-из-тысячи был ощутимым числом людей. Одна оговорка: квантиль гистограммы Prometheus хорош ровно настолько, насколько хороши границы твоих бакетов. histogram_quantile линейно интерполирует внутри того бакета, в который попадает квантиль, так что если твой p99 ложится между бакетами 1s и 5s, отчётное значение — это догадка где-то в этом промежутке, возможно сильно неверная. Ставь границы бакетов там, где тебе реально важно (вокруг порога твоего SLO), а не на круглых числах.

Кардинальность: метка, которая кладёт Prometheus

Это тот режим отказа, что убивает саму систему мониторинга. В Prometheus каждая отдельная комбинация значений меток — это свой временной ряд, хранимый и индексируемый отдельно. http_requests_total{method="GET", route="/users/:id", status="200"} — это один ряд; измени любое значение метки — получишь другой. Это нормально, пока метки ограничены: горстка методов, пара десятков маршрутов, несколько классов статусов, так что произведение — может, несколько сотен рядов.

Это становится катастрофой в момент, когда ты вешаешь на метрику высококардинальную метку: userId, requestId, email или сырой path, в который вшиты id. Метка userId означает один ряд на пользователя — миллион пользователей — это миллион рядов на метрику, у каждого своя память и своя запись в индексе. Prometheus держит head-ряды в RAM; взрыв кардинальности уводит сервер в OOM, раздувает время скрейпа и хранилище и кладёт мониторинг ровно тогда, когда он тебе нужен.

// БОМБА КАРДИНАЛЬНОСТИ — сырой путь со вшитыми id = один ряд НА каждый id.
// /users/1, /users/2, … /users/9999999 → миллионы различных значений метки.
httpRequests.inc({ method: 'GET', route: req.path, status: '200' });
// напр. route="/users/8f3a-...-91/orders/4412"  ← неограничен, уникален на запрос

// БЕЗОПАСНО — сворачивай до ШАБЛОНА маршрута; id — в значении, а не в метке.
httpRequests.inc({ method: 'GET', route: '/users/:id/orders/:orderId', status: '200' });

Правило: метки должны быть низкокардинальными и ограниченными — метод, шаблон маршрута (а не сырой путь), класс статуса. Когда возникнет соблазн добавить метку userId или requestId, чтобы «докопаться» до отдельного пользователя — остановись: этот id принадлежит трейсу или строке лога, а не измерению Prometheus. То, что тебя тянет положить в метку (id пользователя, id запроса), принадлежит трейсу или строке лога, а не измерению метрики. Военная история банальна и распространена: кто-то разметил http_requests по полному URL, включая литеральные id /users/{id}, число рядов взорвалось, Prometheus съел всю свою RAM и упал — а дашборд погас посреди инцидента.

SLO и бюджет ошибок: то, по чему ты алертишь

SLO — это цель: «99.9% запросов оформления завершаются быстрее 300ms, измеряется за 30 дней». Его зеркальное отражение — бюджет ошибок, те 0.1%, что тебе разрешено промахнуть. Этот бюджет — не отказ, которого надо избегать; это ресурс, который надо тратить. Прожигаешь медленно — у тебя есть простор катить фичи и рисковать; прожигаешь быстро — замораживаешь деплои и чинишь надёжность. И ты алертишь не на сырое число ошибок — горстка ошибок в 3 ночи — это шум. Ты алертишь на скорость прожига: насколько быстро ты потребляешь бюджет. Скорость прожига, которая исчерпала бы 30-дневный бюджет за час, — это пейдж; та, что заняла бы неделю, — тикет. Это разница между «разбудить человека» и «не будить».