Перейти к основному содержимому

7.04. Справочник по Grafana

ДЛЯ НОВИЧКОВНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНОВ РАЗРАБОТКЕ
Разработчику Архитектору Инженеру

Справочник по Grafana​

Основные сущности​

  • Организация (Organization) — изолированное пространство пользователей, дашбордов и настроек.
  • Пользователь (User) — аккаунт с ролью внутри организации.
  • Роль (Role) — уровень доступа: Viewer, Editor, Admin.
  • Команда (Team) — группа пользователей для управления правами доступа.
  • Источник данных (Data Source) — внешняя система, откуда Grafana получает данные (Prometheus, Loki, MySQL и другие).
  • Дашборд (Dashboard) — страница с набором визуальных панелей.
  • Панель (Panel) — отдельный элемент визуализации: график, таблица, текст и так далее.
  • Переменная (Variable) — динамический параметр для фильтрации или переиспользования значений в дашборде.
  • Аннотация (Annotation) — временная метка с описанием события.
  • Оповещение (Alert) — правило, срабатывающее при выполнении условия.
  • Правило оповещения (Alert Rule) — логическое выражение с пороговыми значениями и действиями.

Источники данных (Data Sources)​

Grafana поддерживает более 50 типов источников данных. Наиболее популярные:

  • Prometheus
  • Loki
  • Elasticsearch
  • Graphite
  • InfluxDB
  • MySQL / PostgreSQL / Microsoft SQL Server / Oracle
  • OpenTSDB
  • Azure Monitor
  • AWS CloudWatch
  • Jaeger / Tempo (трассировки)
  • CSV / JSON (через плагины)

Общие параметры источника данных​

  • Name — имя источника в интерфейсе Grafana.
  • Type — тип источника (выбирается из списка).
  • URL — адрес сервера источника данных.
  • Access — режим подключения: Server (через backend Grafana) или Browser (прямое подключение из браузера).
  • Auth — метод аутентификации: Basic Auth, Token, OAuth, TLS Client Cert и другие.
  • Database — имя базы данных (если применимо).
  • HTTP Method — GET или POST для некоторых источников.
  • Custom HTTP Headers — дополнительные заголовки запроса.
  • Timeout — максимальное время ожидания ответа.
  • Cache TTL — время кэширования метаданных.

Дашборды​

Свойства дашборда​

  • Title — заголовок дашборда.
  • Description — описание.
  • Tags — теги для поиска и группировки.
  • Folder — папка, в которой хранится дашборд.
  • Time range — диапазон времени по умолчанию (Last 6 hours, Last 30 days, относительный или абсолютный).
  • Refresh interval — автоматическое обновление (например, 5s, 1m, Off).
  • Editable — разрешение на редактирование.
  • UID — уникальный идентификатор дашборда (используется в URL и API).

Настройки дашборда (Dashboard settings → General)​

  • Timezone — часовой пояс: Browser, UTC или конкретный регион.
  • Week start — день начала недели.
  • Auto-fit panels — автоматическая подгонка панелей по высоте.
  • Graph tooltip — поведение подсказок: Default, Shared crosshair, Shared tooltip.

Панели​

Типы панелей​

  • Time series — график временных рядов.
  • Bar chart — столбчатая диаграмма.
  • Stat — одно значение (текущее, среднее, максимум и т.п.).
  • Table — табличное представление.
  • Heatmap — тепловая карта.
  • Logs — просмотр логов.
  • Traces — визуализация трассировок.
  • Text — произвольный текст (Markdown или HTML).
  • Gauge — круговой индикатор.
  • Pie chart — круговая диаграмма.
  • Node graph — граф зависимостей.
  • Histogram — гистограмма распределения.
  • State timeline — временная шкала состояний.
  • Status history — история статусов.
  • Geomap — карта с географическими данными.
  • Custom plugins — сторонние визуализации.

