Метрики HTTP: InstrumentHandler

Пакет promhttp умеет оборачивать http.Handler готовыми слоями, и у всех один знаменатель сигнатуры: InstrumentHandlerX(метрика, next http.Handler) http.Handler. Метрика — не любая, а подходящего типа: счётчику запросов нужен CounterVec с лейблами code и method, гистограмме длительности — HistogramVec с теми же лейблами, in-flight — одиночный Gauge без лейблов. Обёртки проставляют значения сами: код ответа они достают из перехваченного WriteHeader, метод — из запроса, поэтому в хендлерах не появляется ни одной строки про метрики. Слои гнездятся: внешний замеряет длительность, внутренний считает запросы. Объявите в векторе ровно те лейблы, которые слой умеет заполнять: лишний или недостающий — и первый же запрос упадёт паникой inconsistent label cardinality. Поэтому новые связки обкатывают на стенде, а не в проде, и первым тестом после добавления слоя делают обычный прогон хендлера с чтением /metrics.

Слои можно менять местами, и от порядка зависит семантика. Внешний замер длительности включает всё, что внутри: работу счётчика, логи, сам хендлер — так и надо, потому что латентность для пользователя одна. Если поставить замер внутрь, между счётчиком и хендлером, цифра почти не изменится: накладные расходы обёрток ничтожны по сравнению с сетью, но принципиальная схема остаётся — чем ближе слой к пользователю, тем полнее он видит время. С готовыми слоями порядок роли почти не играет; со своими — играет: middleware, который снимает лейбл маршрута, должен стоять после роутера, иначе маршрут ещё не сопоставлен и в лейбл уйдёт пустая строка. Композиция — сильная сторона net/http: recovery сверху, метрики под ним, свой лейбл маршрута ещё ниже — и каждый слой делает ровно одно дело, не зная о соседях.

Инцидент, из которого выросло правило этого урока. Сервис под нагрузкой начал паниковать в одном хендлере: recovery перехватывал панику, писал 500, и всё выглядело штатно — доля ошибок в метриках почти не менялась, а поддержка была завалена жалобами. Причина: замер в middleware стоял после next.ServeHTTP, до которого паника не доживала, — Observe не выполнялся, и пятисотые ответы в гистограмме отсутствовали. Ошибка двойная: замер без defer и отсутствие отдельного счётчика ошибок. Чинится двумя строками: Observe в замыкании defer и инкремент при коде пятой сотни. Мораль шире кода: слой, который обещает метрики всем маршрутам, обязан метить и аварийные ответы — иначе самый интересный трафик, ради которого и ставят мониторинг, проходит мимо распределения молча. Проверьте это на стенде: хендлер с паникой — и посмотрите, какая серия родилась. Счётчик http_errors_total рядом с гистограммой — минимальный страховочный полис: когда два числа расходятся, виноват слой, который врёт.

Готовые слои знают про code и method, и всё. Как только появляется собственное измерение — шаблон маршрута, идентификатор тенанта, флаг эксперимента, версия API в заголовке, — наступает время собственной обёртки по образцу выше. Скелет всегда один: подменить ResponseWriter обёрткой, запоминающей статус; замерить время вокруг next.ServeHTTP; вычислить лейблы; отдать наблюдение нужному Observer. Три тонкости, на которых спотыкаются. Статус по умолчанию — 200: если хендлер не вызвал WriteHeader явно, в метрике должен оказаться 200, как и в реальном ответе. Паника в хендлере: если замер стоит после next.ServeHTTP без defer, 500-е от recovery-слоя никогда не попадут в гистограмму — а это самые интересные значения. Лейбл маршрута берите из роутера после сопоставления: в chi это chi.RoutePattern(r), в gin — c.FullPath(), и оба вернут пустую строку, если слой стоит выше маршрутизации. Шаблон, а не сырой путь: о кардинальности путей мы подробно говорили в уроке про лейблы.

График in-flight обманывает всех, кто видит его впервые: рост линии читают как рост трафика. Не всегда. In-flight — число запросов в обработке прямо сейчас, и его рост означает произведение двух величин: пришедшего трафика и времени обработки. Трафик ровный, а линия ползёт вверх — значит, запросы обрабатываются дольше: заблокировалась база, завис внешний вызов, кончился пул соединений. Это самый ранний сигнал деградации — раньше пятисотых и роста p99: пул ещё держится, но свободных слотов всё меньше, и метрики горутин вскоре покажут то же самое. Практика: на панели in-flight рисуйте рядом rate запросов — если линии расходятся, виновата латентность, а не наплыв. Вторая крайность — паника на всякий рост: пик-час законно поднимает линию втрое; сравнивайте с прошлой неделей, а не с прошлым часом. Сама метрика почти бесплатна: пара атомарных операций на запрос.

Спорное мнение, с которым согласны не все: в сервисе со своим роутером и логикой я чаще пишу один собственный middleware, чем собираю три готовых слоя. Аргумент: своя обёртка сразу даёт то, ради чего всё затевалось, — шаблон маршрута в лейбле, единые имена метрик, замер в defer, — а готовые слои дают code и method, после чего их всё равно приходится дополнять. Две обёртки поверх одной — двойной перехват WriteHeader и два места, где можно ошибиться. Граница, где мнение меняется: новый сервис без собственных измерений и прототип — берите InstrumentHandlerCounter и InstrumentHandlerDuration, это двадцать секунд работы и меньше собственного кода в ревью. Правило разветвления простое: как только появился первый собственный лейбл, весь HTTP-слой собирается в одном месте, а не в трёх разных. И один свой middleware проще объяснить новому человеку в команде, чем композицию из трёх обёрток.