Skip to content

Настройка: от пустой инсталляции до работающего оповещения ​

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

Здесь описано как настраивать. Что представляет собой каждая сущность и по каким правилам движок её обрабатывает — в DOMAIN_MODEL.md. Полный справочник эндпоинтов — в API.md.

Все примеры используют API-ключ; в веб-интерфейсе те же действия доступны через соответствующие разделы.

Те же сущности можно описывать декларативно через публичный Terraform provider nixys/nxs-anomaly. Пример подключения — в README. Провайдер использует тот же /api/v1; зависимости сущностей и порядок их создания, описанные ниже, сохраняются.

У каждого объекта должен быть один владелец конфигурации. Объекты, управляемые через UI, и объекты под Terraform могут сосуществовать в одной инсталляции. Объект, созданный запросом Terraform, получает поле provisioned_by: "terraform"; после этого API отвечает 403 на его изменение и удаление кем-либо другим, а веб-интерфейс показывает рядом с именем бейдж «Управляется terraform» и гасит собственные кнопки правки и удаления. Причина — контракт Terraform: правка в UI живёт до следующего apply, после чего молча откатывается, и раньше об этом ничто не предупреждало.

Что специально не заблокировано: чтение; действия по алерт-группам (ack, resolve, silence); подмены в расписании (override — это «подменю сегодня ночью», Terraform такого не описывает); ротация ключа интеграции — это ответ на утечку, и у Terraform нет действия, которое её выполняет.

Тул определяется по User-Agent (его шлёт любой запрос terraform-plugin-sdk) либо по явному заголовку X-Nxs-Anomaly-Provisioner: <имя>. Заголовок — это ещё и способ убрать объект, определения которого в коде уже нет: назовитесь тем же провизионером и удалите вручную. Это не право доступа: роль и командные границы проверяются как обычно, заголовок лишь сообщает, чьи объекты можно трогать.

bash
export API=http://localhost:8080
export KEY=<ваш NXS_ANOMALY_API_KEY>
alias api='curl -sS -H "X-API-Key: $KEY" -H "Content-Type: application/json"'

Порядок настройки ​

Сущности ссылаются друг на друга, и движок проверяет ссылки при записи: создать интеграцию с несуществующей цепочкой нельзя, шаг NOTIFY_USER с неизвестным пользователем — тоже. Поэтому порядок не произвольный:

пользователи ──┬─→ команды ──┬─→ расписания ──┐
               │             │                ├─→ цепочки эскалации ─→ интеграции
               └─────────────┴────────────────┘

Быстрый ответ на вопрос «что ещё не сделано» даёт страница Setup в веб-интерфейсе (/setup): шесть шагов онбординга, состояние которых выводится из данных, а не хранится отдельно, поэтому чеклист не может разойтись с реальностью. Данные она берёт из того же отчёта, что и API:

bash
api "$API/api/v1/readiness"

UI доступен на ru-RU и en-US. Выбор языка сохраняется в профиле пользователя; даты выводятся в выбранной локали и его IANA timezone.

1. Пользователи ​

bash
api -X POST "$API/api/v1/users" -d '{
  "name": "Анна Петрова",
  "username": "anna",
  "email": "anna@example.com",
  "telegram_id": "123456789",
  "timezone": "Europe/Moscow",
  "priority": "high",
  "notification_targets": ["telegram", "email"]
}'

notification_targets — куда реально уходит уведомление. Допустимы log, webhook, telegram, email, call, slack, mattermost. Если не указать ни одной цели, пользователь получит log — то есть запись в журнале и ничего больше. Это законный вариант для технической учётной записи и почти наверняка ошибка для человека.

Канал работает только если настроен его транспорт: telegram без NXS_ANOMALY_TELEGRAM_BOT_TOKEN недостижим. Такие уведомления получают терминальный статус skipped с причиной not_configured — они не притворяются доставленными. Проверить, какие каналы реально доступны, можно через GET /api/v1/readiness.

priority (high/medium/low) влияет на выбор дежурных в шаге NOTIFY_DUTY_USERS — см. ниже.

Пароль для входа задаётся отдельно; первый администратор создаётся из NXS_ANOMALY_BOOTSTRAP_ADMIN_USERNAME / _PASSWORD.

2. Команды ​

bash
api -X POST "$API/api/v1/teams" -d '{
  "name": "Платформа",
  "member_ids": ["usr_...", "usr_..."]
}'

Команды нужны для расписаний, шагов NOTIFY_TEAM и NOTIFY_DUTY_USERS, ChatOps-каналов.

3. Расписания дежурств ​

Расписание отвечает на вопрос «кто дежурит прямо сейчас». Основной механизм — ротация: упорядоченный список участников и интервал передачи дежурства.