Общие свойства всех панелей​

  • Title — заголовок панели.
  • Description — пояснение (появляется при наведении).
  • Transparent background — прозрачный фон.
  • Span — ширина панели (от 1 до 24 единиц сетки).
  • Height — высота в пикселях.
  • Display mode — режим отображения (например, «Fill» или «Fit»).
  • Links — гиперссылки, привязанные к панели.
  • Repeat by variable — дублирование панели для каждого значения переменной.

Переменные (Variables)​

Переменные позволяют делать дашборды интерактивными и параметризованными.

Типы переменных​

  • Constant — фиксированное значение.
  • Query — значение, полученное из источника данных.
  • Custom — список значений, заданный вручную.
  • Text box — поле ввода текста.
  • Data source — выбор источника данных из списка.
  • Interval — выбор интервала времени (1m, 5m, 1h и т.д.).
  • Ad hoc filters — фильтры, применяемые ко всем запросам (только для Prometheus, Elasticsearch и некоторых других).

Свойства переменной​

  • Name — имя переменной (используется как $name или [[name]]).
  • Label — отображаемая надпись над выпадающим списком.
  • Hide — видимость: None, Label, Variable.
  • Type — тип переменной.
  • Data source — источник данных (для Query-переменных).
  • Query — запрос для получения значений.
  • Regex — регулярное выражение для фильтрации результатов.
  • Sort — порядок сортировки: Disabled, Alphabetical, Numerical.
  • Multi-value — возможность выбрать несколько значений.
  • Include All option — добавление опции «All».
  • All value — значение, подставляемое при выборе «All».
  • Current value — текущее выбранное значение по умолчанию.

Запросы (Queries)​

Каждая панель содержит один или несколько запросов к источнику данных.

Общие элементы запроса​

  • Query editor — интерфейс для написания запроса (зависит от типа источника).
  • Format as — формат возвращаемых данных: Time series, Table, Logs, Trace, Heatmap.
  • Min interval — минимальный интервал агрегации.
  • Max data points — ограничение количества точек на графике.
  • Legend — шаблон имени серии (поддерживает переменные и поля).
  • Alias by — переименование меток (в Prometheus).

Примеры функций и операторов (на примере Prometheus)​

  • rate(metric[5m]) — скорость изменения за 5 минут.
  • irate(metric[5m]) — мгновенная скорость.
  • sum by (job) (metric) — суммирование по метке job.
  • avg_over_time(metric[1h]) — среднее значение за час.
  • topk(5, metric) — топ-5 значений.
  • histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) — 95-й перцентиль.

Аннотации​

Аннотации отображаются как вертикальные линии на временных шкалах.

Типы аннотаций​

  • Dashboard annotations — ручные заметки.
  • Data source annotations — автоматические события из источника (например, деплои из CI/CD).

Свойства аннотации​

  • Name — имя аннотации.
  • Data source — источник данных.
  • Icon color — цвет иконки.
  • Enable — активность аннотации.
  • Query — запрос для получения событий.
  • Tag keys / Text column — поля для отображения.

Оповещения (Alerting)​

Grafana поддерживает два режима оповещений:

  • Legacy alerts — устаревшая система (до Grafana 8).
  • Unified Alerting — современная система (начиная с Grafana 8+).

Компоненты Unified Alerting​

  • Alert rule — правило с условиями и выражениями.
  • Contact point — способ доставки: Email, Slack, PagerDuty, Webhook и другие.
  • Notification policy — маршрутизация оповещений по условиям.
  • Silence — временное отключение оповещений.
  • Template — шаблон сообщения (на основе Go template).

Параметры Alert Rule​

  • Rule name — имя правила.
  • Evaluation interval — частота проверки условия.
  • For — длительность, в течение которой условие должно быть истинным.
  • Condition — выражение на языке запросов (например, A > 90).
  • Labels — дополнительные метки для фильтрации.
  • Annotations — пояснения и ссылки.

