Обзор продукта

Что такое DBWatch PRO и для кого он создан

DBWatch PRO — self-hosted система мониторинга PostgreSQL для команд любого размера. Health Score, анализ запросов, метрики в реальном времени, планирование ресурсов — всё в одном инструменте.

Продукт разработан для DBA, DevOps-инженеров и SRE, которым нужен полный контроль над PostgreSQL-базами данных без зависимости от облачных SaaS-решений. Один Docker-контейнер — и вы получаете профессиональный мониторинг за минуты.

Архитектура

DBWatch PRO — all-in-one Docker-образ со встроенным Nginx, FastAPI backend и агентом сбора метрик. Все данные хранятся локально.

Браузер → :8080 → Nginx
                    ├── /assets/  → статика (React SPA)
                    ├── /api/     → FastAPI backend
                    ├── /ws/      → WebSocket (live метрики)
                    └── /         → SPA routing

Внутри контейнера:
  Supervisor
    ├── nginx (reverse proxy + static)
    ├── backend (FastAPI, порт 8000)
    └── agent (сборщик метрик, каждые 60 сек)

Данные:
  ├── SQLite (metrics.db) — метрики, алерты, инстансы
  └── PostgreSQL — pg_stat_statements, query_stats_history

Стек технологий

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

Минимальные требования для развёртывания DBWatch PRO

Поддерживаемые ОС

DBWatch PRO работает на любой системе с Docker: Linux (Ubuntu, Debian, CentOS, RHEL), macOS, Windows (через WSL2/Docker Desktop). Рекомендуется Linux в production.

Сетевые требования

• Порт 8080 — веб-интерфейс DBWatch PRO (единственный внешний порт)
• Доступ к PostgreSQL-серверу по сети (порт 5432 по умолчанию)

Быстрая установка

Установка DBWatch PRO за 2 минуты

Автоустановка (рекомендуется)

Самый быстрый способ — использовать скрипт автоустановки. Он проверит зависимости, запросит параметры подключения к PostgreSQL, лицензионный ключ и порт — и запустит всё автоматически.

curl -fsSL https://dbwatch.ru/install.sh | sudo bash

Ручная настройка Docker Compose

Если вы хотите настроить конфигурацию вручную — сначала запустите install.sh. Скрипт создаст docker-compose.yml и .env в папке /opt/dbwatch, которые можно отредактировать после установки.

Пример структуры docker-compose.yml:

# /opt/dbwatch/docker-compose.yml
services:
  dbwatch:
    image: ghcr.io/leg1onary/dbwatch-pro:latest
    ports:
      - "8080:8080"
    env_file: .env
    volumes:
      - dbwatch-data:/app/data
    restart: unless-stopped

volumes:
  dbwatch-data:

Первая настройка

Что делать после установки

1. Откройте веб-интерфейс

Перейдите по адресу http://your-host:8080. Если вы установили на локальную машину — http://localhost:8080.

2. Проверьте подключение к PostgreSQL

На странице Overview вы увидите основные метрики базы данных. Если данные отображаются — подключение успешно. Если нет — проверьте PG_DSN в настройках.

3. Настройте API-ключ

Для production-окружения обязательно задайте переменную DBWATCH_API_KEY для защиты API от неавторизованного доступа.

environment:
  PG_DSN: "postgresql://user:password@host:5432/dbname"
  DBWATCH_API_KEY: "your-secure-api-key-here"

4. Настройте уведомления

Перейдите в Settings → Уведомления или укажите переменные окружения для отправки алертов. Подробнее — в разделе Уведомления.

5. Проверьте pg_stat_statements

На странице Settings в блоке PG Extensions проверьте, что расширение pg_stat_statements установлено. Без него раздел «Запросы» будет недоступен.

6. Включите Premium (опционально)

