Работа с дашбордами и алертами Grafana

Текст

---
name: grafana-api
description: Работа с экземпляром Grafana: поиск и чтение дашбордов, запросы к источникам данных (Prometheus, Loki, PostgreSQL и др.), просмотр правил алертов и заглушений (silences), добавление аннотаций и управление папками. Используй всякий раз, когда пользователь упоминает дашборд, панель или алерт Grafana, вставляет ссылку на Grafana, спрашивает «что показывает этот дашборд», «запроси эту метрику в Grafana», «этот алерт сейчас срабатывает?», «заглуши этот алерт» или хочет создать либо экспортировать дашборд — даже если он не говорит «API». Всегда начинай работу с этим сервисом с этого скилла: его готовые скрипты и рецепты — самый быстрый путь.
---

Базовый адрес Grafana — адрес самого экземпляра: Grafana Cloud — https://<your-org>.grafana.net, самостоятельно развёрнутая — там, где её запускает организация (например, https://grafana.example.com). Набор API одинаков; отличается только базовый адрес.

Единицы времени в разных конечных точках разные: /api/ds/query и /api/annotations принимают Unix-время в миллисекундах; история состояний алертов — Unix в секундах; заглушения Alertmanager — формат RFC-3339. Если их перепутать, придёт пустой результат, а не ошибка.

Настройка запросов

Аутентификацию берёт на себя среда выполнения: учётные данные подставляются в исходящие запросы к этому API, так что настраивать ничего не нужно. Не пытайся создавать, выпускать, обновлять или проверять токены и ключи. Переменные с учётными данными нужны только для того, чтобы запросы были корректно сформированы; если какая-то из них не задана, подставь любое значение-заглушку. Устойчивая ошибка 401 или 403 значит, что учётные данные для этого рабочего пространства не настроены, — сообщи об этом, а не разбирайся с авторизацией.

Адрес экземпляра должен быть настоящим: он входит в путь каждого запроса:

export GRAFANA_URL="https://grafana.example.com"   # no trailing slash
export GRAFANA_TOKEN="placeholder"                 # injected by the runtime; any value works

Каждый запрос:

curl -sS "${GRAFANA_URL}/api/..." -H "Authorization: Bearer ${GRAFANA_TOKEN}"

Проверка на здравый смысл — убедись, что адрес верный и рабочее пространство подключено:

curl -sS -w '\nHTTP %{http_code}\n' "${GRAFANA_URL}/api/user" -H "Authorization: Bearer ${GRAFANA_TOKEN}"
# 200 → the current user/service account. 401 → {"message":"Unauthorized"} — report it, don't debug auth.
# Service accounts also work: /api/org returns the current org.

Ошибка 403 обычно означает, что у настроенной учётной записи не хватает нужной роли (Viewer < Editor < Admin). Для запросов к источникам данных и чтения дашбордов достаточно Viewer.

Вспомогательная функция, которая используется ниже (необязательно):

grafana() { curl -sS "$@" -H "Authorization: Bearer ${GRAFANA_TOKEN}"; }

Основные операции

1. Поиск дашбордов и папок

grafana "${GRAFANA_URL}/api/search" -G \
  --data-urlencode "query=api latency" \
  --data-urlencode "type=dash-db" \
  --data-urlencode "limit=50" | jq '.[] | {uid, title, folderTitle, url}'

type принимает dash-db (дашборды) или dash-folder (папки); без него вернутся оба типа. Есть ещё tag=, folderUIDs=, starred=true.

2. Получение дашборда по UID

UID — короткая строка в адресе дашборда: .../d/<uid>/<slug>.

grafana "${GRAFANA_URL}/api/dashboards/uid/abc123xy" | \
  jq '{title: .dashboard.title, folder: .meta.folderTitle, panels: [.dashboard.panels[]? | {id, title, type}]}'

PromQL, LogQL и SQL каждой панели лежат в .dashboard.panels[].targets. Неверный UID возвращает {"message":"Dashboard not found"} (404).

3. Запрос к источнику данных

Так ты задаёшь те же вопросы, что и панель. Сначала найди UID источника данных:

grafana "${GRAFANA_URL}/api/datasources" | jq '.[] | {uid, name, type}'

Затем отправь POST на /api/ds/query. Форма queries[] зависит от type источника данных; вот пример для Prometheus:

NOW_MS=$(( $(date +%s) * 1000 )); FROM_MS=$(( NOW_MS - 3600000 ))
grafana -X POST "${GRAFANA_URL}/api/ds/query" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "'"${FROM_MS}"'",
    "to": "'"${NOW_MS}"'",
    "queries": [{
      "refId": "A",
      "datasource": {"uid": "<datasource_uid>"},
      "expr": "sum(rate(http_requests_total{job=\"api\"}[5m])) by (status)",
      "intervalMs": 30000,
      "maxDataPoints": 500
    }]
  }' | jq '.results.A.error // .results.A.frames[0].data.values'

Для Loki используй "expr": "{job=\"api\"} |= \"error\"" и при желании "queryType": "range". Для SQL-источников данных используй "rawSql": "SELECT ..." и "format": "table".

Ответы приходят в виде фреймов данных (data frames) Grafana: results.<refId>.frames[] с параллельными массивами столбцов в data.values и метаданными столбцов в schema.fields. **При сбое на стороне источника данных frames пуст, а ошибка Prometheus/Loki/SQL лежит в results.<refId>.error** — HTTP-статус при этом всё равно может быть 200 или 500, поэтому проверяй это поле, а не полагайся на один только статус.

