Skip to content

Kafka Analytics Integration ​

nxs-anomaly поддерживает асинхронную отправку алертов в Kafka по паттерну Transactional Outbox. Kafka выступает шиной данных для последующей загрузки в ClickHouse или другие аналитические системы.

Архитектура ​

webhook → IngestAlert()
               │
               ▼ (одна транзакция PostgreSQL)
     ┌──────────────────────────────────┐
     │  nxs_anomaly_alerts              │
     │  nxs_anomaly_alert_groups        │
     │  nxs_anomaly_kafka_outbox  ← NEW │
     └──────────────────────────────────┘
               │
               ▼ (worker cycle, каждые poll-interval секунд)
     PublishKafkaOutbox()
               │
               ▼
     Kafka topic: nxs-anomaly.alerts
               │
               ▼
     ClickHouse Kafka Engine → MergeTree

Гарантии доставки ​

  • Crash-safe: outbox-строка записывается атомарно с алертом. Если процесс упадёт до publish — запись остаётся в outbox и будет опубликована на следующем цикле.
  • At-least-once: если процесс упадёт после publish, но до удаления строки из outbox, событие будет опубликовано повторно. Повторная публикация побайтово идентична исходной, поэтому дедупликация возможна — но только если таблица для неё построена (ReplacingMergeTree, см. ниже). На обычном MergeTree дубли просто задваивают аналитику.
  • Нет блокировки ingest: Kafka-событие пишется в PostgreSQL в том же батче, что и алерт — нулевой overhead на latency HTTP-запроса.

Настройка ​

Переменные окружения ​

ПеременнаяПо умолчаниюОписание
KAFKA_BROKERS—Брокеры через запятую, например kafka:9092. Если не задано — Kafka отключена.
KAFKA_TOPIC_ALERTSnxs-anomaly.alertsТопик по умолчанию для событий alert.ingested.
KAFKA_BATCH_SIZE100Максимальный размер батча продьюсера.
NXS_ANOMALY_ANALYTICS_PSEUDONYMISEfalseЗаменять user_id и team_id односторонними стабильными дайджестами до записи в outbox.

Если KAFKA_BROKERS не задан — outbox не заполняется, Kafka-шаг в worker-цикле пропускается.

Кто создаёт топик ​

Продьюсер разрешает брокеру создать отсутствующий топик, поэтому решение остаётся за брокером: при auto.create.topics.enable=true (умолчание Kafka и настройка встроенного в chart брокера) топик появится при первой публикации, при false — публикация не пройдёт, и worker скажет об этом в журнал как kafka_publish_failed, а события останутся в outbox до починки.

Для production топик обычно создают заранее — так вы контролируете число партиций, replication factor и retention. Автосоздание даст топик с умолчаниями брокера.

Исторически продьюсер запрещал автосоздание независимо от настройки брокера, из-за чего инсталляция без заранее созданного топика не публиковала ничего: события копились в nxs_anomaly_kafka_outbox, а аналитика оставалась пустой. Исправлено (см. CHANGELOG). При обновлении с версии, где этого фикса ещё не было, накопившийся outbox опубликуется сам на ближайших worker-циклах — перекладывать события руками не нужно.

Маршрутизация по топикам (multi-topic) ​

Каждая интеграция может задать индивидуальный Kafka-топик через поле kafka_topic:

bash
curl -X PUT /api/v1/integrations/{id} \
  -H "Content-Type: application/json" \
  -d '{"kafka_topic": "nxs-anomaly.pagerduty"}'

Если kafka_topic у интеграции не задан — используется глобальный KAFKA_TOPIC_ALERTS. Это позволяет разделить потоки по источникам (alertmanager, pagerduty, grafana-alerting) для независимой аналитики.

Multi-replica: advisory lock ​

PublishKafkaOutbox захватывает session-level PostgreSQL advisory lock (ключ 72544106) через pg_try_advisory_lock. Это предотвращает одновременную публикацию одних и тех же событий несколькими worker-репликами.

Поведение:

  • Worker A получает lock → читает outbox → публикует → удаляет → unlock.
  • Worker B пытается взять lock → не получает → пропускает цикл (return 0, nil) → повторяет попытку в следующем цикле.

