Сообщение «High errors on api» не помогает решить, будить ли владельца, откатывать deploy или ждать окончания краткого всплеска. Исправьте не длину текста, а контракт: уведомление должно позволить принять первое безопасное решение без поиска названия сервиса по fingerprint.

Не вставляйте в мессенджер все labels и кусок production log. Это создаёт шум и риск утечки. Короткая карточка сообщает объект, симптом, значение и порог, начало события и следующий шаг; подробности остаются в dashboard, runbook и закрытых logs по ссылке.

Пять полей превращают сигнал в действие

ПолеПримерКакое решение поддерживает
Объектcheckout / prod-euКто владелец и какой blast radius
Симптом5xx rate выше порогаЧто именно деградировало
ЗначениеТекущее и thresholdНасколько срочно
ВремяStartsAt и durationВсплеск или устойчивый отказ
ДействиеRunbook + dashboardГде проверить гипотезу

Контекст начинается в alert rule

- alert: CheckoutHighErrorRate
  expr: job:http_5xx_rate:ratio{job="checkout"} > 0.05
  for: 10m
  labels:
    severity: page
    team: payments
    environment: production
  annotations:
    summary: "Checkout 5xx rate is above the agreed threshold"
    description: "Current ratio: {{ $value }}"
    runbook_url: "https://runbooks.example.test/checkout-5xx"

Числа и URL условны. Порог должен происходить из SLO или эксплуатационного решения, а не из примера. Prometheus позволяет шаблонизировать labels и annotations через $labels и $value; labels участвуют в идентичности и routing, а annotations подходят для description и runbook. Не помещайте переменное значение в label — это создаст новые alert instances.

Grouping может съесть различия между событиями

Alertmanager передаёт template группу Alerts, GroupLabels, CommonLabels и CommonAnnotations. Если шаблон показывает только CommonAnnotations, поле, различающее отдельные alerts, исчезнет из общего блока. Проверьте group_by: слишком широкая группа склеит разные services, слишком узкая отправит шторм сообщений.

  • В заголовок группы вынести общие team, environment и alertname.
  • Внутри пройти по Alerts.Firing и показать instance/service каждого события.
  • Разделить firing и resolved, чтобы статус группы не выглядел двусмысленно.
  • Ограничить число элементов и дать ссылку на полный список при массовом отказе.
  • Не выводить секретные labels, query parameters и customer identifiers.
  • Сохранить GeneratorURL или безопасный dashboard link с фиксированным time range.

Значение нужно подписать единицей и окном

$value без объяснения может означать секунды, долю, количество или rate. Summary должен назвать метрику человеческим языком, а description — единицу, окно вычисления и порог. Значение 0.08 для ratio лучше подписать как долю или корректно отформатированный процент, не меняя смысл expression.

Ссылка на dashboard открывается на интервал вокруг StartsAt, иначе дежурный видит текущее спокойное состояние после задержки доставки. Runbook начинается с проверки, а не с команды restart. Первый шаг должен быть обратимым и объяснять, какой сигнал подтвердит причину.

Тестируем сообщение как интерфейс

  1. Создать synthetic alert в тестовом receiver или использовать fixture template.
  2. Проверить одиночный firing alert и группу из нескольких instances.
  3. Проверить смешанную группу firing/resolved.
  4. Удалить необязательный label и убедиться, что template не ломается.
  5. Открыть ссылки с телефона без привилегированного токена в URL.
  6. Сверить timestamp и timezone.
  7. Попросить человека вне команды назвать первое действие по одной карточке.

Приёмка измеряется не красотой шаблона

Уведомление готово, если получатель различает окружение и объект, видит величину нарушения, понимает длительность, открывает ровно нужный dashboard и находит безопасный первый шаг в runbook. Для редакции подготовьте rule YAML, route/group_by, template, пример Data без секретов и скрин сообщения на узком экране. Историю production-чата и реальные customer labels передавать не нужно.

Проверенные источники