# 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, здесь нет.