monitoring/openspec/specs/gotosocial-monitoring/spec.md

gotosocial-monitoring Specification

Purpose

Дашборд Grafana для метрик GoToSocial (bigbox): наблюдение за инстансом (пользователи/статусы/федерирующиеся инстансы), воркерами (очереди), HTTP-активностью, SQL-соединениями и ресурсами процесса.

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/красная