Дашборд «Данные»: свежесть, поток, брак, сходимость #120

2026-08-21T20:30:31+03:00

ddmitry commented

2026-08-21 20:30:31 +03:00

Closes #115

Главный дашборд ADR 0002: один экран, отвечающий на вопрос «с потоком всё в
порядке?». Три его вопроса — свежесть, брак, сходимость — у предшественника не
заданы вовсе, и в этом весь смысл экрана.

Что внутри

infra/grafana/provisioning/dashboards/data.json — шесть панелей, ровно шесть
вопросов ADR 0002:

Панель	Откуда берёт	О чём отвечает
Свежесть	`ods.event_dist`, `ods.order_dist`	сколько прошло с последней доехавшей строки
Поток	`stg.*_raw_dist`	сколько строк приезжает в слой сырья
Брак	сырьё и `ods.*_errors_dist`	сколько приехавшего не разобралось и какая доля
Сходимость	экспортёр Kafka и `stg.hits_raw_dist`	произведённое против приземлившегося
Отставание	`kafka_consumergroup_lag`	сколько сообщений не прочитано
Дневной слепок	`stg.orders_raw_dist`	какой доехал, когда и после какой паузы

Границы соблюдены: порогов и цветовых вердиктов нет, команд и настроек про тик
в JSON нет, чтецов Kafka панели не читают.

Сходимость: решение и довод

Та самая неочевидная панель. Смешанный источник: произведённое живёт в Kafka,
приземлившееся — в ClickHouse, и со своей стороны ни одна из них не видит
другую. Единицы общие — сообщений за интервал панели: со стороны Kafka разность
офсетов «сейчас минус интервал назад», со стороны ClickHouse count() строк
сырья по тому же интервалу. Столбцы ClickHouse подписаны правым краем — иначе
здоровые ряды разъезжаются ровно на один столбец.

Два способа отвергнуты по замеру на живом стенде, а не по вкусу:

increase растягивает приращение на всё окно и на минутном интервале
промахивается на проценты — здоровый стенд выглядел бы расходящимся;
накопленный итог от начала окна точнее обоих, но отсчитывать его надо от края
окна, а на свежем стенде окно начинается раньше, чем поднялся экспортёр, —
и ряд пропадает целиком.

Разбор целиком — docs/architecture/monitoring.md, раздел «Как считается
сходимость».

Отступление от ADR

У панели потока нет ряда «против вчерашнего». Реальное «вчера» на стенде чаще
всего приходится на время, когда стенда ещё не было, а сдвиг на модельные сутки
прописал бы ускорение мира в JSON дашборда — ровно ту пометку про тик, которую
этот же ADR держать там не велит. Решение записано в самом ADR 0002 и в
monitoring.md.

Сверх задания

make config-test разбирает JSON дашбордов — тем же доводом, что и файлы дагов:
сломанный файл Grafana не выносит сообщением, а молча оставляет прежнюю версию.
Что проверка умеет краснеть, снято порчей файла нарочно.

Проверка

make config-test, make lint, make smoke 21/21, make check-clickhouse
10/10. На живом стенде, с world_live снятым с паузы:

дашборд поднимается из каталога сам, без ручного импорта; сохранение и
удаление через API отвергаются;
все шесть панелей отвечают — и в окне часа по умолчанию, и в шестичасовом,
которое начинается раньше, чем поднялся экспортёр; пустых нет ни при идущем
потоке, ни при остановленном;
брак: подсунутое в hits негодное сообщение легло в ods.event_errors
классом keyset_mismatch, панель показала единицу и долю 0,039 %. Строка
убрана мутациями, обе таблицы вернулись к нулю;
свежесть: через пять минут после конца модельного дня — 305 с у событий и
288 с у заказов; пустил следующий день — события вернулись к секунде;
сходимость: за двадцать пять минут живого потока медиана расхождения
рядов 3 %, худший столбец 11 % — на переломе потока.

Следы опытов — docs/architecture/monitoring.md, раздел «Что проверено».