Семантика доставки — at-least-once: если процесс упал после Kafka-publish, но до удаления строки из outbox — событие будет опубликовано повторно в следующем цикле. Таблица приёмника обязана это учитывать — см. «Приём в ClickHouse».

Запуск ​

bash
# API + встроенный worker (development)
KAFKA_BROKERS=localhost:9092 \
KAFKA_TOPIC_ALERTS=nxs-anomaly.alerts \
nxs-anomaly serve --host 0.0.0.0 --port 8080

# Production: API без scheduler
KAFKA_BROKERS=kafka:9092 nxs-anomaly serve --no-scheduler

# Production: отдельный worker
KAFKA_BROKERS=kafka:9092 nxs-anomaly run-worker --poll-interval 5

Схема Kafka-сообщения ​

Каждое сообщение в топике — JSON-объект:

json
{
  "event_id": "evt_...",
  "event": "alert.ingested",
  "schema_version": 2,
  "occurred_at": "2026-06-06T12:00:00Z",
  "published_at": "2026-06-06T12:00:00Z",
  "entity": {
    "alert_id": "alr_...",
    "alert_group_id": "grp_...",
    "episode_id": "epd_...",
    "integration_id": "int_...",
    "team_id": "",
    "route_id": "rte_...",
    "escalation_chain_id": "esc_...",
    "notification_id": "",
    "user_id": ""
  },
  "data": {},
  "alert": {
    "id": "alr_...",
    "alert_group_id": "grp_...",
    "integration_id": "int_...",
    "status": "firing",
    "severity": "critical",
    "source": "alertmanager",
    "title": "High CPU on web-01",
    "labels": { "host": "web-01", "alertname": "HighCPU" },
    "received_at": "2026-06-06T12:00:00Z"
  },
  "group": {
    "id": "grp_...",
    "status": "open",
    "severity": "critical",
    "alert_count": 3,
    "created_at": "2026-06-06T11:55:00Z",
    "last_received_at": "2026-06-06T12:00:00Z",
    "resolved_at": null
  }
}

Поле group равно null для алертов с типом resolved_without_group (алерт пришёл с status=resolved, но активной группы не было).

Message key: alert.id — обеспечивает аффинность партиций по алертам.

Envelope v2 ​

v2 добавляет конверт вокруг прежнего сообщения: alert и group сохранили имена, форму и место, поэтому существующий consumer продолжает шейпить это сообщение как раньше. Новое — четыре поля:

ПолеСмысл
event_idГенерируется один раз при создании outbox-строки и лежит внутри сохранённого payload. Публикация at-least-once: строка переживает падение между publish и delete, поэтому один и тот же payload уходит дважды. Дедупликация вниз по потоку идёт по event_id, и это работает только потому, что payload переотправляется побайтово, а не пересобирается.
occurred_atВремя доменного перехода. published_at — время создания outbox-строки. Kafka-ретрай через час не меняет ни одно из них: иначе backlog нельзя отличить от медленного подтверждения.
entityВсе идентификаторы измерений, всегда одним и тем же набором ключей, даже пустыми: consumer раскладывает их в фиксированные колонки, а ключ, который появляется через раз, превращается в NULL с двумя разными смыслами.
dataПоля конкретного события. Проходит через централизованный denylist: target, токены, URL, email, телефон, provider body туда не попадают. Хранилище аналитики читает больше людей и держит дольше, чем диагностику доставки в PostgreSQL.

alert/group присутствуют только у alert.ingested; остальные события их не несут.

Эпизоды ​

episode_id — один проход группы по жизненному циклу. Группу можно прожить несколько раз: новый алерт после подтверждения и Unresolve после закрытия начинают новый эпизод. Без этого MTTA/MTTR группы, которая четыре раза возвращалась, усредняются в один «медленный инцидент», а последний resolve переписывает MTTR предыдущего.

Поле лежит в Extra alert group, без миграции и без typed-колонки. Группам, созданным до появления эпизодов, идентификатор назначается лениво, при первом переходе: значимы те группы, с которыми ещё работают.

События жизненного цикла ​