bash
api -X POST "$API/api/v1/schedules" -d '{
  "name": "Платформа — основное",
  "team_id": "team_...",
  "timezone": "Europe/Moscow",
  "enabled": true,
  "notify_on_shift_change": true,
  "rotation": {
    "enabled": true,
    "start_at": "2026-01-05T10:00:00+03:00",
    "handoff_interval": 1,
    "handoff_unit": "weeks",
    "participant_ids": ["usr_a", "usr_b", "usr_c"]
  }
}'
  • handoff_unit — hours, days или weeks. Для days/weeks передача считается по календарю в зоне расписания, поэтому handoff в 10:00 остаётся в 10:00 и после перехода на летнее время. hours — абсолютная длительность.
  • start_at — якорь: от него отсчитываются все последующие передачи.
  • participant_ids идут по кругу в указанном порядке.

Ограничение по часам ​

Если дежурство только в рабочие часы, добавьте restriction. Вне окна дежурного нет вообще — это пробел в покрытии, а не «дежурит предыдущий»:

json
"restriction": {
  "start": "10:00",
  "end": "19:00",
  "days": ["mon", "tue", "wed", "thu", "fri"]
}

Пустой days означает «каждый день». Время — по timezone расписания.

Покрытие и почему это важно ​

Расписание с дырой не пейджит никого ровно тогда, когда это нужнее всего, и делает это молча. Поэтому движок проверяет покрытие в двух местах:

bash
api "$API/api/v1/schedules/coverage"

Кроме того, прикрепить расписание с пробелом к цепочке эскалации нельзя — см. шаг NOTIFY_SCHEDULE.

Подмены (override) ​

Разовая подмена поверх ротации — например, на время отпуска:

bash
api -X POST "$API/api/v1/schedules/{id}/override" -d '{
  "user_id": "usr_d",
  "start_at": "2026-03-10T10:00:00+03:00",
  "until": "2026-03-17T10:00:00+03:00",
  "reason": "отпуск Анны"
}'

Приоритет источников: активный override → ротация → legacy-смены. Если override-ы пересекаются, побеждает созданный позже.

Предпросмотр ​

Прежде чем считать расписание готовым, посмотрите, как оно разложится:

bash
api "$API/api/v1/schedules/{id}/preview"

Ответ показывает интервалы на четыре недели вперёд, пробелы (gaps), пересечения и coverage_ratio.

4. Цепочки эскалации ​

Цепочка — упорядоченный список шагов. Движок идёт по ним сверху вниз, пока не упрётся в WAIT/REPEAT или не дойдёт до конца.

Тип шага задаётся полем kind. Поле type не читается — шаг с ним молча не совпадёт ни с одним обработчиком и будет пропущен.

bash
api -X POST "$API/api/v1/escalation-chains" -d '{
  "name": "Платформа — критичное",
  "steps": [
    {"kind": "NOTIFY_SCHEDULE", "schedule_id": "sch_..."},
    {"kind": "WAIT", "delay_minutes": 10},
    {"kind": "NOTIFY_TEAM", "team_id": "team_..."},
    {"kind": "WAIT", "delay_minutes": 15},
    {"kind": "NOTIFY_EMERGENCY", "user_id": "usr_lead"},
    {"kind": "REPEAT", "from_position": 0, "max_repeat_count": 3, "cooldown_minutes": 30}
  ]
}'

Все типы шагов ​

kindПоляЧто делает
WAITdelay_minutesПауза перед следующим шагом. Группа получает next_run_at, worker вернётся к ней позже
NOTIFY_USERuser_ids, notify_policyПейджит конкретных людей. notify_policy (default/important) выбирает личную политику получателя
NOTIFY_SCHEDULEschedule_id, allow_uncoveredПейджит тех, кто дежурит по расписанию на момент выполнения шага
NOTIFY_TEAMteam_idПейджит всех участников команды
NOTIFY_DUTY_USERSteam_id, fallback_to_allПейджит тех, у кого поднят флаг on_duty
NOTIFY_EMERGENCYuser_idЭкстренный получатель. Без user_id берётся emergency_user_id из политики интеграции
TRIGGER_WEBHOOKwebhook_url, headersВнешний HTTP-вызов
CREATE_ISSUEurl, tracker_type, token_env, project, шаблоныЗаводит задачу в трекере
RESOLVE—Закрывает группу автоматически
REPEATfrom_position, max_repeat_count, cooldown_minutesВозврат к шагу from_position

Нюансы, на которых обычно спотыкаются ​

NOTIFY_SCHEDULE требует покрытого расписания. Если в ближайшие семь дней есть пробел, создание цепочки завершится ошибкой. Это намеренный гейт: шаг с дырой не пейджит никого и выглядит при этом как исправно отработавший. Осознанно обойти можно, но только явно:

json
{"kind": "NOTIFY_SCHEDULE", "schedule_id": "sch_...", "allow_uncovered": true}

