Summary против Histogram

NewSummary принимает SummaryOpts; ключевой параметр — Objectives, карта вида map[float64]float64{0.99: 0.001}. Ключ — целевой квантиль, значение — допустимая погрешность: 0.001 означает, что заявленное число лежит в интервале шириной в две тысячные вокруг истинного квантиля. Чем строже погрешность и больше целей, тем больше памяти на потоковые структуры в процессе — подробнее чуть ниже. Обязательно учитывайте версию библиотеки: в современных client_golang квантили задаются явно, дефолтного набора 0.5, 0.9 и 0.99 давно нет — summary без Objectives экспортирует только sum и count. В экспозиции каждый квантиль выглядит отдельной серией с лейблом quantile="0.99"; сумма и счётчик идут рядом, как у гистограммы, поэтому среднее тоже доступно. Внешне summary почти неотличим от гистограммы без бакетов — различие прячется в том, кто и когда считает квантиль.

Значение в карте Objectives — это обещание точности, и за него платят памятью процесса. Погрешность 0.05 у медианы означает: заявленное число лежит в интервале плюс-минус пять процентов от истинного квантиля; для p99 те же пять процентов — слишком щедро, поэтому цели обычно сужают с ростом квантиля. Чем больше целей и строже погрешности, тем крупнее внутренние буферы наблюдений, которые summary держит на каждую цель. Практическое правило: не больше трёх-четырёх целей на метрику и только те квантили, что реально рисуются на дашбордах. Квантиль, который никто не смотрит, — это память процесса, потраченная впустую. И помните про версионность: если после обновления client_golang из экспозиции внезапно пропали квантили, проверьте, заданы ли Objectives явно — дефолтного набора в свежих версиях больше нет, а старые туториалы могут показывать иное.

Инцидент на обновлении зависимости. Команда подняла версию client_golang, сервис перезапустился, панель p99 замолчала: ряды исчезли, алерт по квантилю перестал существовать. Виноват не Prometheus: summary после обновления отдал только sum и count, потому что Objectives в этой версии задаётся явно, а код создавал метрику без карты целей. Никакой ошибки в логах: квантиль, о котором не попросили, не считается — это документированное поведение, а не регресс. Урок шире библиотеки: зависимость от клиентских квантилей — зависимость от настроек кода, которые меняются молча. У гистограммы схожий риск — смена сетки — но разрыв виден на графике, а исчезновение серии — нет. После обновлений клиентских библиотек прогоняйте короткую проверку: имя метрики существует, нужный лейбл quantile на месте, значение не пусто. Такая проверка вообще полезна в CI: экспозиция сервиса сверяется со списком ожидаемых имён, и любое исчезновение ловится до выката.

Практическая разница сводится к четырём пунктам. Агрегация: бакеты гистограммы — обычные счётчики, их суммируют sum by (le) и подают в histogram_quantile, получая честный p99 фермы или срез по конкретному маршруту; квантили summary суммировать нельзя — у каждого инстанса свой ряд quantile="0.99", и никакой запрос не соберёт их в общий. Новые квантили: гистограмма отдаёт любой перцентиль из имеющейся сетки — захотелось p95, меняется запрос без релиза; summary считает только то, что зашито в Objectives, новый квантиль — это релиз. Точность: summary гарантирует заявленную погрешность на потоке наблюдений; гистограмма ограничена сеткой бакетов и может быть грубее. Стоимость: summary тяжелеет от строгих погрешностей, гистограмма — фиксированные бакеты. Отсюда правило по умолчанию: HTTP-латентность и всё, что агрегируется, — гистограмма; summary — точечный инструмент одиночного процесса.

Ошибка интерпретации, характерная именно для summary: p99 одного инстанса читают как p99 сервиса. История: восемь подов, на дашборде ряд без агрегации — Prometheus показывал первый попавшийся. Половина трафика шла на новый релиз, у него квантиль был в пять раз выше, но на графике это смешивалось с семью зелёными подами и выглядело шумом. Честный срез по релизу построить нельзя: квантили не суммируются, а записи вида «по инстансу» — молитва на балансировщик, который раскладывает трафик как захочет. Правило для дежурного: если на панели латентности нет агрегации и рядов по подам, панель отвечает не на вопрос «как сервис», а на вопрос «как повезло инстансу, который попал в выборку». Для summary это не лечится запросом — лечится заменой типа, и этот аргумент в споре с гистограммой обычно решающий. Ту же ошибку делают с двумя регионами: p99 региона живёт своей жизнью.

Вариация примера, где summary действительно хорош: длительность ночной фоновой задачи. Наблюдений мало — сотни за сутки, квантиль один, агрегировать не с чем: p99 задачи интересен там же, где она выполняется. Objectives с единственной целью 0.99 и погрешностью 0.001 стоит недорого, а MaxAge в сутки отсекает древнюю историю: без него после недели апгрейдов квантиль помнит времена старой версии кода и ползёт вниз неделями — улучшение, которого нет. Подводный камень окна: при малом числе наблюдений квантиль дёргается от каждой задачи, и график превращается в пилу. Для ночных задач с сотней запусков окно в сутки достаточно; для задачи раз в час — мало, и честнее отказаться от квантиля в пользу гистограммы с несколькими бакетами. MaxAge — единственный способ заставить клиентские квантили забывать прошлое.