alert_group.opened/reopened/acknowledged/unacknowledged/silenced/resolved и notification.delivery_attempted включаются флагом KAFKA_ANALYTICS_LIFECYCLE_ENABLED (по умолчанию выключен). Причина в порядке раскатки: текущий Vector шейпит каждое сообщение через object!(.alert), поэтому lifecycle-сообщение, дошедшее до старой конфигурации, будет отвергнуто — уже после того, как offset подтверждён. Сначала схема и маршрутизация, потом emission.

ClickHouse: приём данных ​

Вариант 1 — Vector (рекомендуется, входит в chart) ​

Чарт разворачивает готовый consumer: kafkaConsumer.enabled=true плюс источник (kafka.enabled или externalKafka.enabled) и приёмник (clickhouse.enabled или externalClickHouse.enabled). Без обоих концов рендер падает — pod, который будет CrashLoop-ить при «успешном» релизе, не выпускается.

Вместе с consumer-ом чарт запускает post-install hook, создающий таблицу:

sql
CREATE TABLE IF NOT EXISTS nxs_alerts_log
(
    received_at     DateTime,
    integration_id  String,
    alert_id        String,
    alert_group_id  String,
    status          LowCardinality(String),
    severity        LowCardinality(String),
    source          LowCardinality(String),
    title           String,
    labels          String,
    group_status    LowCardinality(String),
    group_count     UInt32,
    published_at    DateTime
)
ENGINE = ReplacingMergeTree(published_at)
PARTITION BY toYYYYMM(received_at)
ORDER BY (received_at, integration_id, alert_id);

ReplacingMergeTree — не украшение: продьюсер at-least-once, и повторно опубликованное событие совпадает по всем трём полям ключа сортировки, поэтому дубль схлопывается. Схлопывание происходит в фоновых merge-ах, то есть асинхронно: там, где счёт должен быть точным, читайте вью nxs_alerts_log_deduplicated (это SELECT * ... FINAL) или добавляйте FINAL сами.

Журнал событий nxs_events_raw ​

nxs_alerts_log — узкая проекция одного события, alert.ingested. Всё остальное (переходы группы, попытки доставки) хранится в отдельной таблице, которую создаёт тот же hook:

sql
CREATE TABLE IF NOT EXISTS nxs_events_raw
(
    event_id            String,
    event_type          LowCardinality(String),
    schema_version      UInt16,
    occurred_at         DateTime64(3, 'UTC'),
    published_at        DateTime64(3, 'UTC'),
    ingested_at         DateTime64(3, 'UTC'),
    alert_id            String,
    alert_group_id      String,
    episode_id          String,
    integration_id      String,
    team_id             String,
    route_id            String,
    escalation_chain_id String,
    notification_id     String,
    user_id             String,
    alertname           LowCardinality(String),
    service             LowCardinality(String),
    environment         LowCardinality(String),
    cluster             LowCardinality(String),
    host                String,
    payload             String
)
ENGINE = ReplacingMergeTree(ingested_at)
PARTITION BY toYYYYMM(occurred_at)
ORDER BY (toDate(occurred_at), event_type, integration_id, alert_group_id, episode_id, event_id);

Что здесь неочевидно:

  • Три отметки времени, а не одна. occurred_at — время доменного перехода, published_at — время создания outbox-строки, ingested_at — время вставки строки. Первые две штампуются один раз и переживают повторную публикацию, третья — нет. Именно это позволяет отличить backlog от медленного подтверждения.
  • event_id замыкает ключ сортировки. Он делает ключ уникальным, поэтому дедупликация точна, а не «скорее всего». Версионная колонка — ingested_at, и в ключ она не входит: это единственное поле, которым копии различаются. Схлопывание асинхронно, поэтому дашборды читают вью nxs_events_raw_deduplicated (SELECT * ... FINAL), а не таблицу.
  • payload хранит сообщение целиком. Вопрос, который никто не предвидел, можно будет задать без нового деплоя. Payload уже отредактирован на стороне продьюсера: ни target, ни provider body, ни учётные данные сюда не доезжают.
  • Метки хранятся дважды. В payload — полностью, плюс пять промотированных колонок, по которым группирует каждый дашборд. JSON-извлечение на строку по месяцу алертов — это разница между дашбордом, которым пользуются, и дашбордом, который перестали открывать.

Маршрутизация: одна тема, два приёмника ​