NOTIFY_DUTY_USERS выбирает по флагу, а не по расписанию. Берутся участники team_id (без него — все пользователи) с on_duty: true, затем из них — группа с наивысшим priority. Если дежурных нет:

  • fallback_to_all: true (по умолчанию) — пейджатся все кандидаты;
  • fallback_to_all: false — не пейджится никто, в timeline группы появляется no_duty_users.

REPEAT считает повторы по группе. from_position — индекс шага с нуля. При исчерпании max_repeat_count эскалация останавливается и пишет escalation_repeat_exhausted.

TRIGGER_WEBHOOK подчиняется SSRF-гейту. В production-профиле адреса в приватных, loopback и link-local диапазонах отклоняются, включая переходы по редиректам — см. SECURITY_PROFILE.md.

TRIGGER_WEBHOOK: учётные данные — в headers, а не в URL. URL оседает в журналах доступа каждого прокси по дороге, заголовок — нет. headers — объект «имя заголовка → значение», он отправляется с каждым вызовом webhook_url, включая повторы:

json
{"kind": "TRIGGER_WEBHOOK", "webhook_url": "https://gateway.example/hook",
 "headers": {"Authorization": "env:NXS_ANOMALY_GATEWAY_AUTH"}}

Значение считается секретом: его можно задать ссылкой env:ПЕРЕМЕННАЯ (переменная содержит значение целиком, вместе с Bearer …), она читается в момент отправки, а inline-значение production-профиль отклоняет. Если переменная не задана, уведомление получает статус skipped с её именем и ничего не отправляется — запрос без учётных данных вернулся бы 401. Host, Content-Length, Content-Type, Transfer-Encoding и Connection принадлежат транспорту и не задаются; заголовков — не больше 16. То же поле есть у ChatOps-каналов (см. раздел 8).

CREATE_ISSUE: токен через token_env. В production-профиле inline-секрет в поле token отклоняется; используйте ссылку на переменную окружения ("token_env": "NXS_ANOMALY_REDMINE_TOKEN").

5. Интеграции и маршрутизация ​

Интеграция — точка приёма алертов. Ключ (key) генерируется движком и входит в URL приёма.

bash
api -X POST "$API/api/v1/integrations" -d '{
  "name": "Prometheus — прод",
  "type": "alertmanager",
  "team_id": "team_...",
  "default_chain_id": "chn_..."
}'

Ответ содержит key. Отправлять алерты:

bash
curl -X POST "$API/integrations/v1/alertmanager/<key>" \
  -H 'Content-Type: application/json' -d @payload.json

Ключ можно перевыпустить (POST /api/v1/integrations/{id}/rotate-key); старый сразу перестаёт работать. Удаление интеграции — мягкое: строка остаётся ради истории алертов, но перестаёт принимать и попадать в списки.

Маршруты ​

Если все алерты интеграции идут в одну цепочку, достаточно default_chain_id — движок сам создаст единственный маршрут all. Когда разные алерты должны идти по-разному, задайте routes явно:

bash
api -X PUT "$API/api/v1/integrations/{id}" -d '{
  "routes": [
    {
      "name": "база данных",
      "match_type": "labels",
      "labels": {"service": "postgres"},
      "escalation_chain_id": "chn_db"
    },
    {
      "name": "по имени алерта",
      "match_type": "regex",
      "pattern": "^Disk(Space|Inodes)",
      "escalation_chain_id": "chn_infra"
    },
    {
      "name": "остальное",
      "match_type": "all",
      "is_default": true,
      "escalation_chain_id": "chn_default"
    }
  ]
}'
  • match_type: labels — совпадение по всем указанным меткам;
  • match_type: regex — по заголовку алерта, значению каждой метки и каждой метке в виде имя=значение (аннотации и сообщение не участвуют), поэтому ^Disk привязывается к началу заголовка или значения метки; шаблон компилируется при записи, так что синтаксическая ошибка вернёт 400 сразу, а не при первом алерте;
  • match_type: all — принимает всё.

Ровно один маршрут должен быть is_default: true. Ни ноль, ни два: без дефолтного маршрута не подошедший алерт остался бы без цепочки, а два дефолта делают выбор недетерминированным. Запрос с другим количеством отклоняется.

Маршруты проверяются по порядку, поэтому дефолтный логично держать последним.

Проверка маршрутизации без отправки алерта ​

bash
api -X POST "$API/api/v1/routes/debug/<key>" -d '{
  "title": "DiskSpaceLow on db-01",
  "labels": {"service": "postgres", "severity": "critical"}
}'

Ответ покажет выбранный маршрут, цепочку и кого именно уведомит первый шаг — ничего при этом не создавая.

Heartbeat: замечать замолчавший источник ​

Все остальные сигналы сервиса начинаются с пришедшего алерта. Остаётся отказ, о котором никто не сообщит: умерший экспортёр, остановившийся cron, сегмент сети, унёсший с собой Alertmanager. Снаружи молчание неотличимо от здоровья, и чем дольше оно длится, тем спокойнее выглядит.

