# Каталог Grafana в onGuard24

Иерархия **инстанс → организация → папки → правила алертинга** подтягивается **по HTTP API** Grafana и сохраняется в PostgreSQL. Вебхук при этом не заменяет синхронизацию: вебхук даёт события, каталог — актуальную структуру правил.

## Что нужно

1. Миграция **`004_grafana_catalog`** (выполняется при старте контейнера через `alembic upgrade head`).
2. В `.env` у источника Grafana заданы **`api_url`** и **`api_token`** (service account с правами читать папки и alert rules — обычно роль Viewer/Editor и доступ к Alerting).
3. Источник попадает в **`iter_grafana_sources`**: `GRAFANA_SOURCES_JSON` или пара `GRAFANA_URL` + `GRAFANA_SERVICE_ACCOUNT_TOKEN` (slug `default`).

## API

| Метод | Путь | Назначение |
|--------|------|------------|
| POST | `/api/v1/modules/grafana-catalog/sync` | Синхронизация. Тело: `{}` — все источники с токеном; `{"instance_slug":"default"}` — один slug. |
| GET | `/api/v1/modules/grafana-catalog/meta` | Последние метаданные синхронизации по всем slug. |
| GET | `/api/v1/modules/grafana-catalog/tree?instance_slug=default` | Дерево: папки и правила, сгруппированные по `namespace_uid` (обычно UID папки правил). |

## Проверка на https://onguard24.pvenode.ru/

1. Убедитесь, что задеплоена версия с модулем **Каталог Grafana** (пункт в боковом меню).
2. Выполните синхронизацию (с сервера или с машины с доступом к API):

```bash
curl -sS -X POST "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/sync" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Ответ: `results[]` с полями `ok`, `folders`, `rules`, при ошибке — `error`.

3. Посмотреть дерево:

```bash
curl -sS "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/tree?instance_slug=default" | python3 -m json.tool
```

(Если используете только `GRAFANA_URL`, slug источника — **`default`**.)

4. В UI: **Каталог Grafana** — таблица последних синхронизаций.

## Связь с вебхуком

- В инцидентах по-прежнему используется **`externalURL` / лейблы** из тела вебхука.
- Каталог позволяет в UI/API сопоставлять **`rule_uid`** и папку с сохранённым снимком (после доработок привязки).

## Ограничения

- Один токен = **одна Grafana-организация** (контекст `GET /api/org`). Обход нескольких org на одном инстансе — отдельные токены или админ-API (не в этой версии).
- Эндпоинты Ruler: пробуются `/api/ruler/grafana/api/v1/rules` и `/api/ruler/Grafana/api/v1/rules` (зависит от версии Grafana).

## Автоматический cron

Периодический `POST .../sync` пока не встроен: можно повесить **системный cron**, **Forgejo scheduled workflow** или внешний оркестратор.