Skip to content

Prometheus Alerting Rules ​

Пример правил алертинга для мониторинга нxs-anomaly. Адаптируйте пороги под свою нагрузку.

rules.yml ​

yaml
groups:
  - name: nxs-anomaly
    interval: 60s
    rules:


      # Kafka outbox накапливается — брокер недоступен или worker не запущен.
      # Расписание, через которое реально ходит эскалация, перестало покрывать
      # ближайшую неделю: выключено, получило пробел или потеряло участника.
      # Гейт при записи цепочки такое не ловит — расписание меняется после неё.
      # Уведомления, которым некуда идти: канал настроен «на бумаге». Это не
      # сбой доставки — ретраев не будет, поэтому обычные failure-алерты молчат.
      - alert: NotificationsSkippedNoTransport
        expr: increase(nxs_anomaly_notifications_skipped_total[1h]) > 0
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "Notifications with no transport on {{ $labels.instance }}"
          description: >
            Channel {{ $labels.channel }} skipped notifications ({{ $labels.reason }}).
            Nobody was told through it. Configure the provider or remove the channel
            from the escalation chain.

      - alert: ScheduleCoverageDegraded
        expr: nxs_anomaly_schedules_degraded > 0
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "On-call schedule without coverage on {{ $labels.instance }}"
          description: >
            {{ $value }} schedule(s) an escalation chain pages through have gaps,
            are disabled, or name deleted users. See GET /api/v1/schedules/coverage.

      # Coverage says somebody is assigned; this says nobody answered. Thirty
      # minutes rather than fifteen: a shift boundary legitimately leaves a few
      # minutes before the incoming person confirms, and paging on that would
      # teach everyone to ignore the alert.
      # The dead-man switch for the monitoring itself: every other rule reacts
      # to something arriving, this one to nothing arriving. No `for:` — the
      # engine already waited out the source's own interval and grace.
      - alert: SourceSilent
        expr: nxs_anomaly_sources_silent > 0
        labels:
          severity: critical
        annotations:
          summary: "Monitoring source has gone quiet on {{ $labels.instance }}"
          description: >
            Integrations with a declared heartbeat have not reported within it.
            nxs-anomaly also raises an ordinary alert group per source; this rule
            is the backstop for when its own delivery is what broke. Sources
            under an open maintenance window are excluded from the metric, so
            planned work does not fire this.

      - alert: DutyShiftWithoutCheckin
        expr: nxs_anomaly_duty_without_checkin > 0
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "On-call shift nobody confirmed on {{ $labels.instance }}"
          description: >
            People the schedules put on call have not confirmed the shift.
            They may not know they are on duty. Ask them to send "duty on",
            or hand the shift over with "duty take".

      - alert: KafkaOutboxBacklog
        expr: nxs_anomaly_kafka_outbox_depth > 500
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Kafka outbox backlog on {{ $labels.instance }}"
          description: >
            {{ $value }} events queued. Check KAFKA_BROKERS connectivity and
            that the worker is running.

      # Критический backlog — события копятся больше часа.
      - alert: KafkaOutboxBacklogCritical
        expr: nxs_anomaly_kafka_outbox_depth > 5000
        for: 15m
        labels:
          severity: critical
        annotations:
          summary: "Critical Kafka outbox backlog on {{ $labels.instance }}"
          description: >
            {{ $value }} events queued for >15 min. Analytics pipeline may be
            significantly delayed.


      # Ошибки ingest по источнику.
      - alert: IngestErrorsHigh
        expr: >
          sum by (source) (
            rate(nxs_anomaly_ingest_errors_total[5m])
          ) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High ingest error rate from {{ $labels.source }}"
          description: >
            {{ printf "%.2f" $value }} errors/s from source {{ $labels.source }}.
            Check integration key validity and payload format.

      # Уведомления постоянно падают.
      - alert: NotificationFailuresHigh
        expr: >
          rate(nxs_anomaly_notifications_failed_total[10m]) > 0.05
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "High notification failure rate on {{ $labels.instance }}"
          description: >
            {{ printf "%.2f" $value }} permanent failures/s. Check delivery
            adapter credentials (Telegram, SMTP, Asterisk).

      # Уведомления доставляются медленно — большая очередь retry.
      - alert: NotificationRetryQueueDeep
        expr: nxs_anomaly_notifications_retry_queue_depth > 200
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Notification retry queue backlog on {{ $labels.instance }}"
          description: >
            {{ $value }} notifications in retry queue. Delivery adapters may
            be slow or unreachable.

      # Worker-цикл не выполнялся последние N минут.
      # ВНИМАНИЕ: сравнивается с timestamp последнего цикла, а НЕ с его
      # длительностью. Прежняя версия вычитала duration_seconds (например 0.05с)
      # из time() и потому горела всегда. Метрика *_last_cycle_timestamp_seconds
      # существует именно для детекта простоя.
      - alert: WorkerCycleStuck
        expr: >
          time() - nxs_anomaly_worker_last_cycle_timestamp_seconds > 120
          and nxs_anomaly_worker_last_cycle_timestamp_seconds > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Worker cycle not completing on {{ $labels.instance }}"
          description: >
            Last worker cycle completed {{ $value | humanizeDuration }} ago.
            Escalations and notifications may be delayed. Check the worker's
            /ready endpoint and logs.

      # База недоступна из процесса (worker или API): ping не проходит.
      # Это первопричина, а не симптом (stuck-cycle, растущий backlog).
      - alert: DatabaseUnavailable
        expr: nxs_anomaly_db_up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Database unreachable from {{ $labels.instance }}"
          description: >
            The last DB ping from this process failed. Ingest, escalation and
            delivery all stop until the database is reachable again.

      # Backlog эскалаций стареет: worker не успевает продвигать группы.
      - alert: EscalationBacklogAge
        expr: nxs_anomaly_oldest_due_escalation_age_seconds > 120
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Escalation backlog aging on {{ $labels.instance }}"
          description: >
            Oldest due alert group is {{ $value | humanizeDuration }} past its
            next_run_at. Worker is behind: check it is running and DB is healthy.

      # Backlog доставки стареет: уведомления зависли в очереди.
      - alert: DeliveryBacklogAge
        expr: nxs_anomaly_oldest_pending_delivery_age_seconds > 120
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Delivery backlog aging on {{ $labels.instance }}"
          description: >
            Oldest delivery_scheduled notification is {{ $value | humanizeDuration }}
            old. Delivery is falling behind ingest.

      # Реклейм чужих claim-ов: worker'ы падают на середине доставки или
      # claim-timeout выставлен слишком агрессивно.
      - alert: StaleClaimsReclaimed
        expr: increase(nxs_anomaly_stale_claims_reclaimed_total[15m]) > 0
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "Stale delivery claims being reclaimed on {{ $labels.instance }}"
          description: >
            {{ $value }} notifications were reclaimed from a stale 'delivering'/
            'retrying' claim. A non-zero rate means workers crash mid-delivery or
            the claim timeout is too short for the provider latency.

      # Много открытых alert groups — возможна инцидентная буря.
      - alert: AlertGroupsBurst
        expr: nxs_anomaly_alert_groups_open > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High number of open alert groups on {{ $labels.instance }}"
          description: >
            {{ $value }} open groups. This may indicate an alert storm.

      # Delivery errors per provider — помогает определить сломанный канал.
      - alert: DeliveryProviderErrors
        expr: >
          sum by (provider) (
            rate(nxs_anomaly_delivery_errors_by_provider_total[10m])
          ) > 0.02
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Delivery errors on {{ $labels.provider }}"
          description: >
            {{ printf "%.3f" $value }} errors/s on provider {{ $labels.provider }}.

      # Worker не успевает: циклы пропускаются, потому что предыдущий ещё идёт.
      - alert: WorkerCyclesSkipped
        expr: rate(nxs_anomaly_worker_cycles_skipped_total[5m]) > 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Worker cycles being skipped on {{ $labels.instance }}"
          description: >
            Worker не успевает за нагрузкой — цикл стартует, пока предыдущий ещё
            выполняется. Увеличьте concurrency/poll-interval или вынесите worker
            в отдельные реплики.

      # Процесс не упал в деградацию, а пропал. Все правила выше читают метрики,
      # которые экспортирует сам процесс, и мёртвый API или worker молча уносит
      # их с собой — об этом говорит только результат скрейпа. Label job — имя
      # Service под ServiceMonitor чарта (<release>-nxs-anomaly-api, -worker)
      # или ваш job_name в static-конфиге; при fullnameOverride поправьте regex.
      - alert: NxsAnomalyTargetDown
        expr: up{job=~".*nxs-anomaly.*"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "nxs-anomaly target {{ $labels.job }} down on {{ $labels.instance }}"
          description: >
            Prometheus не может снять метрики с процесса nxs-anomaly. Если это
            worker — никого не будят. Маршрутизируйте в обход nxs-anomaly.

      # Ни один worker не завершает циклы: все упали, в crash-loop или вообще не
      # скрейпятся. «> 0» обязательно: API с --no-scheduler тоже экспортирует
      # этот gauge, но со значением 0, и без фильтра маскировал бы отсутствие.
      - alert: WorkerAbsent
        expr: absent(nxs_anomaly_worker_last_cycle_timestamp_seconds > 0)
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "No nxs-anomaly worker is completing cycles"
          description: >
            Ни один процесс не сообщает о завершённом цикле worker-а. Эскалация и
            доставка стоят. Маршрутизируйте в обход nxs-anomaly.

      # Горит всегда — так задумано. Доказывает, что путь Prometheus →
      # Alertmanager → receiver жив: отправляйте его во внешний dead-man's switch,
      # который поднимает тревогу, когда алерт ПЕРЕСТАЁТ приходить. Никогда не
      # направляйте его в сам nxs-anomaly.
      - alert: Watchdog
        expr: vector(1)
        labels:
          severity: none
        annotations:
          summary: "Alerting pipeline heartbeat (always firing)"
          description: >
            Receiver — dead-man's switch с коротким repeat_interval. Его молчание
            означает, что лежит Prometheus или Alertmanager.

      # Канал доставки деградировал по латентности (p95), хотя ошибок может не быть.
      - alert: DeliveryLatencyHigh
        expr: >
          histogram_quantile(0.95,
            sum by (channel, le) (
              rate(nxs_anomaly_notification_delivery_duration_seconds_bucket[10m])
            )
          ) > 3
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Slow delivery on channel {{ $labels.channel }}"
          description: >
            p95 латентность доставки по каналу {{ $labels.channel }} =
            {{ printf "%.1f" $value }}s. Провайдер жив, но медленный.

      # SLI задержки страницы: уведомления уходят из очереди поздно (SLO: p95 < 10 с).
      - alert: PagingLatencyHigh
        expr: >
          histogram_quantile(0.95,
            sum by (channel, le) (
              rate(nxs_anomaly_notification_first_attempt_delay_seconds_bucket[10m])
            )
          ) > 10
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Pages leave late on channel {{ $labels.channel }}"
          description: >
            p95 от постановки в очередь до первой попытки = {{ printf "%.1f" $value }}s.
            Worker не успевает: проверьте длительность цикла и очередь доставки.

      # SLI дежурного: подтверждение/закрытие медленные (SLO: p95 < 2 с).
      - alert: RespondLatencyHigh
        expr: >
          histogram_quantile(0.95,
            sum by (le) (
              rate(nxs_anomaly_http_request_duration_seconds_bucket{handler="respond"}[10m])
            )
          ) > 2
          and sum(rate(nxs_anomaly_http_request_duration_seconds_count{handler="respond"}[10m])) > 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Acknowledge/resolve is slow"
          description: >
            p95 действий дежурного = {{ printf "%.1f" $value }}s; пока дежурный
            ждёт ответа кнопки, страница продолжает эскалироваться.

      # Уведомления окончательно теряются (dead-letter).
      - alert: DeadLetterEvents
        expr: >
          sum by (channel) (
            rate(nxs_anomaly_dead_letter_events_total[15m])
          ) > 0
        for: 15m
        labels:
          severity: critical
        annotations:
          summary: "Dead-letter notifications on channel {{ $labels.channel }}"
          description: >
            Уведомления по каналу {{ $labels.channel }} исчерпали retry и стали
            permanently failed. Проверьте провайдер и dead-letter webhook.

Готовый к применению манифест PrometheusRule со всеми правилами лежит в prometheus-rules.yaml; дашборд Grafana для импорта — grafana-dashboard.json.

Подключение к Prometheus ​

API и отдельный worker (run-worker) экспонируют метрики независимо: worker поднимает собственный телеметрийный порт (/live, /ready, /metrics, по умолчанию :8081, см. NXS_ANOMALY_WORKER_ADDR). Без этого схема serve --no-scheduler + run-worker теряла бы все delivery-метрики: их производит worker, а раньше реестр жил только в HTTP-сервере API. Скрейпить надо оба таргета.

yaml
# prometheus.yml
scrape_configs:
  - job_name: nxs-anomaly-api
    static_configs:
      - targets: ['nxs-anomaly-api:8080']
    metrics_path: /metrics
    scrape_interval: 15s
  - job_name: nxs-anomaly-worker
    static_configs:
      - targets: ['nxs-anomaly-worker:8081']
    metrics_path: /metrics
    scrape_interval: 15s

Мониторинг в обход nxs-anomaly ​

Алерт о том, что nxs-anomaly не работает, нельзя доставлять через nxs-anomaly: он придёт в ту самую систему, которая лежит. Поэтому три правила выше — NxsAnomalyTargetDown, WorkerAbsent и Watchdog — нужно маршрутизировать отдельным receiver-ом Alertmanager прямо в независимый канал, а Watchdog — во внешний dead-man's switch:

yaml
# alertmanager.yml
route:
  routes:
    - matchers: ['alertname="Watchdog"']
      receiver: deadmans-switch
      repeat_interval: 1m
    - matchers: ['alertname=~"NxsAnomalyTargetDown|WorkerAbsent|DatabaseUnavailable|WorkerCycleStuck"']
      receiver: ops-direct          # Telegram/почта/SMS напрямую, не nxs-anomaly
      continue: false
receivers:
  - name: deadmans-switch
    webhook_configs:
      - url: https://hc-ping.com/<uuid>
  - name: ops-direct
    telegram_configs:
      - chat_id: <id>
        bot_token_file: /etc/alertmanager/telegram-token

Watchdog проверяет цепочку Prometheus → Alertmanager, но не сам nxs-anomaly. Для прямого сигнала от worker-а задайте NXS_ANOMALY_WORKER_HEARTBEAT_URL: после успешного цикла worker делает GET на этот адрес, не чаще раза в минуту. Цикл, упавший на базе, пинга не даёт, поэтому один такой check покрывает worker, его базу и сеть — без Prometheus. Период проверки во внешнем сервисе ставьте с запасом: не меньше 5 минут. Пинг уходит от каждой реплики worker-а, так что check молчит, только когда не работает ни одна.

В Helm-чарте переменную задают через Secret приложения или worker.extraEnv; URL содержит токен check-а, поэтому в логи он не пишется.

SLI / SLO ​

Зафиксированные индикаторы для beta. Пороги — стартовые, калибруются под нагрузку (см. CAPACITY.md).

SLIОпределениеPromQLЦелевой SLO
Ingest availabilityдоля webhook-запросов ingest без 5xx1 - (sum(rate(nxs_anomaly_http_requests_total{handler="webhook",code=~"5.."}[5m])) / sum(rate(nxs_anomaly_http_requests_total{handler="webhook"}[5m])))≥ 99.9%
Ingest→first-attempt latencyp95 задержки от приёма алерта до первой попытки доставкиhistogram_quantile(0.95, sum by (le) (rate(nxs_anomaly_ingest_duration_seconds_bucket[5m]))) + nxs_anomaly_oldest_pending_delivery_age_secondsp95 < 10s
Successful delivery ratio (per provider)доля успешных доставок по каналуsum by (provider) (rate(nxs_anomaly_notifications_delivered_by_provider_total[30m])) / (sum by (provider) (rate(nxs_anomaly_notifications_delivered_by_provider_total[30m])) + sum by (provider) (rate(nxs_anomaly_delivery_errors_by_provider_total[30m])))≥ 99%
Acknowledge API latencyp95 ack-запросовhistogram_quantile(0.95, sum by (le) (rate(nxs_anomaly_http_request_duration_seconds_bucket{handler="api"}[5m])))p95 < 2s

Прямой замер ingest→first-attempt (без разложения на две метрики) даёт нагрузочный harness — он засекает время между ingest и первым delivery_attempt и печатает p50/p95/p99. См. CAPACITY.md.

Метка ingest-SLI — handler="webhook". Это категория, которую classifyHandler (internal/server/server_internal.go) присваивает путям /integrations/v1/ и /v2/alert/; значения handler="ingest" не существует, и запрос с ним молча возвращает пустой результат.

Error budget и burn rate ​

Все пороговые алерты выше сравнивают мгновенную скорость с константой. Такой порог не отличает двухминутный всплеск от недели медленного кровотечения: всплеск разбудит дежурного и пройдёт сам, а кровотечение никогда не перешагнёт порог и тихо съест SLO целиком. Поэтому группа nxs-anomaly.slo в prometheus-rules.yaml алертит не на ошибки, а на скорость расхода бюджета ошибок (Google SRE Workbook, гл. 5).

Бюджет = 1 - SLO. Burn rate = наблюдаемая доля ошибок / бюджет. Burn rate 1 расходует месячный бюджет ровно за 30 дней, 14.4 — 2% бюджета за час.

ТирBurn rateОкнаБюджет кончится черезseverity
Fast14.45m и 1h~2 дняcritical — будить
Slow630m и 6h~5 днейwarning — тикет

Два окна обязательны одновременно: короткое даёт быстрое срабатывание и быстрый сброс, длинное не даёт кратковременному блипу поднять дежурного.

SLISLOБюджетFast-порогSlow-порогАлерты
Ingest availability99.9%0.1%1.44% 5xx0.6% 5xxIngestErrorBudgetBurnFast / Slow
Delivery success (по провайдеру)99%1%14.4% ошибок6% ошибокDeliveryErrorBudgetBurnFast / Slow

Доли считаются recording-правилами nxs_anomaly:ingest_5xx:ratio_rate* и nxs_anomaly:delivery_errors:ratio_rate* — они же готовые панели для дашборда.

Чего эти правила не ловят: при нулевом трафике отношение равно 0/0 = NaN, любое сравнение с NaN ложно, и тихий инстанс молчит вместо алерта о делении на ноль. Обратная сторона — полностью прекратившийся приём алертов burn rate не видит; за это отвечают WorkerCycleStuck и DatabaseUnavailable.

DeliverySuccessRatioLow намеренно оставлен: он ловит проседание ниже 99% на 30-минутном окне, то есть срабатывает раньше slow-тира, но без привязки к бюджету. Burn-rate-алерты отвечают на другой вопрос — «успеем ли мы до конца месяца», а не «плохо ли сейчас».

Grafana dashboard (быстрый старт) ​

Основные панели:

ПанельPromQL
Ingested alerts/srate(nxs_anomaly_alerts_ingested_total[1m])
Ingest errors/s by sourcesum by(source)(rate(nxs_anomaly_ingest_errors_total[1m]))
Open alert groupsnxs_anomaly_alert_groups_open
Skipped notificationsnxs_anomaly_notifications_skipped_total
Schedule coveragenxs_anomaly_schedules_degraded
Shifts nobody confirmednxs_anomaly_duty_without_checkin
Sources gone quietnxs_anomaly_sources_silent
Retention deletions by categorysum by(category)(increase(nxs_anomaly_retention_deleted_total[24h]))

| Kafka outbox depth | nxs_anomaly_kafka_outbox_depth |

| Notification retry queue | nxs_anomaly_notifications_retry_queue_depth | | Delivery errors by provider | sum by(provider)(rate(nxs_anomaly_delivery_errors_by_provider_total[5m])) | | Worker cycle duration | nxs_anomaly_worker_cycle_duration_seconds | | Time since last worker cycle | time() - nxs_anomaly_worker_last_cycle_timestamp_seconds | | DB up | nxs_anomaly_db_up | | Escalation backlog age | nxs_anomaly_oldest_due_escalation_age_seconds | | Delivery backlog age | nxs_anomaly_oldest_pending_delivery_age_seconds | | Delivered/s by provider | sum by(provider)(rate(nxs_anomaly_notifications_delivered_by_provider_total[5m])) | | Per-provider success ratio | sum by(provider)(rate(nxs_anomaly_notifications_delivered_by_provider_total[30m])) / (sum by(provider)(rate(nxs_anomaly_notifications_delivered_by_provider_total[30m])) + sum by(provider)(rate(nxs_anomaly_delivery_errors_by_provider_total[30m]))) | | Worker cycles skipped/s | rate(nxs_anomaly_worker_cycles_skipped_total[5m]) | | Delivery latency p95 by channel | histogram_quantile(0.95, sum by(channel,le)(rate(nxs_anomaly_notification_delivery_duration_seconds_bucket[5m]))) | | Dead-letters/s by channel | sum by(channel)(rate(nxs_anomaly_dead_letter_events_total[5m])) | | Short-circuited deliveries/s | sum by(channel)(rate(nxs_anomaly_delivery_short_circuited_total[5m])) |

Для retention нет универсального alert rule: нулевой increase может означать как остановившийся свип, так и отсутствие строк старше отсечки. Сопоставляйте его с выбранными сроками и размером таблиц; readiness отдельно предупреждает о невыбранной политике.

| Kafka outbox by topic | nxs_anomaly_kafka_outbox_depth_by_topic |

| Ingest latency p95 | histogram_quantile(0.95, rate(nxs_anomaly_ingest_duration_seconds_bucket[5m])) |

nxs-anomaly · Documentation