bash
api -X PUT "$API/api/v1/integrations/<id>" -d '{
  "heartbeat": {"interval_seconds": 300}
}'

interval_seconds — как долго источник вправе молчать, прежде чем это новость. grace_seconds даёт запас на опоздавший тик и по умолчанию равен трети интервала. Минимум интервала — 60 секунд: ниже проверка срабатывала бы на обычном дрожании расписания, ведь цикл воркера сам по себе пятисекундный.

Включается на каждую интеграцию отдельно, и по умолчанию выключен: множество источников законно молчат неделями, и сообщать о них значило бы приучить всех игнорировать этот сигнал.

Когда источник замолкает, сервис поднимает обычную группу алертов с меткой alertname=SourceSilent — она проходит маршрутизацию, цепочку эскалации и доставку ровно тем же путём, что любой другой алерт. Dead-man switch, ходящий к дежурному собственной тропой, был бы единственным алертом, который никто никогда не проверял целиком. Когда источник возвращается, группа закрывается сама.

Поднимается один раз на замолкание, а не каждый цикл: иначе счётчик алертов у группы рос бы, и это читалось бы как шторм от источника, который по определению ничего не шлёт. Есть и метрика nxs_anomaly_sources_silent с правилом SourceSilent — на случай, когда сломалась сама доставка nxs-anomaly.

Плановые работы ​

Не отключайте heartbeat и маршруты перед обслуживанием. Создайте окно, которое явно связывает время работ и затронутые интеграции:

bash
api -X POST "$API/api/v1/maintenance-windows" -d '{
  "name": "Обновление PostgreSQL",
  "reason": "minor upgrade",
  "team_id": "team_...",
  "integration_ids": ["int_..."],
  "starts_at": "2026-08-04T01:00:00+07:00",
  "ends_at": "2026-08-04T03:00:00+07:00"
}'

Во время окна входящие алерты не теряются: новые группы записываются как silenced до ends_at, а heartbeat не создаёт SourceSilent. Группа, которая уже эскалировала до начала работ, продолжает эскалацию.

5.1. Пайплайн приёма: разбор и обогащение алерта ​

Полный разбор конвейера приёма — от нормализаторов источников до удаления данных — в ALERT_PROCESSING.md. Здесь — только настройка пайплайна.

Поле pipeline на интеграции переписывает алерт после выбора маршрута и до всего остального.

Маршрут сознательно остаётся выше пайплайна. Обогащение правят часто и разные люди — лейбл team для дашборда, namespace, вытащенный из заголовка. Если бы это влияло на выбор маршрута, каждая такая правка меняла бы то, кого поднимут ночью, руками человека, который про эскалацию не думал. Поэтому маршрут следует из алерта в том виде, в каком его прислал источник, и чтение маршрутов интеграции даёт полную картину, куда уходят её алерты.

Всё, что ниже по потоку, видит уже обогащённый алерт — и там основная польза: ключ дедупликации и, значит, группировка; сохранённый алерт и его лейблы; текст уведомления. Вырезать build id из заголовка, чтобы ночные падения собрались в один инцидент, — работает. Добавить pod и namespace, которых источник не прислал, — доезжает и до сообщения, и до UI.

Единственное, чего этот порядок не позволяет: правилом перенаправить алерт на другую цепочку эскалации. В этом и смысл.

Пайплайн — список этапов. Каждый этап это одно действие и необязательное условие if. Два действия в одном этапе отклоняются: порядок между ними был бы не виден в конфиге, а порядок здесь и есть вся семантика.

ДействиеЧто делает
extractвытащить именованные группы регулярки из поля в лейблы (аналог grok)
setдобавить или перезаписать лейблы
renameпереименовать лейбл
removeудалить лейблы
gsubпереписать поле регуляркой
truncateограничить длину поля
dropотбросить алерт целиком

Поля, к которым можно обращаться: title, message, severity и label:<имя>.

json
{
  "name": "prometheus-prod",
  "pipeline": [
    { "extract": { "from": "title", "pattern": "pod (?P<pod>\\S+) in (?P<namespace>\\S+)" } },
    { "if": { "field": "label:namespace", "matches": "^pay" }, "set": { "team": "payments" } },
    { "gsub": { "field": "title", "pattern": "\\s+run-[0-9a-f]+$", "replace": "" } },
    { "truncate": { "field": "title", "max": 200 } },
    { "if": { "field": "label:severity", "equals": "info" }, "drop": true }
  ]
}

Условие if принимает ровно одну проверку: equals, matches или exists.

