Histogram: латентность и bucket'ы

Представьте два сервиса с одинаковой средней латентностью 120 мс. У первого всё ровно: минимум 80, максимум 180. У второго девять запросов из десяти укладываются в 40 мс, а десятый висит две секунды. Средняя одинаковая — опыт пользователей противоположный. Среднее скрывает форму распределения, а форма и есть главное: медиана показывает типового пользователя, p99 — самого несчастливого из ста, и именно его словами описывают SLO. Обычный Counter здесь бессилен: он умеет только инкременты и не помнит, сколько длился каждый запрос. Histogram решает задачу хитрее: приложение не хранит каждое наблюдение, а раскладывает значения по заранее заданным интервалам — бакетам — и отдаёт Prometheus накопленные счётчики по каждому интервалу. Квантиль считается уже из этих счётчиков, в момент запроса. Компромисс виден сразу: сырые значения теряются, точность ограничена границами бакетов — и границами придётся управлять, это половина урока.

Создаётся гистограмма функцией prometheus.NewHistogram с HistogramOpts, где кроме Name и Help задаётся Buckets — возрастающая сетка границ в секундах. Если её не указать, возьмётся prometheus.DefBuckets: одиннадцать значений от 5 мс до 10 секунд, сетка заточена под типичный веб-сервис. Наблюдение — один вызов hist.Observe(value); передавать принято секунды float64, поэтому у времени ответа пишут time.Since(start).Seconds(). Observe потокобезопасен: его можно звать из любого числа горутин без мьютекса, внутри атомарные операции. Паттерн в хендлере одинаковый всегда: запомнить время в начале, отдать ответ, наблюдать разницу — удобнее всего это делает middleware, про готовые обёртки promhttp будет девятый урок. Здесь пример держим ручным, чтобы была видна механика: замер — это две строки вокруг вашей бизнес-логики, всё остальное берёт на себя client_golang.

DefBuckets — это {0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10} секунд. Обратите внимание на пропорцию: сетка логарифмическая, каждый шаг в полтора-два с половиной раза шире предыдущего, потому что латентности живут на порядках. Но она полезна только сервису, у которого время ответа реально лежит от десятков миллисекунд до секунд. Быстрому API, где всё заканчивается за 40 мс, девять из одиннадцати бакетов не пригодятся, а p99 посчитается грубо. Медленной генерации отчётов, наоборот, нужна сетка выше десяти секунд. Свои границы задаются слайсом float64 по возрастанию — либо хелперами: prometheus.LinearBuckets(start, width, count) даёт равномерную сетку, prometheus.ExponentialBuckets(start, factor, count) — экспоненциальную. Учтите: границы зашиты в релиз. Поменять сетку на живом дашборде нельзя, а после смены графики получат разрыв, потому что счётчики стартуют заново. Планируйте сетку под свой SLO, а не копируйте дефолт по привычке.

Инцидент, который стоит знать до первого дашборда с p99. В одном сервисе замер писали в миллисекундах: Observe(float64(elapsed.Milliseconds())) при сетке DefBuckets от пяти миллисекунд до десяти секунд. Почти все наблюдения попадали в первый бакет: p99 показывал стабильные пять миллисекунд, график был образцово зелёным, а пользователи жаловались на медленный поиск. Ошибка интерпретации в обратную сторону: график честен — врать стали единицы. Диагностика заняла минуты, когда кто-то посмотрел на сырые бакеты: le=0.005 равнялся le=+Inf, значит, весь трафик быстрее первой границы — либо сервис летает, либо мера не в тех единицах. Противоядие: секунды и time.Since(start).Seconds() по умолчанию; если единица другая — она обязана быть в имени метрики. Проверку le=+Inf равно _count вы уже знаете — она же проверка здравого смысла, и этой истории она бы хватило.

Гистограмма экспортирует три семейства серий. Первое — _bucket с лейблом le: для каждой границы — накопленное число наблюдений, которые были меньше либо равны ей, включая последний псевдобакет le="+Inf", равный общему числу наблюдений. Кумулятивность важна: это не «сколько попало в интервал», а «сколько не превысило границу с начала процесса»; разность соседних бакетов даёт интервал. Второе — _sum: сумма всех наблюдений. Третье — _count: их количество. Средняя латентность считается делением sum на count без всяких квантилей, а p99 — функцией histogram_quantile в PromQL: она находит бакет, в котором лежит квантиль, и интерполирует внутри него. Всё это считается на стороне сервера Prometheus в момент запроса. Следствие приятное: можно менять запросы, срезать по любым лейблам и агрегировать инстансы, не трогая ни строчки Go-кода — к этому свойству мы ещё вернёмся в следующем уроке, потому что summary ведёт себя ровно наоборот.

Спорное мнение с границей: в большинстве сервисов сетку не надо трогать. Дефолтные одиннадцать границ критикуют за грубость, забывая, зачем квантиль вообще существует: p99 нужен не для физики, а для решений — сравнить релизы, поймать деградацию, проверить цель по надёжности. Для этих задач важно, чтобы граница лежала рядом с целевым значением, а не чтобы квантиль сходился до четвёртого знака. Я сужаю сетку в двух случаях: быстрый внутренний API, где весь трафик живёт в первом бакете, и фоновые задачи с хвостом за десять секунд. И не сужаю «на всякий случай»: тридцать границ утраивают объём серий, а выигрыш достаётся интерполяции, которой никто не доверяет. Граница спора проста: если у вас есть цель в миллисекундах и алерт по ней — сетка под неё; если есть только любопытство — оставьте дефолт и потратьте время на что-то другое.

Вариация примера, расширяющая применение: гистограмма не обязана мерить секунды. Размер ответа в байтах — тот же Observe с сеткой LinearBuckets от тысячи до шестидесяти четырёх тысяч: из неё получаются медианный размер страницы и хвост тяжёлых выгрузок, которые раздувают трафик. Число элементов в пачке — ExponentialBuckets от единицы: видно, как часто очередь таскает по одной задаче вместо сотни. Даже возраст данных в кэше влезает в распределение. Правило единственное: единица измерения — в имени метрики, а сетка — по реальному диапазону величины, который проще всего снять с продовых данных за неделю. После этого распределения вроде размерных перестают быть экзотикой и становятся обычным инструментом наравне с латентностью.