Конвенция именования метрик

Действуй как Observability Architect. Разработай конвенцию именования метрик для {{stack}}, покрывающую {{services_count}} сервисов.

Что сделать

1. Формат имени: {namespace}_{subsystem}_{metric}_{unit}. Прозрачно и переносимо между бэкендами.

   • namespace — продукт или team (checkout, payments, search). Один токен.
   • subsystem — компонент внутри (db, cache, http_server). Опционально, если контекст явный.
   • metric — что измеряем (requests, bytes_received, duration).
   • unit — единица измерения в имени (_seconds, _bytes, _total для counter). Не миксуй ms и s в одной метрике.
   • Тип в суффиксе: counter → _total, gauge → без суффикса, histogram → _seconds (или _bytes) + автогенерированные _bucket / _sum / _count.
   • Примеры: checkout_http_server_requests_total, payments_db_query_duration_seconds, search_index_documents (gauge).

2. Labels: low vs high cardinality. Cardinality убивает backend. Каждая уникальная комбинация labels = отдельный timeseries.

   • Low cardinality (OK как label): method (GET/POST), status_code (2xx/4xx/5xx бакеты), endpoint (/users/{id}, не /users/12345), region (us-east-1), environment (prod/staging), service (checkout). Бюджет: ≤ 100 уникальных значений на label.
   • High cardinality (НЕ класть в labels): user_id, request_id, trace_id, email, IP-адреса, raw URLs с params. Эти идентификаторы → в logs или traces, не в metric labels.
   • Граничные случаи: customer_tier (gold/silver/bronze) — ок, customer_id — нет. country (~250) — приемлемо, city (миллионы) — нет.
   • Cardinality budget: ≤ 10K active timeseries на сервис. Audit раз в месяц через count by (__name__) ({__name__=~".+"}) (или эквивалент бэкенда).
   • Endpoint normalization mandatory: route template (/users/{id}), не raw URL — иначе каждый user взрывает cardinality.

3. Aggregation rules. Recording rules ускоряют дашборды и снижают cost query.

   • Уровни: raw (что отдаёт app) → 1m aggregation → 5m → 1h. Каждый уровень — отдельная recording rule.
   • Naming для recording rules: {level}:{metric}:{op}. Пример: service:http_requests:rate1m (per-service rate за 1 минуту).
   • Что агрегировать заранее: медленные queries (длинный rollup), часто используемые в дашбордах (top-50 panels), SLI (avoid window math каждый раз).
   • Histogram aggregation: histogram_quantile(0.95, sum by (le) (rate(metric_bucket[5m]))). Не считай quantile в дашборде, если можешь pre-aggregate.
   • Downsampling: raw retention 15 дней, 1m aggregation 90 дней, 1h aggregation 1 год. Cost экономия 10x+ на длинных windows.

4. Federation patterns. Когда метрики выходят за рамки одного Prometheus / региона.

   • Hierarchical federation: региональный Prometheus в каждом регионе → глобальный Prometheus pull'ит только pre-aggregated (recording rules), не raw timeseries. Иначе network blow up.
   • Cross-region SLI: считай локально, агрегируй глобально через recording rule global:service:availability:ratio5m.
   • Cortex / Thanos / Mimir / VictoriaMetrics cluster для масштабирования. Выбор по cost vs ops overhead.
   • Не federate raw timeseries через WAN — латентность и cost. Federate только агрегаты.
   • Tenant isolation (multi-tenant Mimir/Cortex): labels __tenant_id injected at write, чтобы один team не видел чужие метрики.

5. Deprecation flow. Метрики — публичный API дашбордов и алёртов. Сломать = разломать SRE на 3 недели.

   • Lifecycle: experimental → stable → deprecated → removed. Tag в registry (status: stable в metric metadata).
   • Deprecation announce: минимум 90 дней до removal. Communication: changelog, #observability канал, email owner'ам дашбордов.
   • Dual-emit window: новая и старая метрика emit'ятся одновременно как минимум 30 дней. Дашборды/алёрты мигрируются в этот период.
   • Detection: какие дашборды / алёрты используют old metric. Tool: Grafana API (/api/search + parse panel queries), AlertManager rules grep.
   • Removal gate: zero references в Grafana, zero alert rules, zero recording rules за 7 дней до removal.

Anti-patterns

• ❌ my_metric без namespace — конфликты, нечитаемо в большом каталоге.
• ❌ Camel/Pascal case (HttpRequestsTotal) — Prometheus convention = snake_case.
• ❌ Unit в label (unit="seconds") вместо имени — split timeseries, ломает аггрегацию.
• ❌ user_id / url / trace_id в label — взрывает cardinality, кладёт TSDB.
• ❌ Удалить метрику без deprecation window — broken alerts в самом неподходящий момент.
• ❌ Один глобальный Prometheus federate всё с raw cardinality — collapse под нагрузкой.
• ❌ Recording rules без префикса уровня — невозможно отличить raw от aggregated, ошибки в queries.

Формат вывода

## Naming spec
{namespace}_{subsystem}_{metric}_{unit}[_total]

| Type | Suffix | Example |
| counter | _total | http_requests_total |
| gauge | — | queue_depth |
| histogram | _seconds (или _bytes) | request_duration_seconds |

## Label allowlist (global)
| Label | Allowed values (rough) | Cardinality budget |
| environment | prod/staging/dev | 3 |
| service | <service-name> | ~50 |
| region | aws region codes | ~20 |

## Label denylist
- user_id, email, trace_id, raw URL, IP — NEVER

## Recording rules (template)
- `service:http_requests:rate5m`
- `service:request_duration:p95_5m`
- `global:service:availability:ratio28d`

## Federation topology
```mermaid
regional Prometheus → recording rules → global Mimir (aggregated only)

Deprecation flow

1. Announce (T-90d): changelog + owner notify
2. Dual emit (T-60d → T-0): old + new
3. Migration tracker: дашборды, alerts, recording rules
4. Removal gate (T-0): zero references → drop

Cardinality audit (monthly)

• Top 10 services by active timeseries
• Top 10 metrics by cardinality
• New metrics added (review label set)

**Принцип:** конвенция метрик — это API, который читают и люди, и алёрты, и дашборды. Сломанный API ломает observability разом. Дешевле договориться один раз и держаться, чем чинить cardinality blowup в проде.