mroot/grafana_gen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
grafana_gen/README.md
Magnus Root 692fa563e1 Work version
2026-02-24 12:45:35 +03:00

11 KiB
Raw Blame History

grafana_gen — Руководство пользователя

Утилита автоматически генерирует дашборды Grafana на основе данных из PostgreSQL. При каждом запуске она читает список клиентов и их ресурсов из БД, сравнивает с предыдущим состоянием и пересоздаёт единый дашборд только при наличии изменений.

Как это работает

PostgreSQL (test_info)
        ↓
  Список клиентов и ресурсов (SID, domain_name, aliases)
        ↓
  Проверка изменений (state.json)
        ↓  нет изменений → выход
  Загрузка шаблона (dashboard_template.json из Git)
        ↓
  Генерация JSON дашборда
        ↓
  Grafana API → создание/обновление дашборда

На каждый запуск создаётся один дашборд со всеми клиентами. Каждый клиент отображается как свёрнутая строка (collapsed row), внутри которой — панели по каждому ресурсу.

Требования

  • Go 1.21+
  • PostgreSQL с базой test_info
  • Grafana с API-доступом (Service Account Token или Legacy API Key)
  • Git (для загрузки шаблонов)
  • Доступ к Gitea-репозиторию с шаблоном

Установка и запуск

Сборка

git clone <репозиторий утилиты>
cd grafana_gen
go build -o grafana_gen .

Первый запуск

./grafana_gen \
  -grafana-url https://grafana.example.com \
  -grafana-api-key glsa_xxxxxxxxxxxx \
  -db-user waf_reader \
  -db-password secret

Через .env файл (рекомендуется)

Создайте файл /etc/grafana_gen/grafana_gen.env:

GRAFANA_URL=https://grafana.example.com
GRAFANA_API_KEY=glsa_xxxxxxxxxxxx
DB_USER=waf_reader
DB_PASSWORD=secret
GIT_TOKEN=your-gitea-token

Затем просто:

./grafana_gen

Конфигурация

Способы задать параметры (в порядке приоритета)

Приоритет Способ Пример
1 Флаг командной строки -grafana-url https://...
2 Переменная окружения export GRAFANA_URL=https://...
3 .env файл GRAFANA_URL=https://...
4 Константа в config.go DefaultGrafanaURL = "https://..."

Пути поиска .env файла

Утилита ищет .env файл в следующем порядке:

  1. Путь из переменной GRAFANA_GEN_ENV_FILE
  2. /etc/grafana_gen/grafana_gen.env
  3. ./grafana_gen.env (рядом с бинарником)
  4. ./.env

Флаги командной строки

База данных

Флаг Переменная окружения По умолчанию Описание
-db-host — 10.100.10.8 Хост PostgreSQL
-db-port — 5432 Порт PostgreSQL
-db-user DB_USER — Пользователь БД (обязательно)
-db-password DB_PASSWORD — Пароль БД (обязательно)
-db-name — test_info Имя базы данных
-use-manual — false Использовать таблицу manual_info вместо sp_info

Grafana

Флаг Переменная окружения По умолчанию Описание
-grafana-url GRAFANA_URL — URL Grafana (обязательно)
-grafana-api-key GRAFANA_API_KEY — API-ключ Grafana (обязательно)
-grafana-folder GRAFANA_FOLDER WAF - Auto Generated Папка в Grafana для дашборда
-dashboard-title DASHBOARD_TITLE PT AF Nodes Название дашборда

Git / шаблоны

Флаг Переменная окружения По умолчанию Описание
-git-token GIT_TOKEN — Токен доступа к Gitea
-templates-repo — (см. config.go) URL Git-репозитория с шаблонами
-templates-branch — master Ветка репозитория
-templates-path — /etc/grafana_gen/templates Локальный путь для шаблонов
-skip-git-pull — false Не обновлять шаблоны из Git

Управление запуском

Флаг По умолчанию Описание
-dry-run false Сгенерировать JSON, но не отправлять в Grafana
-force false Принудительная регенерация даже без изменений
-state-file /var/lib/grafana_gen/state.json Путь к файлу состояния

Приоритет параметров