Contact Point Types​

  • Email
  • Slack
  • Microsoft Teams
  • Discord
  • Telegram
  • PagerDuty
  • Opsgenie
  • VictorOps
  • Webhook
  • Kafka
  • LINE
  • Pushover
  • Threema

Конфигурация Grafana (grafana.ini)​

Основной файл конфигурации — grafana.ini, расположенный по умолчанию в /etc/grafana/ (Linux) или %PROGRAMFILES%\GrafanaLabs\grafana\conf\ (Windows). Он определяет поведение сервера, подключение к базам данных, параметры безопасности, внешний вид и многое другое.

Основные секции конфигурации​

[server]​

  • http_addr — IP-адрес, на котором слушает Grafana.
  • http_port — порт HTTP-сервера (по умолчанию 3000).
  • domain — доменное имя для генерации абсолютных URL.
  • root_url — базовый URL для всех ссылок (например, %(protocol)s://%(domain)s:/grafana/ при размещении за reverse proxy).
  • serve_from_sub_path — разрешить обслуживание из подпути.
  • enforce_domain — требовать соответствие заголовка Host указанному домену.
  • cert_file / cert_key — пути к TLS-сертификатам для HTTPS.

[database]​

  • type — тип БД: sqlite3, mysql, postgres.
  • host — хост и порт СУБД.
  • name — имя базы данных.
  • user / password — учётные данные.
  • ssl_mode — режим SSL для PostgreSQL (disable, require, verify-full).
  • max_idle_conn / max_open_conn — лимиты соединений.

[auth]​

  • login_cookie_name — имя cookie аутентификации.
  • login_maximum_inactive_lifetime_duration — максимальное время неактивности до разлогина.
  • login_maximum_lifetime_duration — максимальная длительность сессии.
  • disable_login_form — отключить форму входа (если используется OAuth/SAML).
  • signout_redirect_url — URL после выхода.

[auth.basic]​

  • enabled — разрешить базовую аутентификацию.

[auth.anonymous]​

  • enabled — разрешить анонимный доступ.
  • org_name — организация по умолчанию для анонимов.
  • org_role — роль (Viewer, Editor).

[auth.google], [auth.github], [auth.gitlab] и другие OAuth-провайдеры​

  • enabled
  • client_id / client_secret
  • scopes
  • auth_url / token_url
  • allowed_domains / allowed_organizations

[users]​

  • allow_sign_up — разрешить самостоятельную регистрацию.
  • auto_assign_org — автоматически назначать новому пользователю организацию.
  • auto_assign_org_role — роль по умолчанию (Viewer, Editor, Admin).
  • viewers_can_edit — разрешить Viewer’ам редактировать панели.
  • editors_can_admin — разрешить Editor’ам администрировать дашборды.

[smtp]​

  • enabled
  • host
  • user / password
  • from_address
  • from_name
  • skip_verify — игнорировать ошибки SSL сертификата SMTP.

[emails]​

  • welcome_email_on_sign_up
  • templates_pattern — шаблоны писем.

[log]​

  • mode — console, file, syslog.
  • level — debug, info, warn, error, critical.
  • file_format — формат логов.
  • max_lines / max_size_shift / daily_rotate — ротация файлов.

[metrics]​

  • enabled — включить внутренние метрики Grafana (экспортируются в Prometheus-совместимом формате).
  • interval_seconds — интервал сбора.

[analytics]​

  • reporting_enabled — отправлять анонимную статистику в Grafana Labs.
  • check_for_updates — проверять наличие обновлений.

[dashboards]​

  • versions_to_keep — количество версий дашборда для хранения.
  • default_home_dashboard_path — путь к JSON-файлу главного дашборда.

[panels]​

  • enable_alpha — включить экспериментальные панели.
  • disable_sanitize_html — разрешить HTML в текстовых панелях (опасно!).

[plugins]​

  • enable_alpha
  • plugin_admin_enabled — разрешить установку плагинов через UI.
  • plugin_catalog_url — URL каталога плагинов.

[unified_alerting]​

  • enabled — включить Unified Alerting (вместо legacy alerts).
  • ha_peers — список адресов других инстансов для высокой доступности.
  • ha_listen_address — адрес для внутреннего HA-трафика.

Provisioning​

Grafana поддерживает декларативную настройку через YAML-файлы. Это позволяет управлять источниками данных, дашбордами, контактными точками и правилами оповещений без ручного ввода в UI.

Папки provisioning​

По умолчанию: /etc/grafana/provisioning/

Подпапки:

  • datasources/ — .yaml файлы с описанием источников данных.
  • dashboards/ — указание путей к JSON-файлам дашбордов.
  • notifiers/ — контактные точки (устаревший формат).
  • alerting/ — правила оповещений и политики (Unified Alerting).
  • plugins/ — настройки плагинов.
  • access-control/ — права доступа (RBAC).

Пример datasources.yaml​

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    access: proxy
    isDefault: true
    editable: false

Пример dashboards.yaml​

apiVersion: 1
providers:
  - name: 'default'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    editable: true
    options:
      path: /var/lib/grafana/dashboards

Grafana HTTP API​

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

Общие особенности​

  • Базовый путь: /api
  • Аутентификация: токен (API Key или Service Account Token) в заголовке Authorization: Bearer <token>
  • Формат ответа: JSON
  • Коды ошибок: 400 (неверный запрос), 401 (неавторизован), 403 (запрещено), 404 (не найдено), 500 (внутренняя ошибка)

Основные эндпоинты​

Управление пользователями​

  • GET /api/users — список пользователей
  • POST /api/users — создать пользователя
  • GET /api/users/:id — получить данные пользователя
  • PUT /api/users/:id — обновить
  • DELETE /api/users/:id — удалить

Управление организациями​

  • GET /api/orgs
  • POST /api/orgs
  • GET /api/org
  • PUT /api/org
  • DELETE /api/orgs/:orgId

Источники данных​

  • GET /api/datasources
  • POST /api/datasources
  • GET /api/datasources/name/:name
  • PUT /api/datasources/:id
  • DELETE /api/datasources/:id

Дашборды​

  • POST /api/dashboards/db — создать/обновить
  • GET /api/dashboards/uid/:uid
  • DELETE /api/dashboards/uid/:uid
  • GET /api/search?query=... — поиск

Переменные​

Переменные хранятся внутри JSON дашборда, отдельного API нет.

Оповещения (Unified Alerting)​

  • GET /api/v1/provisioning/alert-rules
  • POST /api/v1/provisioning/alert-rules
  • GET /api/v1/provisioning/contact-points
  • POST /api/v1/provisioning/policies

CLI (Command Line Interface)​

Команда grafana-cli позволяет управлять плагинами и выполнять служебные операции.

Основные команды​

  • grafana-cli plugins list-remote — список доступных плагинов
  • grafana-cli plugins install <plugin-id> — установить плагин
  • grafana-cli plugins update <plugin-id> — обновить
  • grafana-cli plugins ls — установленные плагины
  • grafana-cli admin reset-admin-password <new-password> — сброс пароля администратора

Безопасность​

Рекомендуемые практики​

  • Отключить анонимный доступ, если не требуется.
  • Использовать HTTPS (через reverse proxy или встроенный TLS).
  • Ограничить права пользователей (минимально необходимые роли).
  • Регулярно обновлять Grafana и плагины.
  • Не использовать disable_sanitize_html = true без крайней необходимости.
  • Хранить секреты (пароли, токены) в секрете (Vault, Kubernetes Secrets), а не в grafana.ini.
  • Включить двухфакторную аутентификацию (2FA) для администраторов.
  • Настроить rate limiting на уровне reverse proxy (Nginx, Traefik).

RBAC (Role-Based Access Control)​

Доступно в Grafana Enterprise и частично в OSS (начиная с v10).

  • Роли: fixed (Viewer, Editor, Admin) и custom.
  • Разрешения: dashboards:read, datasources:write, alerts:create и другие.
  • Привязка ролей к пользователям, командам или организациям.

Кэширование и производительность​

  • Dashboard caching — Grafana кэширует результаты запросов в памяти (настраивается через cache в datasource).
  • Browser caching — статические ресурсы (JS, CSS) кэшируются браузером.
  • Query caching — некоторые источники данных (например, MySQL) поддерживают кэширование на стороне Grafana.
  • CDN — можно размещать статику через CDN при self-hosted развёртывании.

Логирование и мониторинг​

  • Внутренние метрики доступны по /metrics (Prometheus-формат).
  • Логи содержат информацию о запросах, ошибках, авторизации.
  • Можно интегрировать с Loki для централизованного сбора логов.
  • Алерты могут быть настроены на внутренние метрики Grafana (например, высокая задержка запросов).

Темы оформления (Themes)​

Grafana поддерживает несколько встроенных тем и позволяет настраивать внешний вид через конфигурацию или плагины.

Встроенные темы​

  • Default — светлая тема.
  • Dark — тёмная тема.
  • Light — альтернативная светлая тема с более нейтральными оттенками.

Настройка темы​

  • Через UI: Preferences → Theme
  • Через grafana.ini: 
    [ui]
    default_theme = dark
  • Через URL-параметр: ?theme=dark

Кастомизация цветов​

  • Цветовые палитры для графиков задаются в настройках панели (Time series → Standard options → Color scheme).
  • Поддерживаются:
    • Continuous — градиент от одного цвета к другому.
    • Discrete — фиксированные цвета для категорий.
    • Thresholds — цвета по пороговым значениям.

Плагины​

Grafana расширяется за счёт плагинов двух типов:

  • Data source plugins — подключение новых источников данных.
  • Panel plugins — новые типы визуализаций.

Установка плагинов​

  • Через CLI: grafana-cli plugins install <plugin-id>
  • Через UI (если включено): Configuration → Plugins
  • Через provisioning: YAML-файл в /etc/graf-ana/provisioning/plugins/

Популярные сторонние плагины​

  • Worldmap Panel — отображение метрик на карте мира.
  • Diagram Panel — визуализация диаграмм (например, flowchart).
  • Clock Panel — цифровые часы.
  • Status Dot Panel — индикаторы состояния.
  • Multistat Panel — расширенный статистический виджет.

Разработка собственных плагинов​

  • Используется TypeScript + React.
  • Требуется Node.js и Grafana Toolkit.
  • Структура:
    • src/ — исходный код
    • plugin.json — метаданные
    • module.ts — точка входа
  • Плагин может быть загружен локально или опубликован в Grafana Catalog.

Совместная работа и обмен​

Импорт / экспорт дашбордов​

  • Экспорт: Dashboard → Share → Export
    • Формат: JSON
    • Включает все панели, переменные, аннотации
  • Импорт: Create → Import
    • Поддерживает JSON-файлы и URL из Grafana.com Dashboards

Grafana.com Dashboards​

  • Публичный репозиторий готовых дашбордов.
  • Поиск по источникам данных, меткам, популярности.
  • Пример: официальные дашборды для Prometheus exporters.

Версионирование​

  • Каждое изменение сохраняется как новая версия.
  • Можно просматривать историю и откатываться.
  • Максимальное количество хранимых версий задаётся в grafana.ini: 
    [dashboards]
    versions_to_keep = 20

Комментарии и обсуждения​

  • Встроенной системы комментариев нет.
  • Интеграция с внешними системами (Slack, Teams) через оповещения.
  • Рекомендуется использовать GitOps: хранить JSON-дашборды в Git и управлять через CI/CD.

Шаблонизация и повторное использование​

Шаблоны дашбордов​

  • Создание шаблона: сохранить дашборд как базовый.
  • Использование: клонировать и адаптировать под конкретную задачу.
  • Переменные позволяют делать один дашборд универсальным для множества сервисов.

Repeat panels​

  • Панель может автоматически дублироваться по значениям переменной.
  • Пример: одна панель для CPU usage, но повторяется для каждого сервера ($server).

Folder permissions​

  • Права доступа можно назначать на уровне папки.
  • Поддержка RBAC: разрешения на чтение/редактирование для пользователей и команд.

Продвинутые техники запросов​

Transformations (преобразования)​

После получения данных можно применить преобразования:

  • Reduce — агрегация (среднее, максимум, последнее значение).
  • Organize fields — переименование, скрытие, изменение порядка колонок.
  • Join by field — объединение нескольких запросов по общему полю.
  • Filter data by values — фильтрация строк.
  • Calculate field — создание нового поля на основе формулы.
  • Labels to fields — преобразование меток Prometheus в колонки.
  • Series to rows — развёртывание временных рядов в строки.

Mixed data sources​

  • Одна панель может использовать несколько источников данных.
  • Полезно для сравнения метрик из Prometheus и логов из Loki.

Query chaining​

  • Результат одного запроса может использоваться как вход для другого.
  • Пример: получить список хостов из MySQL, затем запросить их метрики в Prometheus.

Экспорт и внедрение​

Embedding​

  • Дашборды можно встраивать в другие веб-приложения через iframe.
  • Требуется включить CORS и настроить аутентификацию (например, через API-токен в URL).
  • Параметры в URL:
    • orgId=1
    • refresh=30s
    • from=now-6h&to=now
    • var-server=web01

Снимки (Snapshots)​

  • Публичная ссылка на текущее состояние дашборда (без привязки к данным в реальном времени).
  • Полезно для демонстрации или отчётов.
  • Срок жизни: до 7 дней (по умолчанию), можно продлить.

Генерация отчётов (Enterprise)​

  • В Grafana Enterprise доступна функция Report generation.
  • Автоматическая отправка PDF/CSV по расписанию.
  • Поддержка параметризованных отчётов (через переменные).

Лучшие практики​

Проектирование дашбордов​

  • Один дашборд — одна цель (например, мониторинг одного микросервиса).
  • Использовать согласованную цветовую схему.
  • Минимизировать количество панелей на экране.
  • Добавлять описания и ссылки на документацию.

Производительность​

  • Избегать запросов с высокой кардинальностью (много уникальных меток в Prometheus).
  • Использовать min interval для снижения нагрузки.
  • Кэшировать результаты в источнике данных (например, recording rules в Prometheus).

Безопасность​

  • Не хранить чувствительные данные в переменных или аннотациях.
  • Использовать Service Accounts вместо пользовательских токенов для автоматизации.
  • Ограничивать права на уровне datasource (например, только read-only).

Интеграции​

Системы мониторинга​

  • Prometheus — основной источник для метрик.
  • Loki — для логов.
  • Tempo — для трассировок.
  • Mimir / Cortex — масштабируемые решения на базе Prometheus.

CI/CD​

  • Grafana может получать аннотации о деплоях из GitLab CI, GitHub Actions, Jenkins.
  • Пример: отправка POST-запроса в /api/annotations после успешного релиза.

Alerting​

  • Интеграция с PagerDuty, Opsgenie, Slack, Telegram.
  • Возможность отправки вебхуков в собственные сервисы.
  • Поддержка группировки и маршрутизации оповещений.

Отладка и диагностика​

Проверка запросов​

  • В редакторе запроса есть кнопка Explain (для некоторых источников).
  • Можно просмотреть сырые данные в формате JSON/Table.

Логи Grafana​

  • Уровень debug помогает отследить ошибки provisioning’а.
  • Логи запросов включаются через [log] секцию.

Health check​

  • Эндпоинт /api/health возвращает статус сервера.
  • Поля: status, database, version.