Тема одна, поэтому Vector классифицирует сообщение явно:

  • classify.v2 (schema_version >= 2) → таблица событий целиком;
  • фильтр ingested_only → только alert.ingested попадает в nxs_alerts_log (легаси-трансформ начинается с object!(.alert) и отверг бы всё остальное);
  • classify.legacy_ingested — сообщение долетевшее от pre-v2 релиза во время апгрейда: у него нет event_id, дедуплицировать его нечем, поэтому в журнал событий оно не идёт, а в легаси-таблицу — идёт;
  • всё прочее — classify._unmatched → sink rejected, то есть stdout и счётчики. Тихий дроп здесь означал бы событие, которое не доехало до аналитики, на основании которой кто-то принимает решение.

Семантические вью ​

Поверх nxs_events_raw_deduplicated тот же hook создаёт обычные вью (CREATE OR REPLACE, поэтому апгрейд чарта обновляет и семантику):

ВьюОдна строка — этоДля чего
nxs_episode_dimensionsодна группаlabels первого firing-алерта; лейблы пустые на lifecycle-событиях, а join алертов к эпизодам размножил бы строки
nxs_group_episodesодин эпизод группыстадии отклика, superseded, resolution, флаги пригодности
nxs_episode_factодин эпизод группыто же плюс severity/service/environment и единственный outcome; это то, что читают дашборды
nxs_delivery_attemptsодин вызов провайдера либо осознанный skipразложенный JSON, purpose, episode_id, team_id
nxs_notification_factодно уведомлениеисход уникального уведомления, а не отдельных попыток
nxs_group_state_latestодна группасостояние сейчас, для backlog
nxs_response_objectivesцель на (service, severity, valid_from)таблица, не вью; '*' — джокер
nxs_episode_objectivesодин эпизодкакая цель к нему применилась
nxs_response_attainmentсутки × команда × сервис × severitymatured / on time / late / pending
nxs_schedule_coverageрасписание × проверкадыры в ротациях; report_id — чтобы взять общие счётчики один раз
nxs_daily_alert_qualityсутки × интеграцияобъём и шум, firing и resolving порознь
nxs_daily_delivery_qualityсутки × канал × purposedelivered/failed/skipped, retry, перцентили и mergeable состояния
nxs_daily_response_qualityсутки × командаперцентили стадий и mergeable состояния
nxs_analytics_healthтип событиясвежесть, лаг и полнота — читать до всего остального

Три вещи в этом наборе легко прочесть неправильно:

  • Готовые перцентили нельзя объединять. p95_mtta_seconds верен для одной команды за одни сутки. Панель, охватывающая несколько команд или неделю, читает соседнюю колонку mtta_p95_state через quantileMerge — среднее из p95 не p95. По той же причине доли считаются как sum(числитель)/sum(знаменатель): у команды с одним эпизодом и у команды с сотней иначе одинаковый вес.
  • Знаменатель выполнения цели — matured-когорта. Эпизод, у которого срок вышел и ACK нет, — нарушение; у которого срок не вышел — pending, не успех. Доля «быстрых среди ответивших» улучшалась бы каждый раз, когда инцидент затягивается.
  • superseded — не незакрытая работа. Эпизод без resolve, у которого есть следующий эпизод той же группы, был вытеснен, а не заброшен.

Материализованных вью здесь нет и не будет без отдельного дизайна. Поток at-least-once: инкрементальная MV прибавляет дубль в момент прихода, а поздний merge, схлопывающий его в raw-таблице, обратно не вычитает — KPI после этого неверен молча и навсегда. Пред-агрегаты появятся, только если дашборд перестанет укладываться в 2 секунды, и тогда с дедупликацией, а не вместо неё.