Если у вас есть лицензионный ключ, введите его в Settings → License прямо в UI — без перезапуска контейнера. Premium активирует: Multi-Server (до 50 серверов), EXPLAIN-планы, Index Advisor, Sessions drill-down, Lock Tree, Bloat history, PDF-отчёты, Slack-алерты, история 90 дней. Health Score доступен на всех тарифах включая Standard.

Обновление

Как обновить DBWatch PRO до последней версии

Через install.sh (рекомендуется)

Самый простой способ — перезапустите скрипт установки. Он скачает новый образ, сохранит настройки и перезапустит контейнер:

curl -fsSL https://dbwatch.ru/install.sh | sudo bash

Дашборд (Overview)

Обзор состояния базы данных на одном экране

Live Metrics Banner NEW v0.20.0

Верхняя панель Overview показывает метрики в реальном времени через WebSocket-соединение:

• LIVE-индикатор — пульсирующий зелёный маркер + время последнего фрейма
• CPU / RAM / Connections — текущее значение + мини-sparkline за последние 2 минуты
• TPS — транзакций в секунду в реальном времени
• Авто-реконнект — при обрыве соединения переподключается автоматически

WebSocket endpoint: wss://your-host:8080/ws/metrics. Обновление каждые 2 секунды.

Страница Overview — главный дашборд DBWatch PRO. Здесь отображается общее состояние вашего PostgreSQL-сервера: ключевые метрики, Health Score, количество активных соединений и последние алерты.

Health Score

Метрики на дашборде

• CPU % — текущая загрузка процессора хоста
• RAM % — использование оперативной памяти
• Disk % — занятость диска
• Active Connections — количество активных подключений / max_connections
• Cache Hit Ratio — процент попаданий в кеш PostgreSQL
• QPS — количество запросов в секунду (commits/sec)
• Deadlocks — текущее число дедлоков

Данные обновляются в реальном времени через WebSocket (push каждые 2 секунды). При Premium активирована панель All Instances Health — карточки всех серверов с индивидуальным Health Score.

Интерфейс

• Тёмная и светлая тема — дизайн-система «Obsidian Pulse»
• Полная локализация — русский и английский (686 ключей)
• Адаптивная вёрстка — desktop, tablet, mobile
• Skeleton-загрузки — плавное отображение при загрузке данных

Анализ запросов

pg_stat_statements, медленные запросы, EXPLAIN и Index Advisor

Страница Queries предоставляет полный инструментарий для анализа SQL-запросов вашей базы данных. Данные берутся из расширения pg_stat_statements.

Топ медленных запросов

Таблица показывает медленные запросы с фильтрацией, сортировкой и поиском. Для каждого запроса доступны:

• query — текст SQL-запроса
• calls — количество вызовов
• total_time / avg_time — суммарное и среднее время выполнения
• rows — количество возвращённых строк
• hit_ratio — процент попаданий в буфер
• Severity badges — визуальные индикаторы критичности

Таблица виртуализирована для производительности при 200+ запросах. Через QueryModal можно просмотреть полный SQL с возможностью копирования.

EXPLAIN-планы

Кнопка EXPLAIN на странице Queries позволяет получить план выполнения запроса. Поддерживаются параметризованные запросы через PREPARE/EXPLAIN EXECUTE. Результат отображается в ExplainModal с monospace-форматированием.

Index Advisor

Index Advisor анализирует запросы и индексы, выдавая два типа рекомендаций:

• Missing Index Candidates — запросы, которым не хватает индексов. Анализ pg_stat_statements + pg_index, парсинг FROM/WHERE для определения нужных колонок
• Unused Index Detection — неиспользуемые индексы (idx_scan = 0, size > 8 MB)

Для каждой рекомендации указана severity (high/medium/low) и генерируется готовый SQL:

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_user_id
  ON public.orders (user_id);

Доступны 3 пресета агрессивности: Conservative, Balanced и Aggressive.

История запросов