4. Список правил алертов

Два раздела с разными задачами:

# live STATE (firing/pending/inactive) — read-only
grafana "${GRAFANA_URL}/api/prometheus/grafana/api/v1/rules" | \
  jq '.data.groups[]? | {folder: .file, group: .name, rules: [.rules[] | {name, state, health}]}'

# DEFINITIONS (query, condition, labels, for-duration) — full CRUD, no runtime state
grafana "${GRAFANA_URL}/api/v1/provisioning/alert-rules" | jq '.[] | {uid, title, folderUID, condition}'

Сегмент grafana в пути первого запроса — это буквальная подстановка {am_name} для встроенного Alertmanager; внешние Alertmanager используют UID своего источника данных. Ресурсы, записанные через API провижининга, заблокированы в интерфейсе, если при записи не отправить X-Disable-Provenance: true.

5. Заглушения (silences)

startsAt и endsAt — в формате RFC-3339 (date -u +%Y-%m-%dT%H:%M:%SZ).

# active silences
grafana "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silences" | \
  jq '.[] | select(.status.state=="active") | {id, comment, matchers, endsAt}'

# create a 2-hour silence matching a label
# GNU date; on BSD/macOS use: date -u -v+2H +%Y-%m-%dT%H:%M:%SZ
START=$(date -u +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u -d "+2 hours" +%Y-%m-%dT%H:%M:%SZ)
grafana -X POST "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silences" \
  -H "Content-Type: application/json" \
  -d '{
    "matchers": [{"name": "alertname", "value": "HighErrorRate", "isRegex": false, "isEqual": true}],
    "startsAt": "'"${START}"'", "endsAt": "'"${END}"'",
    "createdBy": "api", "comment": "investigating"
  }'
# success → {"silenceID": "..."}

# expire a silence
grafana -X DELETE "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silence/<silence_id>"

6. Аннотации

time и timeEnd — Unix-время в миллисекундах.

grafana -X POST "${GRAFANA_URL}/api/annotations" -H "Content-Type: application/json" \
  -d '{"time": '"$(( $(date +%s) * 1000 ))"', "tags": ["deploy","api"], "text": "Deployed v2.3.1"}'

grafana "${GRAFANA_URL}/api/annotations?from=${FROM_MS}&to=${NOW_MS}&tags=deploy" | jq .

7. Папки

grafana "${GRAFANA_URL}/api/folders" | jq '.[] | {uid, title}'
grafana -X POST "${GRAFANA_URL}/api/folders" -H "Content-Type: application/json" -d '{"title": "Team API"}'

8. Создание или обновление дашборда

grafana -X POST "${GRAFANA_URL}/api/dashboards/db" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {"uid": null, "title": "My Dashboard", "panels": [], "schemaVersion": 41},
    "folderUid": "<folder_uid>",
    "overwrite": false,
    "message": "created via API"
  }'

Чтобы обновить дашборд: сначала сделай GET, затем отправь весь JSON целиком с внесённым изменением — эта конечная точка заменяет дашборд. Укажи в dashboard.uid существующий UID и либо передай текущий dashboard.version (при несовпадении Grafana вернёт 412), либо задай overwrite: true.

Постраничная выдача

/api/search и /api/folders используют параметры запроса limit и page (нумерация с 1). /api/search по умолчанию отдаёт 1000 записей, максимум — 5000. У /api/annotations есть limit (по умолчанию 100), но нет page: вместо этого сужай окно from/to. Конечные точки Alertmanager постраничной выдачи не имеют. Упёршись в предел, сужай выборку через query=, tag= или folderUIDs=, а не листай всё подряд.

Ограничения частоты запросов

У самостоятельно развёрнутой Grafana по умолчанию нет встроенных лимитов на токен. Grafana Cloud может вернуть 429 при большой нагрузке запросами к API или данным — лимиты зависят от тарифа и конечной точки, поэтому соблюдай Retry-After, если он есть, а если нет — делай паузу и пробуй снова. **/api/ds/query — самый затратный путь**: каждый вызов разветвляется на запросы к нижележащей базе, поэтому объединяй несколько queries[] в один запрос, а не гоняй их в цикле.

Обработка ошибок

В теле ошибки всегда есть "message" (иногда "messageId"/"traceID"). Случаи, специфичные для сервиса:

• **412** — конфликт версий при сохранении дашборда. Сделай GET последней версии, примени своё изменение заново, передай version или задай overwrite: true.
• **200/500 на /api/ds/query** — сбой на стороне источника данных. Ошибка Prometheus/Loki/SQL лежит в results.<refId>.error; frames пуст.
• **403** — недостаточно прав. Viewer < Editor < Admin; действуют и права на уровне папки.

401 → учётные данные для этого рабочего пространства не настроены (сообщи, а не разбирайся). UID — короткие строки, чувствительные к регистру, а не названия.

Подробнее

В references/api.md — полный каталог конечных точек: дашборды, папки, источники данных, формы ds/query для разных источников данных, весь раздел единых алертов (правила алертов, контактные точки, политики уведомлений, тайминги отключения уведомлений, Alertmanager), аннотации, снапшоты, организации/пользователи/команды, сервисные аккаунты и короткие ссылки. Читай его, когда нужна конечная точка, которой нет выше.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-tag-plugins/tree/main/grafana/skills/grafana-api, лицензия Apache-2.0. Изменения: перевод на русский язык.