Что здесь неочевидно:

  • Эпизод, а не группа. Группу могут разбудить второй раз (новый алерт по reopen, ручной unresolve). Каждый заход — свой эпизод, иначе повторное открытие переписывает MTTR первого ответа.
  • Событиям доставки эпизод присваивается по времени. Их пишет worker доставки, чья транзакция не грузит группу, поэтому episode_id в них пуст. Вью протягивает вперёд последний увиденный по этой группе эпизод (anyLast(...) OVER (...)), а это корректно потому, что события группы ключуются её id и лежат в одной партиции по порядку.
  • Незавершённый эпизод не «медленный». Без ACK/resolve соответствующая метрика NULL: в перцентили не попадает, но видна отдельными счётчиками never_acknowledged/unresolved. Доля в пороге считается по эпизодам, которые дошли, — иначе затянувшийся инцидент её улучшал бы.
  • delivery_rate не учитывает skip. Канал без транспорта не падал, его не пробовали; сложить их — значит спрятать ошибку конфигурации за хорошим числом. Skip виден отдельной колонкой.
  • Первый page — только доставленный. Неудачные и пропущенные попытки, сколько бы их ни было, в first_delivered_at не считаются.

Пороги — значения чарта: kafkaConsumer.analytics.mttaTargetSeconds (по умолчанию 300) и mttrTargetSeconds (3600). Вью показывает долю, а не вердикт.

Эскалация, покрытие и детекция ​

Три вещи, которых в первой итерации не было:

  • Глубина эскалации. Каждый исполненный шаг цепочки — событие alert_group.escalation_step (индекс, вид шага, счётчик REPEAT). Из финального состояния группы это не выводится: подтверждённая с первого пейджа и подтверждённая после четырёх шагов и повтора обе выглядят как «acknowledged». Отдельно есть alert_group.escalation_exhausted — цепочка кончилась, а группа всё ещё открыта: всех, кого называет политика, попробовали, и никто не ответил. Это единственное событие про «процесс не дотянулся», и вывести его из шагов нельзя — цепочка, стоящая на последнем WAIT, снаружи выглядит так же. В nxs_group_episodes появились escalation_steps, max_escalation_step и escalation_exhausted.

  • Покрытие расписаний. Воркер и раньше раз в минуту считал отчёт покрытия для метрики Prometheus; теперь тот же отчёт уходит событием schedule.coverage_reported. Смысл — история: gauge отвечает «сколько дыр сейчас» и ничего не помнит о расписании, которое уже починили, поэтому вопрос «сколько эта дыра простояла» отвечается только здесь. Вью nxs_schedule_coverage — строка на расписание на проверку. Имена расписаний в аналитику не уходят (в имени бывает клиент или человек), только идентификаторы и счётчики.

  • MTTD. Событие открытия эпизода несёт source_started_at — время, которое назвал сам источник (startsAt у Alertmanager, starts_at у generic-payload). detection_seconds в nxs_group_episodes — интервал от него до открытия группы. Два ограничения, которые нельзя замалчивать: время сообщает отправитель, поэтому у монитора с уехавшими часами будет уехавшая детекция; а источник, который времени не сообщает, даёт NULL, а не ноль — иначе «ничего не сказал» читалось бы как «обнаружено мгновенно» и улучшало бы KPI. Поэтому MTTD живёт отдельной колонкой и в MTTA не подмешивается; episodes_with_source_time говорит, по какой доле эпизодов он вообще посчитан.

Все три — за тем же флагом kafkaConsumer.analytics.lifecycleEvents. Считайте объём: шаги эскалации — самое частое из lifecycle-событий, шторм умножает их на число шагов цепочки.

Rollups (по умолчанию выключены) ​

kafkaConsumer.analytics.rollups.enabled=true добавляет три дневные пред-агрегированные таблицы (nxs_rollup_daily_response, …_delivery, …_alerts) и CronJob, который их пересобирает.

Пересборка, а не инкремент. Инкрементальная материализованная вью поверх at-least-once потока прибавляет дубль в момент прихода и никогда не вычитает его обратно; пересчёт закрытого дня из дедуплицированного источника дрейфовать не может, а повторный запуск ничего не меняет, потому что таблицы схлопываются по ключу (day, измерение).

  • rebuildDays (3) — сколько последних дней пересчитывать. Окно должно перекрывать самый долгий правдоподобный catch-up после простоя Kafka или ClickHouse: день, пересобранный до прихода опоздавших событий, останется неверным до следующей пересборки.
  • concurrencyPolicy: Forbid — пересборка, наехавшая сама на себя, пишет те же строки дважды и отбирает у consumer-а память, нужную ему для вставок.
  • Таблицы объявлены как AS SELECT … WHERE 0, то есть их колонки — колонки вью по построению. Обратная сторона: изменение формы вью не мигрирует уже созданную rollup-таблицу — удалите её, hook создаст заново.

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