DBWatch PRO сохраняет снапшоты из pg_stat_statements (топ-100 по total_exec_time), что позволяет отслеживать изменения производительности запросов во времени. Срок хранения настраивается через QUERY_HISTORY_TTL_DAYS (по умолчанию 90 дней).

Query Trends NEW v0.20.0

При клике на любой запрос в списке — над EXPLAIN-планом появляется мини-график тренда:

• Avg time (ms) по дням — визуализация деградации или улучшения запроса
• Диапазон: 1 / 3 / 7 / 14 дней
• Помогает быстро понять: запрос деградировал после деплоя или нарастающий тренд?

Метрики

Реал-тайм мониторинг CPU, RAM, диска и подключений

Страница Metrics показывает детальные графики метрик сервера с возможностью выбора временного диапазона.

Системные метрики

• CPU % — загрузка процессора (psutil)
• RAM % — использование оперативной памяти
• Disk Used % — занятость диска

PostgreSQL-метрики

• Active Connections — активные подключения к БД
• Max Connections — лимит подключений
• Commits/sec (QPS) — количество коммитов в секунду
• Rollbacks — количество откатов
• Cache Hit Ratio — эффективность использования кеша
• Deadlocks — дедлоки
• Active Queries — активные запросы

Временные диапазоны

WebSocket live-обновления

Метрики в реальном времени передаются через WebSocket /ws/live с интервалом push каждые 2 секунды. Данные включают текущие PG-метрики и системные показатели.

Хранение истории

Метрики сохраняются в SQLite (metrics.db) с TTL 30 дней. Агент собирает данные каждые 60 секунд (настраивается через COLLECT_INTERVAL, диапазон 5–3600 сек).

Планирование ресурсов

Прогнозирование загрузки и оценка «дней до заполнения»

Страница Capacity предоставляет прогнозы по ключевым ресурсам на основе линейного тренда.

Отслеживаемые ресурсы

• CPU — тренд %/день, headroom, прогноз дней до критического порога
• RAM — аналогично CPU
• Disk Space — использование по tablespace'ам, линейный прогноз заполнения
• Connections — прогноз достижения лимита подключений

Disk Space Monitoring

Мониторинг дискового пространства включает:

• Текущий процент использования диска
• Размеры по tablespace'ам (pg_default, pg_global и пользовательские)
• Топ таблиц по размеру
• Размеры баз данных
• Прогноз days_until_full — линейный тренд за 7 дней методом наименьших квадратов (минимум 3 точки)

Графики отображают пороговые линии (warning и critical), что позволяет визуально оценить приближение к лимитам.

Мониторинг сессий

Новое в v0.18.0 — полный контроль над соединениями PostgreSQL

Обзор

Страница /sessions показывает все активные соединения к PostgreSQL в реальном времени. Доступна в Standard и Premium тарифах с разным уровнем детализации.

Standard

• Таблица сессий: PID, user, database, application_name, state, duration
• Фильтр по состоянию (active / idle / idle in transaction / aborted)
• Без текста SQL-запросов и без графиков

Premium

• Donut chart — визуальная разбивка по состояниям + progress bar занятости connection pool (total / max_connections)
• Quick Stats — цветные счётчики по каждому состоянию
• Drill-down — клик по строке раскрывает: client_addr, backend_type, wait_event_type, wait_event, query_start, xact_start, полный текст SQL
• Wait Events — агрегация текущих wait events по типу: IO, Lock, LWLock, Client и др.
• История — stacked area chart состояний + bar chart wait event types, диапазон 1 / 3 / 6 / 12 / 24 / 48 часов

API эндпоинты

Lock Tree Premium · NEW v0.19.0

Секция под историей сессий. Визуализирует цепочки блокировок в реальном времени — кто кого блокирует и почему.

• Дерево blocker → waiters — красные карточки для блокирующих процессов, жёлтые для ожидающих
• Узел содержит: PID, user/db, lock_mode badge, duration
• Drill-down по клику: lock_type, relation, wait_event, application_name, полный текст SQL
• Пустое состояние: No blocking queries с зелёным индикатором + кол-во системных блокировок
• Авторефреш каждые 10 секунд — не нужно обновлять страницу вручную

