feat(monitoring): подготовлена основа мониторинга Kafka и ClickHouse

- Зачем: - подготовлен пол мониторинга для SQL-панелей и метрик отставания Kafka. - Что: - добавлены отдельная роль ClickHouse, источник Grafana и Kafka exporter. - образ Grafana собирается с закреплённым плагином вне тома данных. - Prometheus, смоук и документация обновлены под четыре цели. - Проверка: - make config-test; make lint. - make smoke; make check-clickhouse; make check-services. - make -C generator lint typecheck test.
2026-08-21 09:56:56 -04:00
1 parent 0bb07fd91d
commit c5dd9c2d34
@@ -1,10 +1,11 @@
 # ADR 0007. Доступ к ClickHouse: пользователи файлом, доверие нод секретом

-Дата: 9 августа 2026 года. Статус: принято.
+Дата: 9 августа 2026 года. Статус: принято; роль `monitoring_reader`
+и пользователь `grafana` добавлены 21 августа 2026 года (#114).

 ## Решение

-У кластера пять пользователей и четыре роли.
+У кластера шесть пользователей и пять ролей.

 - `default` — с паролем, только служебный: проверки здоровья нод и работа
  изнутри контейнеров. Приложения им не ходят.
@@ -14,6 +15,8 @@
  Им ходит Superset.
 - `analyst` с ролью `analyst_reader` — чтение всех слоёв и справочников. Им
  человек подключается снаружи, из своего клиента.
+- `grafana` с ролью `monitoring_reader` — чтение слоёв, таблиц базы `dic` и
+  системных таблиц, `CLUSTER` и `REMOTE`. Им ходит Grafana, и больше никто.
 - `dict` с ролью `dict_reader` — чтение одной базы `dic`, пароля нет. Им
  словарь читает свою подложку, и больше он никем не используется
  ([ADR 0012](0012-dictionary-home.md)).
@@ -58,6 +61,20 @@ DDS под ними, потому что так чаще всего и быва
 есть положить секрет в git. Ходить этой учёткой некуда: право у неё одно —
 `SELECT` на `dic`, и хост источника локальный.

+**Своя роль дашбордам.** Панели мониторинга живут не на витринах, а на
+`system.query_log`, частях MergeTree и очереди распределённых DDL — и читают
+их через `clusterAllReplicas`, потому что системные таблицы у каждой ноды свои
+([ADR 0002](0002-monitoring-scope.md)). Для этого нужны `SELECT` на `system.*`
+и `REMOTE`; контракт роли также включает `CLUSTER` для запросов `ON CLUSTER`.
+Такого набора не было ни у одного читателя: у обеих читающих ролей из
+системных таблиц только `system.settings`. Догрузить
+недостающее в `analyst_reader` отвергнуто: аналитик получил бы системные
+таблицы и `REMOTE` заодно, а в `system.query_log` запросы Grafana стали бы
+неотличимы от человеческих — ровно там, где дашборд «Запросы» и должен их
+различать. Пускать Grafana под `etl` отвергнуто сразу: читатель не получает
+права писать. Осталась своя роль по здешней общей схеме — у каждого
+потребителя она своя.
+
 **Секрет, а не учётные данные по репликам.** У каждой реплики в описании
 кластера своя учётка — вписанная явно или подразумеваемая, и тогда это
 беспарольный `default`. Подключение к соседней ноде идёт от неё, а не от
@@ -141,6 +158,25 @@ DDS под ними, потому что так чаще всего и быва
  настройки ClickHouse.
 - Весь DDL репозитория идёт через `IF NOT EXISTS` (файлы `sql/ddl/`).

+Права роли `monitoring_reader` сверены 21 августа 2026 года по документации
+ClickHouse через MCP Context7 (#114).
+
+- Системные таблицы выдаются обычным `SELECT`: в документации это
+  `GRANT SELECT ON system.query_log`, значит `SELECT ON system.*` и есть «все
+  системные таблицы». Отдельного права на них нет.
+- `GRANT CLUSTER ON *.*` — документированная форма права на запросы
+  `ON CLUSTER`; текущий запрос `clusterAllReplicas` его не использует.
+- `clusterAllReplicas` документация держит в одном ряду с `remote`,
+  `remoteSecure` и `cluster`: это табличная функция, которая берёт имя
+  кластера из `remote_servers` и идёт на каждую его реплику. Отсюда `REMOTE` —
+  без права на удалённое обращение запрос дальше своей ноды не пойдёт, а
+  панели ADR 0002 читают `system.*` именно так.
+
+Набор проверен на живом стенде 21 августа 2026 года (#114): пользователь
+`grafana` из Grafana выполнил
+`SELECT count() AS replicas FROM clusterAllReplicas('clickstream_cluster', system.one)`
+и получил 2 — прав хватает, чтобы прочесть системную таблицу с обеих нод.
+
 Проверено на живом стенде 13 августа 2026 года, ClickHouse 26.3.17.56.

 - Секрет кластера принимается внутри `remote_servers` в виде
@@ -0,0 +1,83 @@
+# Мониторинг: из чего собран и что скребёт
+
+Документ описывает зону мониторинга: какие сервисы в неё входят, что собирает
+Prometheus, какие источники данных подготовлены в Grafana и каким
+пользователем она ходит в ClickHouse. Зачем зоне именно такой состав и какие
+дашборды на нём задуманы — [ADR 0002](../adr/0002-monitoring-scope.md);
+устройство доступа — [ADR 0007](../adr/0007-clickhouse-access.md).
+
+**Что здесь есть и чего ещё нет.** Собран пол: свой образ Grafana с плагином
+ClickHouse, два подготовленных источника данных, экспортёр метрик Kafka и цель
+для него у Prometheus. Дашбордов пока ни одного — каталог под них заведён
+пустым, панели приносят отдельные тикеты. Правил оповещения и серверного
+журнала `system.text_log` тоже пока нет.
+
+## Состав
+
+| Сервис | Образ | Что делает |
+|---|---|---|
+| `prometheus` | `prom/prometheus:v3.13.2` | опрашивает цели раз в 15 секунд, порт стенда `29090` |
+| `grafana` | `clickstream-grafana:local` | интерфейс мониторинга; собирается из `infra/grafana/`, порт стенда `23000` |
+| `kafka-exporter` | `danielqsj/kafka-exporter:v1.9.0` | переводит состояние брокера в метрики Prometheus, порт `9308` |
+
+Плагин ClickHouse 4.20.0 входит в образ Grafana. Фоновая установка плагинов
+при запуске отключена.
+
+## Что скребёт Prometheus
+
+| Цель | Задание | Метка `role` | Откуда метрики |
+|---|---|---|---|
+| `clickhouse-01:9363` | `clickhouse` | `server` | встроенный экспортёр ноды |
+| `clickhouse-02:9363` | `clickhouse` | `server` | встроенный экспортёр ноды |
+| `clickhouse-keeper:9363` | `clickhouse-keeper` | `keeper` | встроенный экспортёр keeper |
+| `kafka-exporter:9308` | `kafka` | `exporter` | внешний экспортёр |
+
+Ровно эти четыре цели пересчитывает `check_prometheus_targets` в
+`scripts/stand-smoke.sh` — и по значению `up`, и по списку адресов. Пятая цель
+красит смоук; это и есть способ заметить, что состав пола поменяли молча.
+
+## Источники данных Grafana
+
+Оба источника подготовлены файлами в `infra/grafana/provisioning/datasources/`
+и объявлены `editable: false`: править их через интерфейс нельзя, источник
+истины — репозиторий.
+
+- `prometheus` — основной по умолчанию, ходит на `http://prometheus:9090`.
+- `clickhouse` — плагин `grafana-clickhouse-datasource`, нативный протокол,
+  `clickhouse-01:9000`, пользователь `grafana`, пароль из `.env`.
+
+Источник ClickHouse смотрит на `clickhouse-01`. Системные таблицы обеих нод
+панели читают через `clusterAllReplicas`, как принято в ADR 0002.
+
+## Доступ к ClickHouse
+
+Grafana ходит пользователем `grafana` с ролью `monitoring_reader`: читает слои,
+таблицы базы `dic` и системные таблицы. `REMOTE` разрешает
+`clusterAllReplicas`, `CLUSTER` — запросы `ON CLUSTER`. Решение о своей роли
+записано в [ADR 0007](../adr/0007-clickhouse-access.md). Пароль задаётся
+переменной `CLICKHOUSE_GRAFANA_PASSWORD`.
+
+## Куда кладутся дашборды
+
+Каталог `infra/grafana/provisioning/dashboards/` смонтирован в контейнер и
+объявлен провайдером в `provider.yml`: Grafana подхватывает оттуда файлы
+дашбордов, удалять и править их через интерфейс запрещено. Сейчас в каталоге
+только сам файл провайдера. Тикет с панелями кладёт туда JSON и в
+`compose.yaml` уже не заходит — ради этого каталог и заведён заранее.
+
+## Что проверено
+
+Права роли `monitoring_reader` сверены 21 августа 2026 года по документации
+ClickHouse через MCP Context7; разбор — в
+[ADR 0007](../adr/0007-clickhouse-access.md), раздел «Что проверено».
+
+Сам состав проверен на живом стенде 21 августа 2026 года, собранном заново
+после `make clean`.
+
+- Grafana видит плагин `grafana-clickhouse-datasource` 4.20.0
+  (`/api/plugins?type=datasource`), оба подготовленных источника здоровы.
+- Запрос источника ClickHouse к `system.one` через `clusterAllReplicas` вернул
+  2 — с одной ноды видны обе.
+- Prometheus видит ровно четыре цели, все со значением `up = 1`; запрос
+  `kafka_consumergroup_lag` вернул ряды по группам `clickstream_*`.
+- `make smoke` 21/21, `make check-clickhouse` 10/10, `make check-services` 7/7.
@@ -33,18 +33,18 @@
 генератора: он отдельный пакет со своим `pyproject.toml`, локом и образом, и
 спрашивают его отдельно.

-Стенд нужен трём целям из восьми. Цена — замер, см. «Что проверено»:
-`make test`, `make smoke`, `make check-clickhouse` и `make check-services`
-перемерены 7 августа 2026 года на приёмке этапа 2, корневой `make lint` —
-9 августа при его появлении; остальные стоят с замера 6 августа.
+Стенд нужен трём целям из восьми. Цена — замер, см. «Что проверено».
+`make smoke` и `make check-services` перемерены 21 августа 2026 года,
+`make check-clickhouse` — 19 августа, корневой `make lint` — 9 августа,
+`make test` — 7 августа; остальные стоят с замера 6 августа.

 | Цель | Откуда | Что утверждает | Стенд | Цена |
 |---|---|---|---|---|
 | `make config-test` | корень | Compose разбирается, файлы DAG синтаксически целы, в diff нет пробельных ошибок. О работоспособности не говорит ничего | не нужен | 1 с |
 | `make lint` | корень | Код стенда — `dags/` и `infra/superset/` — отформатирован и проходит ruff | не нужен | 0,4 с |
-| `make smoke` | корень | Стенд **собран**: службы живы, порты отвечают, подключения настроены друг на друга. Вширь и по касательной к каждой службе. Единственная цель, которая здесь правда смоук | нужен | 9 с |
+| `make smoke` | корень | Стенд **собран**: службы живы, порты отвечают, подключения настроены друг на друга. Вширь и по касательной к каждой службе. Единственная цель, которая здесь правда смоук | нужен | 17 с |
 | `make check-clickhouse` | корень | Всё, что спрашивают **у ClickHouse** и он отвечает сам: макросы, шарды, реплики, путь в keeper, ключ шардирования, очередь распределённых DDL, ответ словаря товаров, счёт событий стартового мира против описи | нужен | 24 с |
-| `make check-services` | корень | **Службы работают**: DAG запускается и доходит, топик создаётся и удаляется, Superset логинится и ходит в базу | нужен | 59 с |
+| `make check-services` | корень | **Службы работают**: DAG запускается и доходит, топик создаётся и удаляется, Superset логинится и ходит в базу | нужен | 93 с |
 | `make lint` | `generator/` | Код генератора отформатирован и проходит ruff | не нужен | 0,4 с |
 | `make typecheck` | `generator/` | Типы генератора сходятся (ty) | не нужен | 0,5 с |
 | `make test` | `generator/` | Генератор делает то, что обещает; схема события остаётся объявленным контрактом, а собранные из кода [описание выгрузки](../formats/clickstream-event.md) и [опись мира](../../data/world-inventory.json) — свежими | не нужен | 71 с |
@@ -209,7 +209,7 @@ Kafka → STG → ODS, и живёт он в `make check-clickhouse`.
  контейнер Docker поднимает сам, и проверка здоровья об этом промолчит
  (ADR 0004). Стенд нагружает `check-services`, а увидеть последствия нужно и
  тому, кто гонял один смоук. Это единственная проверка, которая считается
-  дважды: 20 у смоука плюс 7 у `check-services` — это 26 разных проверок.
+  дважды: 21 у смоука плюс 7 у `check-services` — это 27 разных проверок.
 - **Зависимости машины считает только смоук.** «На машине есть Docker, curl и
  jq» — вопрос к машине, а не к службам, и на оси он стоит рядом с «стенд
  собран». Для `check-services` это условие запуска: без них он не начнёт
@@ -221,6 +221,12 @@ Kafka → STG → ODS, и живёт он в `make check-clickhouse`.

 ## Что проверено

+**Перезамер 21 августа 2026 года при исполнении #114.** После добавления
+`kafka-exporter` и источника ClickHouse смоук прошёл 21/21 за 16–17 секунд,
+`check-services` — 7/7 за 93 секунды. При остановленном экспортёре смоук дал
+19/2: назвал нездоровый сервис и отсутствие одной из четырёх целей. После
+возврата сервиса прогон снова дал 21/21.
+
 **Перезамер 20 августа 2026 года при исполнении #96.** `make up` после
 `make clean` прошёл за 8 м 18 с, повтор на живом стенде — за 3 м 35 с. Служба
 семи слепков заняла около 28 секунд между концом `world-init` и своим концом.