Что стоит знать до того, как это включить ​

  • extract не перезаписывает то, что прислал источник. Он добавляет контекст; чтобы именно заменить лейбл, поставьте после него set — так замена видна как замена.
  • drop без if отклоняется. Безусловный сброс молча выключает интеграцию: она продолжает отвечать 202, а не будит никого.
  • Ошибка этапа не роняет алерт. Этап пропускается, пишется предупреждение alert_pipeline_stage_skipped с номером этапа. Недоставленный алерт хуже необогащённого: первое — пропущенный инцидент, второе — косметика.
  • Ограничения. До 32 этапов, регулярка до 512 символов, поле длиннее 16 КБ не обрабатывается (этап пропускается), до 32 групп в одном extract. Регулярки Go — это RE2, катастрофического бэктрекинга там нет, поэтому лимиты про латентность на горячем пути, а не про ReDoS.
  • Ошибочное правило отклоняется при сохранении интеграции, а не при первом алерте.

Проверка правила до боевого алерта ​

POST /api/v1/routes/debug/{key} прогоняет пайплайн так же, как ingest, и возвращает блок pipeline с labels_before / labels_after, labels_added, labels_changed, labels_removed и title_before / title_after. Сброшенный алерт возвращает result: dropped_by_pipeline. Маршрут в ответе считается по исходным лейблам, как и при приёме, поэтому предпросмотр показывает ровно то, что произойдёт с боевым алертом.

6. Политика уведомлений интеграции ​

notification_policy управляет группировкой и эскалацией по объёму:

bash
api -X PUT "$API/api/v1/integrations/{id}" -d '{
  "notification_policy": {
    "channels": ["telegram", "email"],
    "batch_timeout_seconds": 60,
    "batch_deadline_seconds": 300,
    "epic_threshold_count": 20,
    "epic_threshold_seconds": 600,
    "epic_user_id": "usr_lead",
    "emergency_user_id": "usr_oncall_lead"
  }
}'
  • batch_timeout_seconds — окно тишины: уведомления копятся, пока не пройдёт столько секунд без новых. batch_deadline_seconds — жёсткий предел, после которого батч уходит в любом случае. Оба нуля — батчинг выключен, каждое уведомление уходит сразу. Батчинг откладывает уведомления и отпускает их вместе, но не объединяет в одно сообщение: четыре уведомления одному человеку так и останутся четырьмя письмами, отправленными после окна.
  • epic_threshold_count / epic_threshold_seconds — если за окно набралось столько алертов, дополнительно уведомляется epic_user_id. Это защита от ситуации «шторм идёт, дежурный не справляется».
  • emergency_user_id — получатель шага NOTIFY_EMERGENCY, если тот не задал user_id сам.

7. Личные политики уведомлений ​

По умолчанию все notification_targets пользователя отрабатывают разом. Личная политика превращает это в лестницу с ожиданием — уведомление идёт по каналам по очереди, пока человек не подтвердит алерт:

bash
api -X PUT "$API/api/v1/users/{id}" -d '{
  "notification_policies": {
    "default": [
      {"channel": "telegram", "wait_minutes": 5},
      {"channel": "email",    "wait_minutes": 10},
      {"channel": "call",     "wait_minutes": 0}
    ],
    "important": [
      {"channel": "call",     "wait_minutes": 2},
      {"channel": "telegram", "wait_minutes": 0}
    ]
  }
}'
  • Это opt-in: без notification_policies поведение не меняется.
  • wait_minutes — пауза после шага перед следующим. В примере сначала Telegram, через 5 минут email, ещё через 10 минут звонок.
  • Шаги с wait_minutes: 0 уходят подряд в одном цикле.
  • Прогон останавливается, как только группу подтвердили или закрыли — в этом весь смысл fallback-а.
  • Какую политику применить, решает шаг: {"kind": "NOTIFY_USER", "notify_policy": "important"}. Пустая important откатывается на default.

Почта (SMTP) ​

Письма отправляются через SMTP-сервер, настроенный у API и worker:

ПеременнаяПо умолчаниюНазначение
NXS_ANOMALY_SMTP_HOST—SMTP-сервер; без него канал email получает skipped / not_configured
NXS_ANOMALY_SMTP_PORT465Порт
NXS_ANOMALY_SMTP_USE_TLStruetrue — TLS с первого байта (порт 465); false — обычное соединение со STARTTLS, если сервер его предлагает (порт 587 или 25)
NXS_ANOMALY_SMTP_USERNAME, NXS_ANOMALY_SMTP_PASSWORD—Учётные данные; без имени пользователя аутентификация не выполняется
NXS_ANOMALY_SMTP_SENDERимя пользователяАдрес отправителя (конверт и From)
NXS_ANOMALY_SMTP_FROMNixys AlerterОтображаемое имя в From

Пароль храните в Secret, а не в values. Тема письма — [severity] заголовок ([RESOLVED] … для уведомления о закрытии), поэтому почтовый клиент группирует письма по инцидентам; тело — UTF-8. Прежде чем полагаться на канал, проверьте его кнопкой тестового уведомления в карточке пользователя.