Connection Breakdown Standard · NEW v0.19.1

Секция доступна всем тарифам включая Standard. Показывает детализацию соединений без Premium gate.

• Pool utilization bar — прогресс бар занятости пула; цвет: зелёный → жёлтый при >60% → красный при >80%
• State Donut — donut chart с легендой по состояниям (active / idle / idle in tx / aborted)
• By User / By Database / By Application — горизонтальные bar charts top-10, ширина пропорциональна максимуму в группе
• Авторефреш каждые 15 секунд

Idle-in-Transaction Badge NEW v0.19.1

Индикатор в заголовке страницы Sessions — сразу видно есть ли зависшие транзакции:

• Жёлтый при 1–2 сессиях: показывает кол-во и максимальную duration, например 1 idle in tx (max 42s)
• Красный при 3+ сессиях: сигнал критической ситуации
• Пропадает автоматически когда таких сессий нет

Анализ Bloat

Новое в v0.19.0 — мониторинг раздутия таблиц и индексов PostgreSQL

Обзор

Страница /bloat показывает накопленный bloat в таблицах и индексах. Bloat возникает из-за MVCC — удалённые и обновлённые строки остаются на диске до VACUUM. Большой bloat замедляет запросы и раздувает диск.

Summary Cards

• Total bloat таблиц (MB)
• Total bloat индексов (MB)
• Количество таблиц с bloat
• Количество индексов с bloat

Таблицы и индексы

Две таблицы с сортировкой по любому столбцу (кликабельные заголовки):

• Progress bar для bloat%
• Severity badge: ok (<20%), warning (20–50%), critical (>50%)
• Столбцы: schema, table/index, size, bloat size, bloat%, last vacuum

История

Stacked area chart — тренд bloat в MB за 7 / 14 / 30 / 90 дней. Помогает увидеть когда bloat начал расти и коррелировать с деплоями или нагрузкой.

API эндпоинты

Обслуживание

VACUUM, реплики, блокировки и dead tuples

VACUUM мониторинг

DBWatch PRO отслеживает статистику autovacuum:

• Dead tuples — количество мёртвых строк по таблицам
• Autovacuum статистика — время и частота запусков
• Рекомендации — при накоплении dead tuples или пропуске autovacuum

Replication мониторинг

• Статус реплик — streaming, catchup, потенциальные проблемы
• Replication Lag — отставание реплик по WAL-позициям
• WAL-позиции — текущие позиции мастера и реплик

Управление блокировками

• Активные блокировки — текущие lock'и в системе
• Ожидающие процессы — запросы, заблокированные другими

Multi-Server мониторинг

Управление несколькими PostgreSQL-серверами из одного интерфейса

Возможности

• CRUD инстансов — создание, редактирование, удаление и включение/выключение серверов
• Тест подключения — проверка DSN перед добавлением сервера
• Instance Selector — переключатель серверов, доступный на всех страницах
• Per-instance данные — метрики, алерты, запросы, disk space фильтруются по instance_id
• Health Score per instance — оценка здоровья для каждого сервера

Агент и сбор данных

Агент каждые 60 секунд обновляет список инстансов через GET /api/premium/instances и собирает метрики для каждого enabled-инстанса: PG-метрики, системные показатели, tablespace usage и снапшоты запросов. Все данные сохраняются с привязкой к instance_id.

Лимит серверов

Количество серверов ограничено лицензией (max_servers в JWT-токене). При попытке превысить лимит — HTTP 400.

Алерты

Настраиваемые уведомления о проблемах

Система алертов мониторит ключевые показатели и отправляет уведомления при превышении порогов.

Типы алертов

Каналы уведомлений