Дашборды Grafana ​

docs/enterprise/grafana/ — десять дашбордов, по одному вопросу на каждый, вместо одного общего:

ФайлНа какой вопрос отвечает
01-response-overview.jsonгде реагирование идёт не так, на уровне владельца сервиса
02-response-latency.jsonна какой стадии задержка: до страницы, после неё или после ACK
03-active-backlog.jsonчто не закрыто сейчас
04-alert-volume.jsonкакие правила и интеграции дают объём и страницы
05-notification-delivery.jsonдоходят ли уведомления и по какому каналу ломается
06-routing-escalation.jsonкакие цепочки затягивают или заканчиваются ничем
07-oncall-load.jsonкак часто прерывают людей
08-schedule-coverage.jsonкакие дыры в расписаниях известны заранее
09-episode-explorer.jsonразбор одного эпизода по первичным событиям
10-analytics-data-quality.jsonможно ли верить остальным девяти

Импортировать первым 10-analytics-data-quality.json. Пустой график отклика даёт и тихая неделя, и потребитель, остановившийся три дня назад; отличает их только этот дашборд.

При импорте задаётся datasource ClickHouse и константа db (база из clickhouse.auth.database, по умолчанию nxs_anomaly). Переменные team, service и severity применяются на всех панелях, где измерение действительно доступно; там, где нет, это сказано в описании панели.

Обоснование состава, словарь метрик и то, чего в данных нет, — INCIDENT_ANALYTICS_DASHBOARDS.md.

Доступ Grafana: только чтение ​

Заводить отдельного пользователя ClickHouse, не переиспользовать того, которым пишет Vector: у продьюсера есть DDL и INSERT, а дашборду нужен SELECT по вью.

sql
CREATE USER grafana IDENTIFIED BY '...' SETTINGS max_execution_time = 30;
GRANT SELECT ON nxs_anomaly.* TO grafana;

max_execution_time — часть контракта, а не перестраховка: вью читают FINAL, и запрос на неудачно выбранном диапазоне способен занять сервер, который в этот момент нужен consumer-у для вставки. TLS до ClickHouse включается на стороне datasource; пароль хранить в secret Grafana, не в JSON дашборда.

Границы аналитики beta ​

  • MTTD считается только при наличии времени источника. Если источник не передал starts_at, detection_seconds остаётся NULL, а не превращается в искусственный ноль. Долю пригодных эпизодов показывает episodes_with_source_time.
  • Покрытие расписаний — периодический sample. Gauge показывает состояние в момент измерения и не восстанавливает задним числом уже исправленную дыру.
  • Episode id доставки снапшотится на уведомлении. Для старых уведомлений без поля остаётся временная атрибуция; новые не переезжают в другой эпизод после reopen группы.
  • Rollups opt-in и пересобираются. Они не являются инкрементальной materialized view над at-least-once потоком; изменение формы semantic view требует согласованной миграции соответствующей rollup-таблицы.
  • Данные до включения флага неполны по построению: до этого момента публиковался только alert.ingested. Первые сутки после включения сверять с PostgreSQL, а не считать историей.

Retention ​

kafkaConsumer.analytics.rawRetentionDays — явное значение. 0 (по умолчанию) означает «хранить всё»: retention, который никто не выбирал, — это способ потерять год истории на той неделе, когда она понадобилась. Положительное значение добавляет таблице TTL по occurred_at.

Это не политика резервного копирования, и реплика ClickHouse не является бэкапом.

Псевдонимизация идентификаторов не удаляет персональные данные из текстов алертов и labels: источник по-прежнему может прислать имя, email или hostname. Карта данных и процедура erase — DATA_INVENTORY.md.

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

  1. helm upgrade — схема и Vector обновляются, kafkaConsumer.analytics.lifecycleEvents остаётся false;
  2. убедиться, что nxs_events_raw наполняется обычными alert.ingested;
  3. включить kafkaConsumer.analytics.lifecycleEvents=true (это перезапускает API и worker: у обоих deployment-ов есть checksum-аннотация на ConfigMap);
  4. сутки сверять PostgreSQL и ClickHouse, и только затем считать дашборды поддерживаемыми.