8. ChatOps ​

Канал — это общий чат: адрес, по которому туда уходят оповещения, и привязка chat id → канал, по которой набранные там команды находят свою команду-владельца. Для переписки бота с человеком один на один канал не нужен и не создаётся: личные уведомления идут по telegram_id пользователя, а кнопки под ними выполняются от его имени (см. раздел про Telegram-бота).

bash
api -X POST "$API/api/v1/chatops/channels" -d '{
  "name": "#alerts-platform",
  "platform": "slack",
  "team_id": "team_...",
  "webhook_url": "https://hooks.slack.com/services/...",
  "external_id": "C01234567",
  "notifications_enabled": true,
  "commands_enabled": true
}'

Обязательны только platform и name. Остальное определяет, что канал реально умеет:

  • webhook_url — исходящие сообщения. Без него канал существует только внутри сервиса: отправить в него ничего нельзя, и уведомления для него получают статус skipped, а не «доставлено».
  • headers — дополнительные заголовки каждого запроса к webhook_url, для шлюза, который проверяет вызывающего по Authorization или X-API-Key ({"Authorization": "env:NXS_ANOMALY_GATEWAY_AUTH"}). Правила те же, что у заголовков TRIGGER_WEBHOOK (раздел 4); null или {} в обновлении их удаляет.
  • external_id — идентификатор канала на стороне платформы (id канала Slack, chat id Telegram). Входящие slash-команды приходят с ним, а не с внутренним id, поэтому без него команды из этого канала не сопоставятся.

Для входящих команд (подтверждение алерта прямо из чата) настройте подпись: NXS_ANOMALY_SLACK_SIGNING_SECRET, NXS_ANOMALY_TELEGRAM_WEBHOOK_SECRET или NXS_ANOMALY_MATTERMOST_COMMAND_TOKEN. Без секрета соответствующий эндпоинт отвечает 501 — неподписанные команды не принимаются.

Добавление Telegram-бота ​

Есть три сценария; включать их можно по отдельности, и они требуют разного.

Что нужноТокен бота (шаг 2)Секрет + setWebhook (шаги 4–5)ChatOps-канал (шаг 6)
Личные уведомления — сервис пишет человеку по его telegram_idданетнет
Кнопки под личным уведомлением — Acknowledge, Resolve, «I am on duty»даданет
ChatOps-бот в общем чате — рассылка в группу и команды из неёдадада

Средняя строка — та, о которую чаще всего спотыкаются. Кнопка приходит вместе с личным уведомлением и требует только вебхука: нажатие прилетает из лички, а личка ничьим ChatOps-каналом не является, и команда выполняется от имени того пользователя, чей telegram_id совпал с отправителем, в границах его роли и команд. Канал (шаг 6) нужен ровно для общего чата: он даёт чату адрес для рассылки (webhook_url), сопоставление chat id → канал для набранных там команд и команду-владельца (team_id), которой ограничено то, что из этого чата видно.

1. Создайте бота и получите токен.

В Telegram напишите @BotFather:

/newbot

Задайте имя и username (должен заканчиваться на bot). BotFather вернёт токен вида 123456789:AAExampleTokenDoNotUseInProd.

2. Положите токен в секрет инсталляции.

Ключ секрета совпадает с именем переменной окружения — envFrom подключает секрет целиком:

bash
kubectl create secret generic nxs-anomaly-env \
  --from-literal=NXS_ANOMALY_DB_DSN=... \
  --from-literal=NXS_ANOMALY_TELEGRAM_BOT_TOKEN='123456789:AAExampleTokenDoNotUseInProd'

(если секрет уже существует — kubectl edit secret или --dry-run=client -o yaml | kubectl apply -f -, не пересоздавайте существующий объект с нуля). В dev-инсталляции с inlineSecret — та же переменная в values.yaml.

Одного этого шага достаточно для личных уведомлений: добавьте пользователю telegram_id и telegram в notification_targets (см. раздел 1) — доставка пойдёт через Bot API sendMessage без дополнительной настройки вебхука.

Кнопки Acknowledge / Resolve под таким уведомлением — отдельная строка таблицы выше: нужны шаги 4–5 (без вебхука Telegram некуда сообщить о нажатии), но не нужен шаг 6.

3. Для общего чата — узнайте chat id. (Для личных уведомлений и кнопок под ними шаг не нужен: сервис пишет в личку по telegram_id пользователя.)

  • Личка: напишите боту любое сообщение и откройте https://api.telegram.org/bot<TOKEN>/getUpdates — chat.id в ответе.
  • Группа/канал: добавьте бота участником, отправьте туда сообщение и посмотрите тот же getUpdates — id группы отрицательный (-100...).

4. Сгенерируйте секрет и включите приём входящих команд.

bash
openssl rand -hex 32