• Email (SMTP) — отправка алертов на email через настроенный SMTP-сервер
• Email/Webhook — уведомления через Email и Webhook (Standard и выше)
• Slack — отправка в каналы Slack (Professional и выше)
• Webhook — HTTP POST на произвольный URL (Professional и выше)

Дебаунс и дедупликация

• CPU debounce — CPU critical алерт срабатывает только после N последовательных превышений (cpu_critical_streak, по умолчанию 3)
• Дедупликация — алерт сохраняется в SQLite один раз, пока его ID присутствует в активных
• Acknowledge — подтверждение алертов через UI или API
• История — хранение истории алертов с настраиваемым TTL (по умолчанию 7 дней)

Экспорт данных

Выгрузка метрик и отчётов в CSV и Excel

DBWatch PRO позволяет экспортировать данные мониторинга для дальнейшего анализа или архивирования.

Форматы экспорта

• CSV — универсальный формат для импорта в любые аналитические инструменты
• Excel (.xlsx) — для работы в Microsoft Excel или Google Sheets

Что можно экспортировать

• Историю метрик за выбранный период
• Список медленных запросов с статистикой
• Историю алертов
• Рекомендации Index Advisor

PDF Отчёты

Генерация отчётов о состоянии базы данных

DBWatch PRO генерирует PDF-отчёты с полной информацией о состоянии базы данных — для передачи руководству, аудита или архивирования.

Содержание отчёта

• Health Score и его составляющие
• Графики ключевых метрик за выбранный период
• Топ медленных запросов
• Рекомендации Index Advisor
• Активные алерты и их история
• Информация о дисковом пространстве и прогнозы

Docker Compose конфигурация

Полная конфигурация для production и разработки

Production (all-in-one образ)

Этот docker-compose.yml создаётся автоматически скриптом install.sh. Приведён для справки:

services:
  dbwatch:
    image: ghcr.io/leg1onary/dbwatch-pro:latest
    ports:
      - "8080:8080"
    environment:
      PG_DSN: "postgresql://user:password@host:5432/dbname"
      LICENSE_KEY: ""
      DBWATCH_API_KEY: "your-secure-key"
      COLLECT_INTERVAL: "60"
    volumes:
      - dbwatch-data:/app/data
    restart: unless-stopped
    healthcheck:
      test: curl -f http://localhost:8080/health
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s

volumes:
  dbwatch-data:

Порты

Переменные окружения

Полный справочник переменных для настройки DBWatch PRO

Основные переменные

Email/Webhook и уведомления

Хранение данных

Пороги алертов (настраиваются в Settings UI)

Прочие

Настройка pg_stat_statements

Как включить расширение для анализа запросов

Расширение pg_stat_statements необходимо для работы раздела «Анализ запросов». Без него остальной мониторинг (метрики, алерты, capacity planning) работает в полном объёме.

Шаг 1: Добавьте в postgresql.conf

shared_preload_libraries = 'pg_stat_statements'

Шаг 2: Перезапустите PostgreSQL

sudo systemctl restart postgresql

Шаг 3: Создайте расширение

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Проверка

В DBWatch PRO перейдите в Settings → PG Extensions. Расширение pg_stat_statements должно показывать статус ✓.

Настройка уведомлений

Email и Webhook

Уведомления

Наиболее простой способ получать алерты. Доступен во всех тарифах.

Настройка через UI

1. Создайте бота через @BotFather
2. Получите токен бота и ID чата
3. В DBWatch PRO: Settings → Уведомления
4. Введите токен и Chat ID
5. Нажмите «Send test notification» для проверки

Настройка через переменные окружения

TELEGRAM_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

Email (SMTP)

Настройте SMTP-сервер для отправки email-уведомлений в разделе Settings → Email. Укажите хост, порт, учётные данные и адреса получателей.

Slack

Для интеграции со Slack создайте Incoming Webhook в настройках вашего workspace и укажите URL в настройках DBWatch PRO.