Порядок не декоративный: старая конфигурация Vector отвергает lifecycle-сообщение уже после подтверждения offset-а, то есть события теряются безвозвратно.

Ловушка при правке VRL: vector validate --no-environment конфиг не компилирует — он загружает файл и печатает «Validated» даже на VRL, который не собирается. Проверять надо построением топологии (vector validate без флага либо реальный запуск); в CI это делает deploy/helm/nxs-anomaly/tests/e2e/kind-kafka-consumer.sh.

Почему Vector, а не Kafka Engine: у engine отказ почти не виден снаружи — остановившийся consumer и пропуск битых сообщений живут в system.kafka_consumers и в логе сервера, алертить не на что. Vector отдаёт Prometheus-метрики (их снимает уже существующий ServiceMonitor), держит disk-буфер на время недоступности ClickHouse, а событие, которое не удалось разобрать, печатает в stdout и считает в component_discarded_events_total вместо тихого дропа.

Значимая деталь конфигурации: минимальный размер disk-буфера — 268435488 байт. Меньшее значение проходит vector validate и падает уже при старте топологии; в чарте это проверяет preflight.

Вторая значимая деталь: у ClickHouse-приёмников намеренно выключен стартовый healthcheck (healthcheck.enabled: false). Приёмник, чей healthcheck не прошёл, не запускается вовсе: события уходят в буфер и остаются там навсегда, а в логе после единственной строки «Healthcheck failed» больше ничего нет. Порядок старта подов произвольный, поэтому «ClickHouse ещё поднимается» — обычный случай, а не исключительный; два приёмника проверяются с разницей в миллисекунды, так что молча умирает то один, то другой. Признак этой ситуации — vector_buffer_events растёт при vector_component_received_events_total = 0 у того же component_id; на это и стоит алертить, а не на стартовую проверку.

Вариант 2 — ClickHouse Kafka Engine (без отдельного сервиса) ​

ClickHouse сам читает из топика без дополнительного consumer-сервиса. Плата за это — наблюдаемость: остановившийся consumer и пропуск битых сообщений видны только в system.kafka_consumers и в логе сервера, метрики для алерта нет.

Дедупликация повторных публикаций здесь так же обязательна — nxs_alerts_log ниже показан на MergeTree для краткости, но при at-least-once его нужно заменить на ReplacingMergeTree(published_at) с ORDER BY (received_at, integration_id, alert_id), как в варианте 1.

sql
-- 1. Промежуточная таблица с Kafka Engine
CREATE TABLE nxs_alerts_kafka_queue
(
    event           String,
    schema_version  UInt8,
    published_at    DateTime,
    alert_id        String        MATERIALIZED JSONExtractString(alert_raw, 'id'),
    alert_group_id  String        MATERIALIZED JSONExtractString(alert_raw, 'alert_group_id'),
    integration_id  String        MATERIALIZED JSONExtractString(alert_raw, 'integration_id'),
    status          LowCardinality(String) MATERIALIZED JSONExtractString(alert_raw, 'status'),
    severity        LowCardinality(String) MATERIALIZED JSONExtractString(alert_raw, 'severity'),
    source          LowCardinality(String) MATERIALIZED JSONExtractString(alert_raw, 'source'),
    title           String        MATERIALIZED JSONExtractString(alert_raw, 'title'),
    labels          String        MATERIALIZED JSONExtractString(alert_raw, 'labels'),
    received_at     DateTime      MATERIALIZED toDateTime(JSONExtractString(alert_raw, 'received_at')),
    group_status    LowCardinality(String) MATERIALIZED JSONExtractString(group_raw, 'status'),
    group_count     UInt32        MATERIALIZED JSONExtractUInt(group_raw, 'alert_count'),
    alert_raw       String        ALIAS JSONExtractRaw(message_value, 'alert'),
    group_raw       String        ALIAS JSONExtractRaw(message_value, 'group'),
    message_value   String
) ENGINE = Kafka('kafka:9092', 'nxs-anomaly.alerts', 'clickhouse-consumer', 'JSONEachRow');