Значение — в NXS_ANOMALY_TELEGRAM_WEBHOOK_SECRET, тем же способом, что и токен на шаге 2. Без этой переменной эндпоинт /integrations/v1/chatops/telegram отвечает 501 и неподписанные апдейты не принимает.

5. Зарегистрируйте вебхук в Telegram.

Публичный URL сервиса должен быть на HTTPS. Вызовите setWebhook с тем же секретом:

bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://<ваш-хост>/integrations/v1/chatops/telegram" \
  -d "secret_token=<значение NXS_ANOMALY_TELEGRAM_WEBHOOK_SECRET>"

Проверить, что Telegram видит вебхук и не копит ошибки доставки:

bash
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

6. Создайте ChatOps-канал — только для общего чата. Для кнопок под личными уведомлениями шаг пропускается: там всё уже работает после шага 5.

bash
api -X POST "$API/api/v1/chatops/channels" -d '{
  "name": "Дежурные — платформа",
  "platform": "telegram",
  "team_id": "team_...",
  "external_id": "-100500",
  "notifications_enabled": true,
  "commands_enabled": true
}'

external_id — chat id с шага 3. Чтобы отдельные люди в общем чате опознавались по имени в аудите и командах ack/resolve, у их пользователей тоже должен быть проставлен telegram_id (шаг 1 в начале раздела) — иначе команда выполняется от общего сервисного принципала chatops:telegram с ролью responder.

Проверка целиком: отправьте /status боту в настроенный чат. Кнопки проверяются отдельно и без канала — дождитесь следующего оповещения в личке и нажмите Acknowledge; группа должна перейти в acknowledged, а подтвердившим в аудите должен быть человек, а не сервисный принципал chatops:telegram.

Кнопки под алертом ​

Под алертом на всех трёх платформах одни и те же действия:

КнопкаЧто делает
Acknowledgeвзял в работу; эскалация останавливается
Resolveзакрыл
Silence 1h / 4h / 8hзамолчать на срок; эскалация останавливается, статус silenced
Open in nxs-anomalyссылка на карточку группы; требует NXS_ANOMALY_PUBLIC_URL

После нажатия сообщение не заменяется вердиктом: текст алерта остаётся, к нему дописывается результат, а вместо прежних кнопок остаётся одна — отмена (Undo acknowledge после Acknowledge, Reopen после Resolve). Промах по кнопке с телефона правится там же, без входа в интерфейс. У Silence отмены нет: он истекает сам.

В списке /alerts каждая строка — две кнопки: подпись открывает карточку, ✓ подтверждает. Ниже строк — Acknowledge all open и Silence all 1h на случай шторма; обе действуют на все открытые группы, видимые вызвавшему.

Добавление Mattermost-бота ​

Двусторонний бот требует двух значений, и это разные значения.

1. Кнопки (исходящее + нажатия). NXS_ANOMALY_PUBLIC_URL — адрес, на который Mattermost вернёт нажатие, и NXS_ANOMALY_MATTERMOST_ACTION_SECRET — произвольный секрет (openssl rand -hex 32). Mattermost не подписывает эти колбэки: секрет едет в контексте кнопки и сверяется постоянным по времени сравнением. Без любого из двух алерт уходит без кнопок — кнопка, ведущая на адрес, который никто не слушает, хуже её отсутствия.

2. Команды. В Mattermost: Integrations → Slash Commands → Add. Request URL — https://<ваш-хост>/integrations/v1/chatops/mattermost/command, метод POST. Mattermost выдаст свой токен — его в NXS_ANOMALY_MATTERMOST_COMMAND_TOKEN. Задать этот токен самому нельзя, поэтому он никогда не совпадает с секретом из шага 1.

Триггер выбирайте любой (/nxs, /oncall) — он отбрасывается, а аргументы и есть команда: /nxs ack grp_1 выполняет ack grp_1, /nxs без аргументов — help. Это отличается от Slack, где триггером служит сам глагол и каждая команда регистрируется отдельно.

3. Привязка людей. Чтобы действия из Mattermost приписывались человеку, а не боту, проставьте пользователю mattermost_id (в интерфейсе — поле рядом с Telegram ID). Без него команда выполняется от сервисного принципала chatops:mattermost с ролью responder, а duty и priority отказывают: они требуют человека. То же поле для Slack называется slack_id.

9. Прокси для исходящей доставки ​

Нужен там, где провайдер недоступен напрямую: мессенджер заблокирован в сети, или из кластера наружу пускают только через один аудируемый хоп. Без прокси такое уведомление падает на этапе установки соединения, уходит в retry и в итоге в dead letter — то есть алерт просто не доходит.

Настраивается переменными окружения, как и остальные креды доставки:

