| 1 | # Справочник: Grafana (v1) |
| 2 | |
| 3 | > **Назначение:** база для ответов по Grafana — понятия, где что искать в UI и в документации, типовые задачи админа. Без привязки к конкретным инстансам и паролям. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## 1. Ключевые понятия |
| 8 | |
| 9 | - **Дашборд (dashboard):** набор панелей и визуализаций для мониторинга и анализа. Может использовать несколько источников данных. Главный интерфейс для просмотра метрик и состояния систем. |
| 10 | - **Источник данных (data source):** подключение к хранилищу данных — БД, time series (Prometheus, InfluxDB), облачные сервисы (CloudWatch, Azure Monitor), MySQL, PostgreSQL и др. У каждого типа — свой редактор запросов. Источники используются дашбордами, правилами алертов и разделом Explore. |
| 11 | - **Панель (panel):** один блок визуализации на дашборде. Получает данные по запросам к data source; тип визуализации (график, таблица, алерт-лист и т.д.) настраивается. Панель «Alert list» показывает текущие алерты (firing, pending, normal). |
| 12 | - **Алерт (alert):** правило, срабатывающее по запросам и условиям к данным из data source. Состоит из: запрос(ы), при необходимости — выражения/трансформации, условие срабатывания. Можно создавать из любого источника с включённым alerting. Для каждой серии или строки, нарушающей условие, создаётся instance алерта. |
| 13 | |
| 14 | Поток: Data source → запросы в панелях и в alert rules → визуализация и уведомления. |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## 2. Где что искать в веб-интерфейсе |
| 19 | |
| 20 | - **Боковое меню:** если не видно — нажать на иконку Grafana в левом верхнем углу. |
| 21 | - **Администрирование:** иконка **шестерёнки (⚙️)** в боковом меню → Administration. Там: Data Sources, Users, Teams, Roles, Organization settings, Plugins, Provisioning и др. Только пользователи с ролью Organization Admin могут добавлять/редактировать источники данных. |
| 22 | - **Источники данных:** Configuration (шестерёнка) → Data Sources. Добавление и правка подключений; у каждого типа — свои поля (URL, auth, таймауты). |
| 23 | - **Дашборды:** раздел Dashboards (в меню). Создание, поиск, открытие; организация в **папки (folders)** для прав и навигации. Настройки дашборда: кнопка **Settings** на открытом дашборде; **Edit** — режим редактирования панелей и запросов. В настройках: JSON-модель, переменные, аннотации, теги, время по умолчанию. **Snapshot:** снимок дашборда в режиме только чтения (ссылка для шаринга без доступа к данным в реальном времени). |
| 24 | - **Алерты:** в современных версиях — Alerting в меню (правила, контактные точки, политики уведомлений). Alert list как тип панели — для отображения списка алертов на дашборде. |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## 3. Документация (официальная) |
| 29 | |
| 30 | - **Базовый URL:** `https://grafana.com/docs/grafana/` (актуальная версия — latest или next для превью). |
| 31 | - **Основные разделы:** |
| 32 | - Dashboards: создание, панели, переменные, аннотации. |
| 33 | - Data sources: управление, добавление, типы (Prometheus, InfluxDB, CloudWatch и т.д.). |
| 34 | - Alerting: основы, правила, условия, контакты, политики. |
| 35 | - Administration: управление источниками, пользователями, provisioning, плагины. |
| 36 | - **Структура:** левая боковая навигация, вложенные разделы по продукту (Grafana OSS, Cloud, Enterprise). Для быстрого ответа «где в доке про X» — вести к соответствующему подразделу (например datasources, alerting, administration). |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## 4. Типы источников данных (data sources) |
| 41 | |
| 42 | - **Встроенные и популярные:** Prometheus (метрики, PromQL), InfluxDB (временные ряды), Loki (логи, LogQL), Tempo (трейсы), Elasticsearch, MySQL, PostgreSQL, Graphite, CloudWatch, Azure Monitor и др. У каждого — свой редактор запросов и синтаксис. |
| 43 | - **Loki:** лог-агрегатор Grafana; запросы на LogQL; связь с трейсами (derived fields → переход к Tempo). **Tempo:** распределённая трассировка; интеграция с Prometheus (exemplars) и Loki. |
| 44 | - **Плагины:** Zabbix, MongoDB, Splunk и др. — из каталога плагинов; настройка в Data Sources после установки. Документация по каждому типу: grafana.com/docs, раздел Data sources. |
| 45 | |
| 46 | --- |
| 47 | |
| 48 | ## 5. Типовые задачи админа |
| 49 | |
| 50 | - **Добавить источник данных:** Configuration → Data Sources → Add data source; выбрать тип, заполнить URL и при необходимости учётные данные. |
| 51 | - **Изменить дашборд:** открыть дашборд → Edit; править панели, запросы, переменные; Save. |
| 52 | - **Настроить алерт:** Alerting → Alert rules → New alert rule; указать запрос(ы), условие, контактные точки и политику. |
| 53 | - **Разрешения и роли:** Administration → Users и Teams; роли (Viewer, Editor, Admin, Organization Admin) задают доступ к дашбордам и к настройкам (в т.ч. к добавлению data sources). |
| 54 | - **Provisioning:** загрузка дашбордов и источников из файлов/конфигов (документация — Administration → Provisioning). |
| 55 | |
| 56 | Конкретные URL, логины и токены — только из локального контекста пользователя. |
| 57 | |
| 58 | --- |
| 59 | |
| 60 | ## 6. Диагностика и типовые проблемы |
| 61 | |
| 62 | - **Нет данных на панели:** проверить data source (Test в настройках источника), запрос (синтаксис, диапазон времени), права доступа к хранилищу. |
| 63 | - **Алерт не срабатывает / срабатывает не так:** проверить условие (query, expression, threshold), интервал оценки, контактные точки и маршрутизацию уведомлений. |
| 64 | - **Не видно меню/настроек:** проверить роль пользователя (Organization Admin нужен для управления источниками данных и части админ-функций). |
| 65 | |
| 66 | --- |
| 67 | |
| 68 | ## 7. Связь с другими системами |
| 69 | |
| 70 | - **Zabbix:** данные из Zabbix можно отображать в Grafana через плагин/прокси (например Zabbix plugin for Grafana или экспорт в Prometheus/InfluxDB). Конкретная схема — по документации плагина и локальной конфигурации. |
| 71 | - **Prometheus / InfluxDB / Loki:** типовые data sources для метрик и логов; настройка в Data Sources по официальной документации Grafana для каждого типа. |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## 8. Установка (платформы) |
| 76 | |
| 77 | - **Документация:** `https://grafana.com/docs/grafana/latest/setup-grafana/install-grafana/` — установка под Linux (deb/rpm), Docker, прочие способы. |
| 78 | - **Docker:** образы `grafana/grafana` (OSS) и `grafana/grafana-enterprise`; порт 3000. Конфиг: либо монтировать свой `grafana.ini` (`-v /path/grafana.ini:/etc/grafana/grafana.ini`), либо переменные окружения `GF_<SECTION>_<KEY>` (например `GF_SECURITY_ADMIN_USER`, `GF_SERVER_HTTP_PORT`). Документация: Configure a Grafana Docker image. |
| 79 | - **Пакеты (Linux):** после установки конфиг обычно `/etc/grafana/grafana.ini`, данные — `/var/lib/grafana`. |
| 80 | |
| 81 | --- |
| 82 | |
| 83 | ## 9. Под капотом: конфиг, данные, БД |
| 84 | |
| 85 | - **grafana.ini:** основной конфиг — БД, сервер (порт, домен), безопасность, почта, плагины, логи и т.д. Расположение: Linux пакеты — `/etc/grafana/grafana.ini`; Docker — монтировать с хоста или задавать через env. После изменений — перезапуск Grafana. Документация: Configure Grafana. |
| 86 | - **Данные и плагины:** deb/rpm — `/var/lib/grafana` (в т.ч. `grafana.db`, `plugins/`); при установке из бинарника/исходников — `$WORKING_DIR/data`. Бэкап: копировать эту директорию и при необходимости сам конфиг. |
| 87 | - **БД:** по умолчанию SQLite (`grafana.db`). Для продакшена можно переключить на MySQL или PostgreSQL (секция `[database]` в grafana.ini). Миграции — при старте Grafana по версии. |
| 88 | |
| 89 | --- |
| 90 | |
| 91 | ## 10. Бэкап, обновление, безопасность |
| 92 | |
| 93 | - **Бэкап:** копировать изменённый `grafana.ini`; копировать `/var/lib/grafana` (или аналог) — БД, плагины. Для SQLite — желательно останавливать Grafana на время копирования `grafana.db`. MySQL/PostgreSQL — стандартный dump. Дашборды можно экспортировать в JSON и хранить в Git/provisioning. Документация: Back up Grafana. |
| 94 | - **Provisioning:** дашборды и data sources можно задавать файлами (YAML/JSON) в заданных каталогах — тогда конфиг и дашборды версионируются; изменения из UI в provisioned-объекты обратно в файлы не пишутся. Документация: Provision resources, Set up file provisioning. |
| 95 | - **Обновление:** по официальному Upgrade guide (проверить совместимость, бэкап перед обновлением). |
| 96 | - **Безопасность:** роли (Viewer, Editor, Admin, Organization Admin), смена пароля админа по умолчанию, при необходимости — обратный прокси и HTTPS; настройки в grafana.ini и в UI (Administration). |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## 11. Переменные дашборда, аннотации, Explore, плагины |
| 101 | |
| 102 | - **Переменные (template variables):** на дашборде задаются переменные (например список хостов, окружений, data source), которые подставляются в запросы панелей; пользователь выбирает значение из выпадающего списка — все панели перезапрашивают данные с учётом выбора. Настройка: Dashboard settings → Variables. Типы: **Query** (значения из запроса к data source), **Custom** (список через запятую), **Constant** (фиксированное значение), **Text box**, **Interval** и др. В запросах и заголовках: `${var_name}`; модификаторы формата: `:csv`, `:json`, `:regex` и т.д. Документация: Variable syntax. |
| 103 | - **Аннотации (annotations):** события с временной меткой и текстом, отображаемые на графиках (вертикальная линия + подпись). Источник — data source (запрос возвращает поля времени и текста) или вручную. Помогают соотносить всплески метрик с деплоями, инцидентами и т.д. Документация: Dashboards → Annotations. |
| 104 | - **Explore:** режим «исследования» — произвольные запросы к выбранному data source без привязки к дашборду; проверка запросов, отладка, экспорт в панель. Доступ из меню (компас/иконка Explore). |
| 105 | - **Плагины:** расширения — data sources (в т.ч. Zabbix, MongoDB, Splunk, облака), панели, приложения. Установка: Administration → Plugins или через CLI; обновление из каталога плагинов Grafana. Официальный каталог и документация по каждому плагину — на grafana.com/grafana/plugins. |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## 12. Алерты: контактные точки и политики уведомлений |
| 110 | |
| 111 | - **Контактные точки (contact points):** куда отправлять уведомления — Email, Slack, PagerDuty, webhook, Telegram и др. Настройка: Alerting → Contact points; для каждого типа свои параметры (SMTP, URL, токен). Можно проверить отправку (Test). |
| 112 | - **Политики уведомлений (notification policies):** дерево правил маршрутизации алертов. Корневая политика (default) — верх; дочерние политики сопоставляются по меткам (labels) алерта. Операторы: `=`, `!=`, `=~` (regex), `!~`. При срабатывании алерта Grafana проходит по дереву и направляет уведомление в контактные точки тех политик, чьи matchers совпали. В политике задаются: group wait, group interval, repeat interval — как группировать и как часто повторять уведомления. |
| 113 | - **Метки (labels) на правилах алертов:** задаются при создании/редактировании alert rule; по ним политики решают, в какой канал отправить (например критичные — в PagerDuty, остальные — в Slack). **Тишины (silences):** временное отключение уведомлений по меткам (например «все алерты по хосту X на 2 часа»); алерт может оставаться в состоянии firing, но уведомления не отправляются. Документация: Alerting → Configure notifications, Create notification policy. |
| 114 | |
| 115 | --- |
| 116 | |
| 117 | ## 13. Provisioning дашбордов и алертинга |
| 118 | |
| 119 | - **Дашборды и data sources:** задаются YAML/JSON в каталогах, указанных в grafana.ini (provisioning). При старте Grafana загружает их; изменения в UI для provisioned объектов не сохраняются обратно в файлы — правки только в файлах и перезагрузка/деплой. |
| 120 | - **Алертинг:** контактные точки и политики уведомлений можно provision через API или конфиг; при provision через файлы политики по умолчанию становятся **нередактируемыми в UI**. Через API есть способ оставить их редактируемыми; при file-based provisioning — нет. Документация: Provision alerting resources, Set up file provisioning. |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | ## 14. Роли и права (кратко) |
| 125 | |
| 126 | - **Viewer:** только просмотр дашбордов. **Editor:** просмотр и редактирование дашбордов, создание панелей и алертов в пределах своих дашбордов. **Admin:** управление папками, пользователями организации (но не источниками данных). **Organization Admin:** полный доступ, в т.ч. Data Sources, Plugins, Provisioning, настройки организации. Только Organization Admin может добавлять/редактировать data sources. |
| 127 | |
| 128 | --- |
| 129 | |
| 130 | ## 15. Аутентификация: LDAP, OAuth, SSO |
| 131 | |
| 132 | - **LDAP:** вход по учётной записи LDAP/Active Directory. Включается в grafana.ini, задаётся конфиг-файл LDAP (хост, bind, атрибуты пользователя и группы). Опции: allow_sign_up (создавать пользователя при первом входе), skip_org_role_sync (роли задавать вручную в Grafana). Документация: Configure LDAP authentication. |
| 133 | - **OAuth2 / Generic OAuth:** вход через провайдера (Google, GitHub, GitLab, Okta, Keycloak, Entra ID и др.). Generic OAuth — для любого провайдера с поддержкой OAuth2/OpenID Connect. В конфиге указываются URL авторизации, токена, userinfo и маппинг полей. Документация: Configure authentication, Generic OAuth. |
| 134 | - **Единый вход (SSO):** достигается за счёт LDAP или OAuth, когда один провайдер идентичности обслуживает и Grafana, и другие системы. |
| 135 | |
| 136 | --- |
| 137 | |
| 138 | *Источники: официальная документация Grafana (grafana.com/docs). Справочник дополнен: типы data sources (Loki, Tempo, Prometheus, InfluxDB и др.), provisioning дашбордов и алертинга (в т.ч. нередактируемость политик при file provisioning), роли (Viewer/Editor/Admin/Organization Admin), переменные, аннотации, Explore, плагины, контактные точки и политики, LDAP/OAuth — картина от установки до тонких настроек и интеграций.* |
| 139 | |
| 140 | |