JSON-модель дашборда¶

Каждый дашборд в Grafana хранится как JSON-документ. Это не просто удобно для импорта-экспорта — это фундаментально. Любое движение мыши в интерфейсе создаёт, изменяет или удаляет JSON-свойства под капотом. Поэтому понимание JSON-модели — ключ к осознанной работе с Grafana.

Аналогия¶

Представьте чертёж дома. На чертеже — размеры комнат, расположение окон, материал стен. Этот чертёж можно распечатать, отправить другому архитектору, и тот построит точно такой же дом. JSON дашборда — это и есть такой чертёж. С помощью него вы можете воссоздать дашборд на другом сервере Grafana, поделиться им с коллегами, или положить в Git чтобы отслеживать изменения.

Структура JSON дашборда — разбор ключевых полей¶

Вот минимальный JSON дашборда, чтобы вы почувствовали структуру:

{
  "id": null,
  "title": "Мой первый дашборд",
  "tags": ["example", "newbie"],
  "timezone": "browser",
  "schemaVersion": 40,
  "version": 0,
  "panels": [],
  "templating": {
    "list": []
  }
}

А теперь разберём каждое значимое поле в том порядке, в котором они встречаются в полной модели.

`id`¶

Уникальный числовой идентификатор дашборда в базе Grafana. Присваивается автоматически при сохранении. При импорте JSON оставляйте null — Grafana сама назначит id.

`uid`¶

Строковый идентификатор, уникальный для каждого дашборда. Появился позже, чем id, потому что id — это «местный» номер в конкретном экземпляре Grafana. Если вы импортируете дашборд на другой сервер, id изменится, а uid останется тем же (при условии, что вы не изменили его специально). Именно на uid ссылаются переменные datasource, ссылки от панели к панели, и многие другие элементы. В отличие от id, uid переносим между экземплярами.

`title`¶

Заголовок дашборда. То, что отображается вверху интерфейса и в списке дашбордов. Может содержать пробелы, кириллицу и эмодзи наподобие 📊 — но последними лучше не злоупотреблять: они усложняют поиск и оскорбляют эстетический вкус администратора.

`tags`¶

Массив строк. Появились не просто так: когда у вас сотни дашбордов, поиск по названию перестаёт работать. Теги позволяют классифицировать дашборды сколь угодно гибко. Хороший пример тегов: ["production", "database", "postgresql"], ["staging", "cache", "redis"]. Плохой: ["дашборд", "дмитрий"]. Второй никому, кроме Дмитрия, не нужен.

`timezone`¶

Часовой пояс для дашборда. Варианты:

"browser" — автоматически подстраивается под часовой пояс браузера пользователя. Лучший выбор, если команда сидит в разных городах.
"utc" — все времена на дашборде показываются в UTC. Стандартный выбор для серверной инфраструктуры, потому что логи и метрики обычно пишутся именно в UTC.
любой IANA TZ identifier, например "Europe/Moscow", "America/New_York".

`refresh`¶

Автообновление дашборда. Строка, принимающая значения: "" (выключено), "5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d". Обсудим подробнее в главе про Settings.

`time`¶

Временной диапазон по умолчанию. Например { "from": "now-6h", "to": "now" }. Пользователь может его изменить в интерфейсе в любое время — это просто стартовое значение.

`schemaVersion`¶

Номер версии JSON-схемы. Grafana автоматически обновляет это поле при открытии старых дашбордов в новой версии сервера. Вам менять его вручную почти никогда не нужно.

`version`¶

Счётчик сохранений дашборда. Увеличивается на 1 при каждом нажатии Save. Используется для проверки конфликтов редактирования: если два человека одновременно откроют один дашборд и каждый нажмёт Save, второй получит предупреждение «версия изменилась» и сможет решить, перезаписать или отменить.

`panels`¶

Самый жирный массив. Каждый элемент — объект панели. Включает в себя id, title, type, gridPos (расположение в сетке), targets (запросы к источнику данных), fieldConfig, transformations, options и десятки других полей. Панелям посвящена вся Часть III.