ПеременнаяЧто задаёт
NXS_ANOMALY_DELIVERY_PROXY_URLПрокси по умолчанию для всех каналов доставки
NXS_ANOMALY_DELIVERY_PROXY_<КАНАЛ>_URLПереопределение для одного канала; direct — не проксировать его
NXS_ANOMALY_DELIVERY_NO_PROXYХосты, к которым всегда ходим напрямую

Схемы http, https, socks5, socks5h, tcp (прозрачный релей, HAProxy mode tcp — для него порт обязателен). Типичная конфигурация «заблокированы только мессенджеры»:

bash
NXS_ANOMALY_DELIVERY_PROXY_TELEGRAM_URL='socks5://tunnel.internal:1080'
NXS_ANOMALY_DELIVERY_PROXY_SLACK_URL='socks5://tunnel.internal:1080'
NXS_ANOMALY_DELIVERY_NO_PROXY='receiver.internal,.corp.example'

Три вещи, о которых стоит знать до того, как они удивят:

  • email и call не HTTP — их несут только socks5:// и tcp://, HTTP-прокси для них игнорируется;
  • tcp://-релей слеп к назначению — он шлёт всё в свой единственный бэкенд, поэтому подходит каналам с фиксированным хостом провайдера, а для webhook, issue и chatops при старте пишется предупреждение;
  • ошибка в URL прокси не превращается в «отправим напрямую» — канал падает с внятной причиной, а /api/v1/readiness считает его каналом без транспорта;
  • SSRF-гейт для проксированного канала меняет форму — адрес назначения резолвит прокси, поэтому проверки на соединении нет; IP-литерал или имя, локально резолвящееся в непубличный адрес, по-прежнему отвергаются заранее.

Полностью — каналы, взаимодействие с гейтом, Helm, диагностика и частые ошибки — в отдельном документе PROXY.md.

10. Проверка ​

Три уровня, от дешёвого к настоящему.

Готовность инсталляции — десять проверок: база, worker, интеграции, маршрутизация, доступность каналов и дежурных, покрытие расписаний, граница команд, retention и свежесть резервной копии:

bash
api "$API/api/v1/readiness"

Проверка, которая не смогла выполниться, считается блокером, а не пропуском.

Маршрутизация — POST /api/v1/routes/debug/<key>, см. выше.

Настоящий алерт — единственный способ убедиться в доставке:

bash
curl -X POST "$API/integrations/v1/webhook/<key>" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Проверка связи","severity":"critical","status":"firing",
       "labels":{"service":"postgres"}}'

Затем посмотрите timeline группы — там по шагам видно, кого уведомили и что ответил провайдер:

bash
api "$API/api/v1/alert-groups"
api "$API/api/v1/alert-groups/{id}/timeline"
api "$API/api/v1/delivery-attempts?alert_group_id={id}"

Первое уведомление уходит не мгновенно: доставка вынесена из транзакции приёма, поэтому задержка до одного цикла worker-а (--poll-interval, по умолчанию 5 секунд) — норма, а не поломка.

Частые ошибки ​

СимптомПричина
integration must contain exactly one default routeВ routes ноль или больше одного is_default
Создание цепочки падает на NOTIFY_SCHEDULEВ расписании пробел в ближайшие 7 дней. Закройте дыру или задайте allow_uncovered: true осознанно
Шаг «выполняется», но никого не уведомляетТип шага задан полем type вместо kind
Уведомления со статусом skipped / not_configuredКанал не настроен в окружении (нет токена бота, SMTP и т.п.)
channel_blocked_by_policyКанал запрещён через NXS_ANOMALY_BLOCKED_CHANNELS
destination_not_allowlistedАдрес назначения не входит в NXS_ANOMALY_EGRESS_ALLOWLIST
Уведомление «ушло», но человек ничего не получилУ пользователя пустые notification_targets → fallback log
NOTIFY_DUTY_USERS пейджит всех подрядНи у кого нет on_duty: true, сработал fallback_to_all
В timeline notify_skipped_unknown_usersРасписание ссылается на удалённого пользователя
TRIGGER_WEBHOOK не проходит в productionSSRF-гейт: адрес приватный, loopback или link-local
delivery proxy ... is misconfiguredОпечатка в NXS_ANOMALY_DELIVERY_PROXY_*_URL; напрямую сервис в этом случае намеренно не отправляет
400 про env: при сохранении секретаProduction-профиль запрещает inline-секреты, нужна ссылка env:ИМЯ_ПЕРЕМЕННОЙ

Что дальше ​

  • DOMAIN_MODEL.md — модель данных и правила движка

  • API.md — полный справочник эндпоинтов

  • SECURITY_PROFILE.md — production-профиль и что он ужесточает

  • ALERTING_RULES.md — мониторинг самого nxs-anomaly

  • KAFKA.md — выгрузка событий в аналитику

  • DATA_INVENTORY.md — какие персональные данные где лежат, сроки хранения, экспорт и удаление по запросу человека

nxs-anomaly · Documentation