Какие практики инструментации важны при добавлении кастомных метрик в приложение, чтобы они были полезны и не создавали проблем в будущем?

Короткий ответ

Ключевые практики: выбирать правильный тип метрики (counter/gauge/histogram) под характер данных, ограничивать кардинальность labels заранее продуманным набором значений, называть метрики согласно конвенции (___), и избегать дублирования уже существующих стандартных метрик фреймворка.

Как это работает подробнее

Prometheus client-библиотеки (Go, Java, Python, Node.js) предоставляют примитивы Counter/Gauge/Histogram/Summary, и неправильный выбор типа (например, Gauge для величины, которая должна быть Counter) приводит к невозможности использовать rate()/increase() корректно. Конвенция именования с единицей измерения в конце (_seconds, _bytes, _total для counter) делает метрики самодокументируемыми и предотвращает путаницу с единицами при построении запросов.

Пример кода

instrumentation.pyКопировать

# Псевдокод с prometheus_client (Python)
from prometheus_client import Counter, Histogram
orders_total = Counter(
    "checkout_orders_total", "Total number of completed orders", ["payment_method"]
)
order_processing_seconds = Histogram(
    "checkout_order_processing_seconds", "Time to process an order"
)
orders_total.labels(payment_method="card").inc()
with order_processing_seconds.time():
    process_order(order)

Что использовать на практике

• Практика. перед добавлением новой метрики стоит проверить, не покрывает ли её уже стандартная инструментация фреймворка (например, HTTP-метрики часто уже есть в middleware) — дублирование усложняет дашборды и создаёт путаницу, какую метрику использовать. Для бизнес-метрик (например, "число оформленных заказов") имеет смысл явно отделять их от технических метрик инфраструктуры по namespace, чтобы разные команды могли независимо искать нужные им данные.
• Практика. После деплоя запрос rate(checkout_orders_total[5m]) должен показывать скорость оформления заказов по методам оплаты, а histogram_quantile(0.95, rate(checkout_order_processing_seconds_bucket[5m])) — p95 времени обработки, оба — без необходимости в дополнительных костылях для расчёта скорости или процентилей.

Подводные камни

• Частые ошибки. добавлять Gauge туда, где естественная семантика — "накопительный счётчик событий" (например, число обработанных заказов как Gauge, который сбрасывается при перезапуске, вместо Counter); не продумывать заранее возможные значения labels и добавлять потенциально неограниченные значения (email, IP, произвольный текст ошибки) напрямую в label; называть метрики без единиц измерения, из-за чего через полгода никто не помнит, секунды это или миллисекунды.