Closes #115 Главный дашборд ADR 0002: один экран, отвечающий на вопрос «с потоком всё в порядке?». Три его вопроса — свежесть, брак, сходимость — у предшественника не заданы вовсе, и в этом весь смысл экрана. ## Что внутри `infra/grafana/provisioning/dashboards/data.json` — шесть панелей, ровно шесть вопросов ADR 0002: | Панель | Откуда берёт | О чём отвечает | |---|---|---| | Свежесть | `ods.event_dist`, `ods.order_dist` | сколько прошло с последней доехавшей строки | | Поток | `stg.*_raw_dist` | сколько строк приезжает в слой сырья | | Брак | сырьё и `ods.*_errors_dist` | сколько приехавшего не разобралось и какая доля | | Сходимость | экспортёр Kafka и `stg.hits_raw_dist` | произведённое против приземлившегося | | Отставание | `kafka_consumergroup_lag` | сколько сообщений не прочитано | | Дневной слепок | `stg.orders_raw_dist` | какой доехал, когда и после какой паузы | Границы соблюдены: порогов и цветовых вердиктов нет, команд и настроек про тик в JSON нет, чтецов Kafka панели не читают. ## Сходимость: решение и довод Та самая неочевидная панель. Смешанный источник: произведённое живёт в Kafka, приземлившееся — в ClickHouse, и со своей стороны ни одна из них не видит другую. Единицы общие — сообщений за интервал панели: со стороны Kafka разность офсетов «сейчас минус интервал назад», со стороны ClickHouse `count()` строк сырья по тому же интервалу. Столбцы ClickHouse подписаны правым краем — иначе здоровые ряды разъезжаются ровно на один столбец. Два способа отвергнуты **по замеру на живом стенде**, а не по вкусу: - `increase` растягивает приращение на всё окно и на минутном интервале промахивается на проценты — здоровый стенд выглядел бы расходящимся; - накопленный итог от начала окна точнее обоих, но отсчитывать его надо от края окна, а на свежем стенде окно начинается раньше, чем поднялся экспортёр, — и ряд пропадает целиком. Разбор целиком — `docs/architecture/monitoring.md`, раздел «Как считается сходимость». ## Отступление от ADR У панели потока нет ряда «против вчерашнего». Реальное «вчера» на стенде чаще всего приходится на время, когда стенда ещё не было, а сдвиг на модельные сутки прописал бы ускорение мира в JSON дашборда — ровно ту пометку про тик, которую этот же ADR держать там не велит. Решение записано в самом ADR 0002 и в `monitoring.md`. ## Сверх задания `make config-test` разбирает JSON дашбордов — тем же доводом, что и файлы дагов: сломанный файл Grafana не выносит сообщением, а молча оставляет прежнюю версию. Что проверка умеет краснеть, снято порчей файла нарочно. ## Проверка `make config-test`, `make lint`, `make smoke` 21/21, `make check-clickhouse` 10/10. На живом стенде, с `world_live` снятым с паузы: - дашборд поднимается из каталога сам, без ручного импорта; сохранение и удаление через API отвергаются; - все шесть панелей отвечают — и в окне часа по умолчанию, и в шестичасовом, которое начинается раньше, чем поднялся экспортёр; пустых нет ни при идущем потоке, ни при остановленном; - **брак**: подсунутое в `hits` негодное сообщение легло в `ods.event_errors` классом `keyset_mismatch`, панель показала единицу и долю 0,039 %. Строка убрана мутациями, обе таблицы вернулись к нулю; - **свежесть**: через пять минут после конца модельного дня — 305 с у событий и 288 с у заказов; пустил следующий день — события вернулись к секунде; - **сходимость**: за двадцать пять минут живого потока медиана расхождения рядов 3 %, худший столбец 11 % — на переломе потока. Следы опытов — `docs/architecture/monitoring.md`, раздел «Что проверено».

ddmitry added 3 commits 2026-08-21 20:30:33 +03:00

feat(monitoring): собран дашборд «Данные» из шести панелей 180ef5b94f

- Зачем:
  - главный дашборд ADR 0002 отвечает на вопрос «с потоком всё в порядке?»;
    три его вопроса — свежесть, брак и сходимость — у предшественника не
    заданы вовсе, и в этом весь смысл экрана.
- Что:
  - добавлен infra/grafana/provisioning/dashboards/data.json: свежесть, поток,
    брак, сходимость, отставание чтения из Kafka и дневной слепок заказов;
    порогов и цветовых вердиктов на панелях нет.
  - в monitoring.md записано устройство дашборда: почему слои у панелей разные
    и как считается сходимость — с доводом и двумя отвергнутыми способами.
  - make config-test разбирает JSON дашбордов тем же доводом, что и файлы
    дагов: сломанный файл Grafana молча оставляет прежнюю версию.
- Проверка:
  - make config-test; на живом стенде make smoke 21/21 и make check-clickhouse
    10/10; все шесть панелей отвечают через /api/ds/query.

fix(monitoring): панели уточнены по ревью, приёмка снята на стенде e5c573bb25

- Зачем:
  - две линии ревью нашли, что колонки панели брака читаются как
    непересекающиеся кучи, «вовремя ли» из ADR 0002 не считается вовсе, а
    отказ от ряда «против вчерашнего» нигде не записан рядом с решением.
- Что:
  - в панели брака столбец назван «Из них в брак»: брак — часть приехавшего,
    а не соседняя куча.
  - панель слепка считает паузу после прошлого слепка — это и есть «вовремя
    ли» из ADR 0002; пустая пауза у самого раннего слепка держится
    обнуляемым типом.
  - отказ от ряда «против вчерашнего» записан в ADR 0002 и в monitoring.md с
    доводом: сдвиг на модельные сутки прописал бы ускорение мира в JSON.
  - в monitoring.md сказано, почему свежесть читает физическую _dist, а не
    ods.*_v, и почему панель слепка не знает окна; довод про сломанный JSON
    оставлен у кода, а не задвоен в доке.
  - README больше не утверждает, что панелей нет.
  - у разбора дашбордов убран флаг -e: он обещал утверждение, которого нет.
- Проверка:
  - make config-test (краснеет на нарочно сломанном JSON дашборда), make lint,
    make smoke 21/21, make check-clickhouse 10/10; все шесть панелей отвечают
    через /api/ds/query. Опыты приёмки и их следы — monitoring.md,
    «Что проверено».

fix(monitoring): ряды панелей подписаны своими именами, а не буквой запроса f7123f2ad7

- Зачем:
  - на живом дашборде видно то, чего не показывает API: при нескольких
    запросах в панели Grafana ставит перед именем ряда его букву — «A события»,
    «B приземлилось в ClickHouse». Читателю панели это шум.
- Что:
  - свежесть и поток собраны одним запросом на панель: два столбца вместо двух
    запросов. У потока это заодно вернуло ряд заказов, который пропадал, когда
    в окне не было ни одного слепка.
  - у сходимости ряды из разных источников слить нельзя, поэтому ряду
    ClickHouse имя задано переопределением поля.
- Проверка:
  - make config-test; на живом стенде подписи прочитаны прямо со страницы
    дашборда: «события», «заказы», «произведено в Kafka», «приземлилось в
    ClickHouse»; все шесть панелей отвечают через /api/ds/query.

ddmitry merged commit d43a9b348b into main

2026-08-21 20:52:55 +03:00

ddmitry deleted branch feat/115-data-dashboard

2026-08-21 20:52:55 +03:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#120