# Мониторинг: из чего собран и за чем следит

Набор описывает зону мониторинга: какие сервисы в неё входят, что собирает
Prometheus, какие источники данных подготовлены в Grafana, каким пользователем
она ходит в ClickHouse и куда кладутся дашборды. Устройство каждого дашборда —
отдельным файлом, указатели ниже. Зачем зоне именно такой состав и какие
дашборды на нём задуманы — [ADR 0002](../../adr/0002-monitoring-scope.md);
устройство доступа — [ADR 0007](../../adr/0007-clickhouse-access.md).

**Что здесь есть и чего ещё нет.** Собран пол: свой образ Grafana с плагином
ClickHouse, два подготовленных источника данных, экспортёр метрик Kafka и цель
для него у Prometheus. Поверх пола стоят все три дашборда ADR 0002, они
перечислены ниже. Правил оповещения и серверного журнала `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. При сборке Grafana CLI берёт
закреплённый выпуск из официального репозитория на GitHub, а не из каталога
Grafana: прямой запрос к каталогу при проверке вернул HTTP 451. Фоновая
установка плагинов при запуске отключена.

## Кого опрашивает 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 подхватывает оттуда файлы
дашбордов, удалять и править их через интерфейс запрещено. Новый дашборд — это
новый файл в каталоге и больше ничего: в `compose.yaml` заходить не нужно, ради
этого каталог и заведён заранее.

Файлы каталога разбирает `make config-test`, рядом с файлами дагов и по тому же
доводу ([testing.md](../testing.md)).

Порогов и цветовых вердиктов на панелях нет ни на одном дашборде: на них
смотрят глазами, красное и зелёное живёт в проверках и дагах DQ.

Собранные дашборды:

- **«Данные»** (`data.json`) — с потоком всё в порядке: свежесть, поток, брак,
  сходимость Kafka с ClickHouse, отставание чтения и дневной слепок заказов.
  Устройство и разбор панелей — [data.md](data.md).
- **«Кластер»** (`cluster.json`) — что с машиной: процессор, память и диски
  обеих нод, части и слияния, keeper, очередь распределённых DDL. Устройство и
  разбор панелей — [cluster.md](cluster.md).
- **«Запросы»** (`queries.json`) — что выполнялось и во что обошлось: тяжёлые
  запросы, аппетит по посетителям, ошибки. Устройство и разбор панелей —
  [queries.md](queries.md).

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

Права роли `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.