feat(gotosocial): Grafana dashboard GoToSocial (20 panels); fix dashboard provisioning provider overlap; openspec: gotosocial-monitoring

2026-09-29 09:55:09 +00:00 · 2026-09-19 18:44:24 +00:00
parent 9cde035e5a
commit ee9249697d
9 changed files with 1790 additions and 2 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-19
@@ -0,0 +1,64 @@
+# Design: add-gotosocial-dashboard
+
+## Context
+
+См. proposal.md — Why. Метрики GtS уже поступают в VictoriaMetrics (job
+`gotosocial` в prometheus.yml active, `gotosocial_instance_total_users`
+отвечает с метками `{service="gotosocial",host="bigbox",
+instance="bigbox:9464",otel_scope_name="GoToSocial"}`). Задача — только
+визуализация: дашборд Grafana + provisioning.
+
+## Goals / Non-Goals
+
+**Goals**
+- Дашборд `GoToSocial` в Grafana (папка gotosocial) со стандартными
+  панелями: доступность, инстанс, воркеры, HTTP, SQL, процесс.
+- Автоимпорт через provisioning, как у vesti/vinogorod/nodes.
+
+**Non-Goals**
+- Алерты — отдельное изменение (как vesti-alerts).
+- Изменения docker-compose/prometheus.yml — не нужны.
+
+## Decisions
+
+- **Формат дашборда**: копия стиля `grafana/dashboards/vesti/vesti.json`
+  (Grafana 11.1, datasource uid "Prometheus", stat/timeseries панели).
+- **Доступность**: expr `gotosocial_instance_total_users` + stat (mapping
+  0=DOWN/1=UP по наличию значения; VI с блек-значением если нет данных —
+  зелёный/красный как в vesti).
+- **Панели по группам** (row-группировка как vesti):
+  1. Доступность (stat): instance total users (инстанс жив)
+  2. Instance: `gotosocial_instance_total_{users,statuses,federating_instances}`
+  3. Воркеры: 6 пулов `gotosocial_workers_*_{count,queue}` — count на одном
+     графике (stacks), queue на другом (столбики)
+  4. HTTP: `http_server_requests_total` (rate, все routes — sum),
+     `http_server_requests_active` (gauge)
+  5. SQL: `go_sql_connections_{open,in_use}`, `go_sql_query_timing_milliseconds{quantile="0.5"}`
+  6. Процесс: `process_resident_memory_bytes` (GB), `process_cpu_seconds_total`,
+     `process_open_fds`
+- **Метка фильтров**: везде `instance="bigbox:9464"` (или service — что
+  уникальнее; у GtS instance уже bigbox:9464).
+- **Provisioning**: новый провайдер в dashboards.yml, folder: gotosocial,
+  path: /var/lib/grafana/dashboards/gotosocial.
+
+## Risks / Trade-offs
+
+- [Крупный дашборд, много панелей] → писать аккуратно, проверять импорт по
+  grafana.db.
+- [Панель доступности по instance_total_users] — если инстанс упадёт,
+  метрика пропадёт, stat станет красным (нет данных) — ок как индикатор.
+- [Новые метрики в новых версиях GtS] — дашборд читает по именам; при
+  обновлении GtS проверить, что имена не поменялись.
+
+## Migration Plan
+
+1. Создать `grafana/dashboards/gotosocial/gotosocial.json`.
+2. Добавить провайдер `gotosocial-dashboards` в dashboards.yml.
+3. Подождать 30-60с; проверить импорт через grafana.db
+   (`SELECT uid FROM dashboard WHERE uid LIKE 'gotosocial%'`).
+4. Обновить STATUS.md (задача закрыта).
+5. Commit+push (gitverse) + mirror-sync.
+
+## Open Questions
+
+- Алерты на недоступность/очереди GtS — отдельный change, здесь нет.
@@ -0,0 +1,36 @@
+## Why
+
+В STATUS.md GoToSocial открыта задача «Мониторинг: пробросить :9464 (метрики
+уже слушают), job в prometheus.yml, дашборд Grafana». Job `gotosocial`
+(127.0.0.1:9464 → /metrics) и relabel `instance=bigbox:9464` уже добавлены
+ранее и данные реально приходят в VictoriaMetrics
+(`gotosocial_instance_total_users` отвечает с метками host/service/instance).
+Осталось: дашборд Grafana для метрик GtS + provisioning-провайдер.
+
+## What Changes
+
+- Новый дашборд Grafana `grafana/dashboards/gotosocial/gotosocial.json`
+  (панели: доступность, instance-статистика, воркеры, HTTP, SQL, процесс).
+- Новая папка Grafana `gotosocial` + провайдер в
+  `grafana/provisioning/dashboards/dashboards.yml`.
+- Автоимпорт дашборда через provisioning (~30с).
+- Обновление STATUS.md (задача закрывается).
+
+## Capabilities
+
+### New Capabilities
+- `gotosocial-monitoring`: дашборд Grafana с метриками GtS
+  (instance users/statuses, workers, HTTP, SQL, Go-runtime).
+
+### Modified Capabilities
+- `vesti-alerts`, `grafana-access-control`, `vinograd-wan-monitoring`:
+  не затрагиваются.
+
+## Impact
+
+- `/opt/monitoring/grafana/dashboards/gotosocial/gotosocial.json` — новый.
+- `/opt/monitoring/grafana/provisioning/dashboards/dashboards.yml` — +1 провайдер.
+- Grafana provisioning автоматически импортирует файл (~30с).
+- Никаких изменений в docker-compose/prometheus.yml — job уже есть.
+- Откат: удалить файл дашборда и блок провайдера из dashboards.yml
+  (Grafana удалит визуализацию, данные в VM остаются).
@@ -0,0 +1,64 @@
+# gotosocial-monitoring Specification
+
+## Purpose
+
+Дашборд Grafana для метрик GoToSocial (bigbox): наблюдение за инстансом
+(пользователи/статусы/федерирующиеся инстансы), воркерами (очереди),
+HTTP-активностью, SQL-соединениями и ресурсами процесса.
+
+## ADDED Requirements
+
+### Requirement: Job gotosocial в prometheus.yml активен
+
+- **MUST**: job `gotosocial` опрашивает `127.0.0.1:9464/metrics` и
+  релейб`instance=bigbox:9464`.
+- **MUST**: метрики доступны в VictoriaMetrics с метками
+  `service="gotosocial"`, `host="bigbox"`, `instance="bigbox:9464"`.
+
+#### Scenario: Метрики отвечают
+
+- **GIVEN** job gotosocial настроен в prometheus.yml
+- **WHEN** запросить
+  `/api/v1/series?match[]=gotosocial_instance_total_users`
+- **THEN** ответ содержит метрику с `instance: "bigbox:9464"` и данные
+
+### Requirement: Дашборд gotosocial в Grafana
+
+- **MUST**: Провайдер `gotosocial-dashboards` в
+  `grafana/provisioning/dashboards/dashboards.yml` импортирует
+  `/var/lib/grafana/dashboards/gotosocial` (updateIntervalSeconds: 30).
+- **MUST**: Дашборд `grafana/dashboards/gotosocial/gotosocial.json` содержит:
+  - stat-панель доступности (запрос `gotosocial_instance_total_users` — если
+    данные есть, служба жива)
+  - instance-панели: users, statuses, federating_instances
+  - воркеры: по каждому пулу `gotosocial_workers_*` count+queue
+  - HTTP: `http_server_requests_total`, `http_server_requests_active`
+  - SQL: `go_sql_connections_in_use`
+  - процесс: RSS, CPU секунды, open_fds
+- **SHOULD**: панели названы по-русски, структура соответствует стилю vesti.json.
+
+#### Scenario: Дашборд импортирован
+
+- **GIVEN** файл дашборда и провайдер добавлены
+- **WHEN** пройти 30-60с после изменения provisioning
+- **THEN** дашборд `GoToSocial` виден в папке
+  `gotosocial` (проверка: `SELECT uid FROM dashboard WHERE uid LIKE 'gotosocial%'`
+  в grafana.db)
+
+### Requirement: Инстанс виден без алертов
+
+- **MUST**: Дашборд не содержит алертинга (алерты GtS — отдельное изменение).
+- **SHOULD**: Панель доступности зелёная (UP), когда `gotosocial_instance_total_users`
+  возвращает значение; красная — когда нет данных.
+
+#### Scenario: Инстанс жив
+
+- **GIVEN** GtS отвечает на 9464
+- **WHEN** проверить stat-панель «Инстанс жив»
+- **THEN** значение `gotosocial_instance_total_users` > 0 и панель зелёная
+
+#### Scenario: Инстанс недоступен
+
+- **GIVEN** GtS не отвечает на 9464
+- **WHEN** пройти интервал опроса (15с)
+- **THEN** метрика пропадает и панель доступности показывает DOWN/красная
@@ -0,0 +1,17 @@
+## 1. Дашборд Grafana gotosocial
+
+- [x] 1.1 Создать `grafana/dashboards/gotosocial/gotosocial.json`
+      (генератор: `scripts/gen_gotosocial_dash.py`) — 20 панелей:
+      Доступность (stat), Инстанс (users/statuses/federating), Воркеры
+      (count+queue × 6 пулов), HTTP (req/s, active, p50), SQL (соединения,
+      p50), Процесс (RSS, CPU, FD).
+- [x] 1.2 Добавить провайдер `gotosocial-dashboards` в dashboards.yml
+      (folder: gotosocial, path: /var/lib/grafana/dashboards/gotosocial).
+- [x] 1.3 Исправить пересечение провайдеров: `garage-dashboards` смотрел на
+      весь `/var/lib/grafana/dashboards` (дублировал nodes/vinogorod/vesti/
+      gotosocial → блокировал запись) → сужен до
+      `/var/lib/grafana/dashboards/garage-cluster.json`.
+- [x] 1.4 Рестарт grafana (перечитывает provisioning).
+- [x] 1.5 Проверка импорта: `gotosocial-main` в grafana.db, папка
+      `gotosocial` (id 23), включён в dashboard_provisioning.
+- [x] 1.6 Обновить STATUS.md (задача закрыта).