-- 2. Финальная таблица
CREATE TABLE nxs_alerts_log
(
    received_at     DateTime,
    alert_id        String,
    alert_group_id  String,
    integration_id  String,
    status          LowCardinality(String),
    severity        LowCardinality(String),
    source          LowCardinality(String),
    title           String,
    labels          String,
    group_status    LowCardinality(String),
    group_count     UInt32
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(received_at)
ORDER BY (received_at, integration_id, severity);

-- 3. Materialized View переливает данные из очереди в таблицу
CREATE MATERIALIZED VIEW nxs_alerts_mv TO nxs_alerts_log AS
SELECT
    received_at, alert_id, alert_group_id, integration_id,
    status, severity, source, title, labels,
    group_status, group_count
FROM nxs_alerts_kafka_queue;

Вариант 3 — Vector вне chart ​

Если consumer разворачивается отдельно, за образец возьмите ConfigMap templates/kafka-consumer-config.yaml. Два места, где самописный конфиг обычно ошибается:

  • group бывает null — для алерта со status=resolved, у которого не было открытой группы (resolved_without_group). object!(.group) на таком событии падает, и алерт молча не доезжает, искажая всю статистику по resolved. В chart-конфиге это group = object(.group) ?? {}.
  • labels тоже бывает null — encode_json(object(alert.labels) ?? {}).

Dead Letter Webhook ​

Если доставка уведомления окончательно провалилась (retry exhausted, status = "failed"), nxs-anomaly может отправить событие на dead letter endpoint:

bash
NXS_ANOMALY_DEAD_LETTER_WEBHOOK_URL=https://hooks.example.com/dead-letter

Payload:

json
{
  "event": "notification.failed",
  "notification_id": "ntf_...",
  "alert_group_id": "grp_...",
  "user_id": "usr_...",
  "channel": "telegram",
  "target": "123456789",
  "retry_count": 3,
  "last_error": "HTTP 502",
  "failed_at": "2026-06-07T12:00:00Z"
}

Отправка fire-and-forget (не блокирует worker-цикл). Ошибка отправки логируется как ERROR dead_letter_delivery_failed.

Мониторинг ​

В логах worker-цикла появляется поле published_kafka_events:

INFO worker_cycle_complete published_kafka_events=12 processed_alert_groups=3 ...

При ошибке брокера:

ERROR kafka_outbox_publish_failed error="dial tcp kafka:9092: connection refused"

Outbox-строки остаются в PostgreSQL и будут повторно опубликованы на следующем цикле.

Для мониторинга глубины очереди:

sql
SELECT COUNT(*) FROM nxs_anomaly_kafka_outbox;

Если счётчик растёт — брокер недоступен или worker не запущен.

Локальная разработка ​

bash
# Запуск Kafka (официальный ASF-образ, KRaft, без ZooKeeper)
docker run -d --name kafka \
  -p 9092:9092 \
  -e KAFKA_NODE_ID=0 \
  -e KAFKA_PROCESS_ROLES=controller,broker \
  -e KAFKA_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093 \
  -e KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT \
  -e KAFKA_CONTROLLER_QUORUM_VOTERS=0@localhost:9093 \
  -e KAFKA_CONTROLLER_LISTENER_NAMES=CONTROLLER \
  -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 \
  -e KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=1 \
  -e KAFKA_TRANSACTION_STATE_LOG_MIN_ISR=1 \
  apache/kafka:3.9.0
# Без трёх KAFKA_..._REPLICATION_FACTOR/_MIN_ISR выше __consumer_offsets
# (служебный топик для consumer group) никогда не создастся — апстрим-образ
# по умолчанию требует 3 реплики, а брокер один. Симптом: produce работает,
# а любой consumer (в т.ч. Vector в kafkaConsumer) висит на первом fetch.

# Создать топик заранее (необязательно, но полезно: так вы задаёте число
# партиций, а не полагаетесь на умолчание брокера). Бинарники образа не в PATH.
docker exec kafka /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 \
  --create --topic nxs-anomaly.alerts --partitions 3 --replication-factor 1

# Запустить с Kafka
KAFKA_BROKERS=localhost:9092 \
NXS_ANOMALY_DB_DSN=postgres://... \
nxs-anomaly serve

nxs-anomaly · Documentation