`templating`¶

Объект, содержащий массив list — все переменные дашборда. Каждая переменная — это объект с name, type (query, constant, datasource, custom, interval, textbox, adhoc), query и другими полями. Переменные — это то, что превращает статический дашборд в динамический, с возможностью выбирать источник данных, сервер, регион. Подробно разберём в Части IV.

`annotations`¶

Объект с полем list — массив аннотаций уровня дашборда. Аннотации — это линии или области на графиках, которые показывают важные события: деплой новой версии, срабатывание алерта, запланированные работы. Подробно — в главе про аннотации.

`links`¶

Массив ссылок, которые показываются в верхней части дашборда. Можно связать дашборд PostgreSQL с дашбордом Loki по логам, с дашбордом Node Exporter по использованию CPU, и так далее. Подробно — в главе про ссылки.

`timepicker`¶

Объект настройки timepicker — кастомный выбор временных интервалов. Вы можете скрыть определённые интервалы (например убрать «Last 5 years», если ваш датасет существует всего месяц) или добавить свои.

`liveNow`¶

Булево поле. Если true, дашборд будет обновляться в реальном времени, без учёта интервала refresh. Используется для стриминга метрик через WebSocket — редко, но полезно.

`preload`¶

Булево. Если true, дашборд начинает загружать данные сразу при загрузке страницы, не дожидаясь, пока пользователь откроет его. Полезно для дашбордов на информационных панелях.

`editable`¶

Булево. Если false, дашборд не может быть изменён никем, даже админом. По сути — вечная блокировка от случайного редактирования. Используйте осторожно: снять можно только через API или прямое изменение в базе данных.

Импорт и экспорт¶

Экспорт. Зайдите в Dashboard Settings → JSON Model. Скопируйте содержимое и сохраните в файл .json. Или нажмите кнопку «Save JSON to file» — браузер скачает файл.

Импорт. Есть три способа:

Через UI: Dashboards → New → Import → вставьте JSON или загрузите файл.
Provisioning: положите JSON-файлы в директорию, за которой следит Grafana, и они автоматически загрузятся при старте. Подробно — в Части IV.
Dashboard API: POST /api/dashboards/db с JSON-телом запроса. Позволяет автоматизировать импорт через скрипты, CI/CD или Ansible.

Dashboard API¶

Grafana предоставляет полноценный REST API для работы с дашбордами:

Метод	Путь	Что делает
`POST`	`/api/dashboards/db`	Создаёт или обновляет дашборд
`GET`	`/api/dashboards/uid/:uid`	Получает дашборд по UID
`DELETE`	`/api/dashboards/uid/:uid`	Удаляет дашборд
`GET`	`/api/search`	Ищет дашборды по тегам, названию, папке

API требует аутентификацию (API key или Service Account token). Подробнее — в разделе про Provisioning и автоматизацию.

Когда редактировать JSON напрямую¶

В 95% случаев это не нужно — интерфейса достаточно. Но есть сценарии, где ручное редактирование JSON незаменимо:

Массовое переименование панелей, источников данных или переменных — открыл JSON, Ctrl+F, заменил.
Перенос дашборда между окружениями с заменой datasource UID.
Создание дашбордов скриптами (например, генератор дашбордов по шаблону).
Версионирование: JSON дашборда можно положить в Git и отслеживать изменения через git diff. Не бинарный, а человеко-читаемый текст!

В оставшихся 5% случаев редактирование JSON напрямую может сломать дашборд. Делайте бекап (version не спасёт — он лишь счётчик). А лучше — дублируйте дашборд перед экспериментами через Save As.

Далее: Настройки дашборда

JSON-модель дашборда¶

Аналогия¶

Структура JSON дашборда — разбор ключевых полей¶

id¶

uid¶

title¶

tags¶

timezone¶

refresh¶

time¶

schemaVersion¶

version¶

panels¶

templating¶

annotations¶

links¶

timepicker¶

liveNow¶

preload¶

editable¶