Пример: если одновременно задан флаг -grafana-api-key, переменная GRAFANA_API_KEY и значение в .env — используется флаг командной строки как наиболее приоритетный.

Флаг CLI  >  Переменная окружения  >  .env файл  >  константа в config.go

Это позволяет безопасно хранить секреты в .env и при необходимости переопределять их на лету без изменения файлов.

State-файл

Утилита сохраняет состояние после каждого успешного запуска в JSON-файл (по умолчанию /var/lib/grafana_gen/state.json).

При следующем запуске сравниваются:

  • Коммит шаблона в Git
  • Версия шаблона (version в dashboard_template.json)
  • SHA-256 хэш данных из БД (список клиентов, доменов, SID)
  • Количество клиентов и доменов

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

=== No Changes Detected ===
No changes in templates or database since last run.
Skipping dashboard generation.

Use -force flag to regenerate anyway.

Если изменения есть — выводится подробный отчёт:

=== Changes Detected ===
Changes detected:
  Template commit changed: abc12345 -> def67890
  Database content changed
    - New SIDs: [SID_001, SID_002]

Режим dry-run

Позволяет проверить что будет сгенерировано без отправки в Grafana:

./grafana_gen -dry-run

В лог выводится превью JSON дашборда и итоговая статистика:

DRY RUN: Dashboard generated but not sent to Grafana
=== Summary ===
Clients: 12
Skipped: 0

Запуск через cron

Рекомендуемый вариант — запуск каждые 15 минут:

*/15 * * * * /usr/local/bin/grafana_gen >> /var/log/grafana_gen.log 2>&1

Утилита сама определяет нужно ли обновлять дашборд — частые запуски без изменений завершаются мгновенно.

Systemd timer (альтернатива)

/etc/systemd/system/grafana-gen.service:

[Unit]
Description=Grafana Dashboard Generator
After=network.target postgresql.service

[Service]
Type=oneshot
EnvironmentFile=/etc/grafana_gen/grafana_gen.env
ExecStart=/usr/local/bin/grafana_gen
StandardOutput=journal
StandardError=journal

/etc/systemd/system/grafana-gen.timer:

[Unit]
Description=Run grafana-gen every 15 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min

[Install]
WantedBy=timers.target

systemctl enable --now grafana-gen.timer

Типичные сценарии

Первое развёртывание

# 1. Создать .env
cp grafana_gen.env.example /etc/grafana_gen/grafana_gen.env
vim /etc/grafana_gen/grafana_gen.env

# 2. Проверить без отправки
./grafana_gen -dry-run

# 3. Создать дашборд
./grafana_gen

Принудительное обновление после изменения шаблона

./grafana_gen -force

Переключение на резервную БД

./grafana_gen -db-host 10.10.10.5

Тестирование с другим шаблоном

./grafana_gen \
  -templates-path /tmp/my-templates \
  -skip-git-pull \
  -dry-run

Использование таблицы ручного ввода

./grafana_gen -use-manual

Структура БД

Утилита читает данные из двух таблиц базы test_info.

Таблица sp_info (основная)

Колонка Тип Описание
sid text Идентификатор ресурса
domain_name text Доменное имя
aliases jsonb JSON-массив дополнительных доменов

Таблица apps_settings (справочник клиентов)

Колонка Тип Описание
l7resourceid text SID ресурса (связь с sp_info.sid)
client_title text Название клиента

Если client_title не найден — клиент группируется под именем Unknown.

Таблица manual_info имеет ту же структуру, что и sp_info, и используется при флаге -use-manual для ручного управления данными без изменения основной таблицы.

Файловая система

/etc/grafana_gen/
├── grafana_gen.env          # Конфигурация (секреты)
└── templates/               # Клонированный Git-репозиторий с шаблонами
    └── dashboard_template.json

/var/lib/grafana_gen/
└── state.json               # Состояние последнего запуска

/usr/local/bin/
└── grafana_gen              # Бинарник утилиты

Права доступа

# Директории
install -d -m 755 /etc/grafana_gen
install -d -m 755 /var/lib/grafana_gen

# .env файл — только для владельца процесса
chmod 600 /etc/grafana_gen/grafana_gen.env