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

Что такое 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 по умолчанию)
• Для Telegram-уведомлений — доступ к api.telegram.org

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

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

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

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

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

Ручная установка через Docker Compose

Создайте файл docker-compose.yml:

# docker-compose.yml
services:
  dbwatch:
    image: ghcr.io/leg1onary/dbwatch-pro:latest
    ports:
      - "8080:8080"
    environment:
      PG_DSN: "postgresql://user:password@host:5432/dbname"
      LICENSE_KEY: ""  # Пустой = Standard (бесплатный)
    volumes:
      - dbwatch-data:/app/data
    restart: unless-stopped

volumes:
  dbwatch-data:

Запустите контейнер:

docker compose up -d
# Откройте http://localhost:8080

Установка из исходников

Для разработки или кастомизации:

git clone https://github.com/Leg1onary/dbwatch-pro.git
cd dbwatch-pro
cp backend/.env.example backend/.env
# Отредактируйте PG_DSN в backend/.env
docker compose up -d --build

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

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

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 → Telegram или укажите переменные окружения для отправки алертов. Подробнее — в разделе Уведомления.

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

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

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

Если у вас есть лицензионный ключ, добавьте его в переменную LICENSE_KEY и перезапустите контейнер. Это активирует Multi-Server, Health Score, EXPLAIN-планы и Index Advisor.

Обновление

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

Docker-образ (production)

docker compose pull
docker compose up -d

Из исходников

git pull
docker compose up -d --build

Дашборд (Overview)

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

Страница 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 дней).

Метрики

Реал-тайм мониторинг 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), что позволяет визуально оценить приближение к лимитам.

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

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-сервер
• Telegram — уведомления в чат через бота (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 образ)

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:

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

# docker-compose.yml (development)
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      PG_DSN: "postgresql://postgres:postgres@postgres:5432/postgres"
    volumes:
      - backend-data:/app/data
      - ./backend/.env:/app/backend/.env:ro
    healthcheck:
      test: curl -f http://localhost:8000/health
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s

  agent:
    build:
      context: ./backend
      dockerfile: Dockerfile.agent
    volumes:
      - backend-data:/app/data
      - ./backend/.env:/app/backend/.env:ro
    depends_on:
      backend:
        condition: service_healthy

  frontend:
    build: ./frontend
    ports:
      - "8080:8080"
    depends_on:
      backend:
        condition: service_healthy

  postgres:
    image: postgres:16
    ports:
      - "5433:5432"
    environment:
      POSTGRES_PASSWORD: postgres
    volumes:
      - pg-data:/var/lib/postgresql/data

  postgres_replica:
    image: postgres:16
    ports:
      - "5434:5432"
    environment:
      POSTGRES_PASSWORD: postgres
    volumes:
      - pg-replica-data:/var/lib/postgresql/data

volumes:
  backend-data:
  pg-data:
  pg-replica-data:

Порты

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

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

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

Telegram и уведомления

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

Прочие

Настройка 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 должно показывать статус ✓.

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

Telegram, Email, Slack и Webhook

Telegram

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

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

1. Создайте бота через @BotFather
2. Получите токен бота и ID чата
3. В DBWatch PRO: Settings → Telegram
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

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

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

Опциональная аутентификация по заголовку 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

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

Фаза 2 — Расширенный анализ

• Advanced Index Advisor (JOIN, partial indexes)
• Query Regression Detection
• Vacuum & XID Monitoring

Фаза 3 — Extension-aware Monitoring

• pgvector (index inventory, performance)
• TimescaleDB (hypertables, chunks)
• PostGIS, pg_cron

Фаза 4 — Integrations & Enterprise

• Slack, PagerDuty, Opsgenie, Webhooks
• RBAC + SSO
• Audit log export
• Grafana datasource plugin