Webhook

Webhook отправляет HTTP POST на указанный URL при каждом новом алерте. Тело запроса содержит JSON с информацией об алерте: тип, severity, сообщение и timestamp.

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

Пороги всех алертов настраиваются через Settings → Alert Thresholds или через API POST /api/settings/thresholds.

Тарифы и лицензирование

Standard, Professional и Enterprise

Активация лицензии

Лицензия активируется через переменную окружения LICENSE_KEY:

LICENSE_KEY=eyJhbGciOiJSUzI1NiIs...

Механизм лицензирования

Лицензия — JWT-токен с подписью RS256. Публичный RSA-ключ вшит в Docker-образ. Проверяются: подпись, issuer (dbwatch-pro), audience (dbwatch-pro-self-hosted), срок действия, tier и max_servers.

UX-граница Standard / Premium

Standard не выглядит как урезанный продукт. Premium-функции обозначены аккуратно:

• Кнопки EXPLAIN — серые с подсказкой «Available in Premium»
• Extended history — кнопки видны, но неактивны с tooltip
• Instance Selector — отображается как «Local / Standard» pill
• Health Score — доступен на всех тарифах

API Reference

40 REST-эндпоинтов + WebSocket. Версия 0.20.1

Аутентификация

Опциональная аутентификация по заголовку X-API-Key:

• Задаётся через переменную окружения DBWATCH_API_KEY
• Если не задана — аутентификация отключена
• При несовпадении → HTTP 403
• GET /health всегда доступен без ключа

Формат ошибок

{
  "detail": "Описание ошибки",
  "code": "VALIDATION_ERROR"
}

Базовый URL

Все эндпоинты доступны по адресу http://your-host:8080. API проксируется через Nginx на /api/.

Системные эндпоинты

Healthcheck, версия, статус лицензии

API Метрики

Реал-тайм и исторические метрики

Пример ответа disk-space

{
  "instance_id": null,
  "summary": {
    "current_percent": 42.5,
    "days_until_full": 127.3
  },
  "tablespaces": [
    {"tablespace": "pg_default", "used_bytes": 1073741824, "used_percent": 12.5},
    {"tablespace": "pg_global", "used_bytes": 524288, "used_percent": 0.1}
  ]
}

API Запросы

Медленные запросы и история

Поля ответа top-slow

API Алерты

Активные алерты, история и подтверждение

API Настройки

Конфигурация мониторинга и пороги алертов

Параметры настроек

API Premium

Multi-server, Health Score, EXPLAIN, Index Advisor

Управление инстансами

Health Score

EXPLAIN

Index Advisor

Часто задаваемые вопросы

FAQ по DBWatch PRO

Changelog

История изменений DBWatch PRO

Дорожная карта

✅ Реализовано (v0.13–v0.19)

• Health Score, метрики, алерты, pg_stat_statements
• EXPLAIN-планы, Index Advisor, Capacity Planning
• Multi-Server, PDF-отчёты, CSV-экспорт
• Command Palette (Cmd+K), Notifications Centre
• Мониторинг сессий, Lock Tree, Wait Events
• Анализ Bloat таблиц и индексов
• Connection Breakdown, Idle-in-tx badge
• Лицензирование UI (activate/deactivate без перезапуска)

Фаза 2 — Продвинутый анализ

• Advanced Index Advisor (JOIN, partial indexes)
• Query Regression Detection — автообнаружение деградации запросов
• Anomaly Detection — ML-based выявление аномалий
• Query groups — группировка похожих запросов

Фаза 3 — Extension-aware мониторинг

• pgvector — index inventory, performance метрики
• TimescaleDB — hypertables, chunks, compression stats
• PostGIS, pg_cron мониторинг

Фаза 4 — Enterprise расширения

• PagerDuty, Opsgenie интеграции
• RBAC + SSO / LDAP
• Audit log export
• Grafana datasource plugin
• Telegram-уведомления