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_ALERTS | nxs-anomaly.alerts | Топик по умолчанию для событий alert.ingested. |
KAFKA_BATCH_SIZE | 100 | Максимальный размер батча продьюсера. |
NXS_ANOMALY_ANALYTICS_PSEUDONYMISE | false | Заменять 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:
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».
Запуск
# 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-объект:
{
"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, создающий таблицу:
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:
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→ sinkrejected, то есть 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 | сутки × команда × сервис × severity | matured / on time / late / pending |
nxs_schedule_coverage | расписание × проверка | дыры в ротациях; report_id — чтобы взять общие счётчики один раз |
nxs_daily_alert_quality | сутки × интеграция | объём и шум, firing и resolving порознь |
nxs_daily_delivery_quality | сутки × канал × purpose | delivered/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 по вью.
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.
Порядок раскатки
helm upgrade— схема и Vector обновляются,kafkaConsumer.analytics.lifecycleEventsостаётсяfalse;- убедиться, что
nxs_events_rawнаполняется обычнымиalert.ingested; - включить
kafkaConsumer.analytics.lifecycleEvents=true(это перезапускает API и worker: у обоих deployment-ов есть checksum-аннотация на ConfigMap); - сутки сверять 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.
-- 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:
NXS_ANOMALY_DEAD_LETTER_WEBHOOK_URL=https://hooks.example.com/dead-letterPayload:
{
"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 и будут повторно опубликованы на следующем цикле.
Для мониторинга глубины очереди:
SELECT COUNT(*) FROM nxs_anomaly_kafka_outbox;Если счётчик растёт — брокер недоступен или worker не запущен.
Локальная разработка
# Запуск 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