BetterDB Monitor

Мониторинговый слой, которого заслуживает Valkey.

BetterDB сохраняет то, что Valkey выбрасывает, — медленные логи, паттерны команд, активность клиентов, сигналы аномалий, — чтобы вы могли разобраться, что произошло в 3 часа ночи, а не только видеть, что происходит сейчас. Создан для Valkey 8.x с нативной поддержкой COMMANDLOG, CLUSTER SLOT-STATS и метрик I/O по потокам. Для всего остального совместим с Redis 6+.

Сайт | Docker Hub | npm | Документация | Блог

BetterDB создан компанией BetterDB Inc. — публичной компанией социальной направленности, действующей в соответствии с OCV Open Charter.

Быстрый старт (Docker)

docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest

Откройте в браузере http://localhost:3001. Для мониторинга конкретного экземпляра:

docker run -d \
  --name betterdb \
  -p 3001:3001 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  betterdb/monitor:latest

Публикуются два варианта образа, оба мультиархитектурные (linux/amd64, linux/arm64):

См. Продакшн-развёртывание в Docker для настройки постоянного хранилища, нестандартных портов, лицензирования и изолированных (air-gapped) окружений.

Быстрый старт (CLI)

Запустите BetterDB Monitor без Docker:

npx @betterdb/monitor

При первом запуске интерактивный мастер настройки проведёт вас через подключение к базе данных, выбор хранилища (SQLite, PostgreSQL или in-memory) и настройки сервера. Конфигурация сохраняется в ~/.betterdb/config.json.

npm install -g @betterdb/monitor   # global install
betterdb --setup                   # re-run setup wizard
betterdb --port 8080               # override server port
betterdb --db-host 1.2.3.4         # override database host
betterdb --help                    # all options

Требуются Node.js >= 20.0.0 и экземпляр Valkey или Redis для мониторинга. Для хранения в SQLite дополнительно выполните npm install -g better-sqlite3.

Что вы получаете

Видите всё, сохраняете всё

• Историческая аналитика — запрашивайте медленные логи, паттерны команд, активность клиентов и задержки за любой временной интервал. Те данные, которые раньше исчезали после ротации логов.
• Поддержка COMMANDLOG — эксклюзивно для Valkey 8.1+. Большие запросы и большие ответы, а не только медленные.
• Сессии захвата MONITOR — записывайте реальный трафик по требованию: живой просмотр (live tail), фильтрация, повторное воспроизведение, экспорт в JSON/CSV и перекрёстная сверка с историей подключений.
• Отслеживание горячих ключей — топ ключей по частоте обращения с изменением позиции с течением времени. Key Analytics (Pro, бесплатно в раннем доступе) добавляет распределения по типам, TTL и размерам на основе живых выборок.
• Видимость кластера — графы топологии, тепловые карты SLOT-STATS, распределение CPU и ключей по слотам.
• Метрики потоков CPU и I/O — видимость по каждому потоку, которую не может дать ни один Redis-инструмент.
• Аналитика клиентов — точно видно, какой сервис за что отвечает, с атрибуцией по имени клиента и паттерну.
• Журнал аудита ACL — отслеживайте, кто и к чему обращался; данные сохраняются для соответствия требованиям и разбора инцидентов.

Понимайте и действуйте

• Обнаружение аномалий (Pro, бесплатно в раннем доступе) — автоматическое обучение базовому уровню с коррелируемыми событиями и диагнозами на простом английском. 20+ детекторов, без ручных порогов.
• Прогнозирование ёмкости — прогнозируемое время достижения потолка по памяти, ops/sec, CPU и фрагментации.
• Вебхуки — доставка алертов с HMAC-подписью, повторами и полным журналом доставки.
• Живая миграция — переход между Redis и Valkey с трёхфазным рабочим процессом: анализ, выполнение и проверка.

Создан для эпохи ИИ

• Наблюдаемость векторного поиска — FT.SEARCH ops/sec и задержки с индикацией здоровья каждого индекса для valkey-search и RediSearch. См. docs/vector-ai.
• Задержка инференса — p50/p95/p99 по каждому индексу с алертами о нарушении SLA (Pro, бесплатно в раннем доступе).
• Аналитика семантического кэша (Pro, бесплатно в раннем доступе) — оценка здоровья hit-rate, рекомендации по порогу схожести и рабочий процесс с предложениями «одобрить/отклонить». Включена наблюдаемость памяти агентов.
• AI-трейсы — OTLP-водопады спанов из вашего AI-приложения, соотнесённые с живым состоянием Valkey под каждым запросом.

Подключается ко всему

• MCP-сервер — 60 инструментов для Claude Code, Cursor или любого MCP-клиента через @betterdb/mcp.
• Prometheus-эндпоинт — 100+ метрик betterdb_*. См. docs/prometheus-metrics.md.
• OpenTelemetry — зеркалируйте метрики и события в любой OTLP-бэкенд.
• REST API — всё, что есть в интерфейсе, является API-вызовом и документировано через OpenAPI.

Доступ к данным — как вам удобно

Примечание: В продакшн-сборках (Docker, CLI) API-маршруты обслуживаются с префиксом /api. В локальной разработке (pnpm dev) префикса нет — например, http://localhost:3001/health.

Поддерживаемые базы данных

Бэкенд использует унифицированный адаптер поверх совместимого по протоколу клиента iovalkey и автоматически определяет Valkey или Redis по ответу INFO (DB_TYPE=auto). Возможности вроде COMMANDLOG и SLOT-STATS определяются по версии, а интерфейс плавно деградирует, когда функция недоступна.

Управляемые сервисы тоже поддерживаются — руководства для AWS ElastiCache, MemoryDB, Redis Cloud и Upstash находятся в docs/providers, а @betterdb/agent подключается к экземплярам, доступным только через VPC, по исходящему WebSocket.

Продакшн-развёртывание в Docker

Docker-образ содержит приложение для мониторинга (бэкенд и фронтенд). Требуются:

1. Экземпляр Valkey/Redis для мониторинга
2. Экземпляр PostgreSQL для хранения данных (или используйте in-memory хранилище)

Запуск с хранилищем PostgreSQL

docker run -d \
  --name betterdb-monitor \
  -p 3001:3001 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  -e STORAGE_TYPE=postgres \
  -e STORAGE_URL=postgresql://user:pass@postgres-host:5432/dbname \
  betterdb/monitor

Запуск на нестандартном порту

Задайте переменную окружения PORT и укажите соответствующее сопоставление -p:

docker run -d \
  --name betterdb-monitor \
  -p 8080:8080 \
  -e PORT=8080 \
  -e DB_HOST=your-valkey-host \
  betterdb/monitor

Запуск с сетью хоста (доступ к сервисам на localhost)

Если ваш Valkey и PostgreSQL работают на одном хосте:

docker run -d \
  --name betterdb-monitor \
  --network host \
  -e DB_HOST=localhost \
  -e DB_PORT=6380 \
  -e DB_PASSWORD=devpassword \
  -e STORAGE_TYPE=postgres \
  -e STORAGE_URL=postgresql://dev:devpass@localhost:5432/postgres \
  betterdb/monitor

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

Полный справочник, включая AI, экспорт OTLP, настройку вебхуков и пороги health-гейтов: docs/configuration.md.

Лицензирование и поддержка изолированных (air-gapped) сред

BetterDB Monitor открывает функции Pro/Enterprise одним из двух способов, в зависимости от того, есть ли у хоста доступ в интернет:

• Онлайн-лицензионный ключ — задайте BETTERDB_LICENSE_KEY. Монитор проверяет его на betterdb.com и кэширует локально проверяемый подписанный токен, поэтому ваш тариф продолжает работать при кратковременных сбоях и перезапусках.
• Офлайн- / автономный лицензионный токен — для хостов вообще без доступа в интернет (см. ниже).

Как работает автономное лицензирование

Каждая лицензия — это подписанный RS256 JWT. Монитор проверяет его локально по публичным ключам, встроенным в образ, — ему никогда не нужно обращаться к лицензионному серверу, чтобы доверять токену. Поэтому изолированный хост может работать на платных тарифах без какого-либо подключения:

1. На машине с доступом в интернет войдите на betterdb.com/account/licenses и скачайте свой офлайн-лицензионный токен (.jwt, Pro/Enterprise). Он не содержит секретов и защищён от подделки — любое изменение нарушит подпись.
2. Перенесите его на изолированный хост любым удобным способом (USB, управление конфигурацией, Docker/Kubernetes secret mount).
3. Укажите его через BETTERDB_OFFLINE_LICENSE_FILE (путь), BETTERDB_OFFLINE_LICENSE (строка) или вставьте в интерфейсе в разделе Settings → License → «Air-gapped environment? Activate an offline license.»

Когда настроен офлайн-токен и не задан BETTERDB_LICENSE_KEY, монитор не выполняет ни одного исходящего запроса — проверки лицензии, телеметрия и пинги обновлений полностью отключены. Он работает на предоставленном тарифе до истечения срока действия токена (бессрочные лицензии обновляются ежегодно), а затем возвращается к Community.

# fully offline - no network required
docker volume create betterdb-data
docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d   # volume writable by UID 1001 (one-time)

docker run -d --name betterdb-monitor -p 3001:3001 \
  -e DB_HOST=your-valkey-host -e DB_PORT=6379 -e DB_PASSWORD=your-password \
  -v /path/to/betterdb-license.jwt:/run/secrets/betterdb-license.jwt:ro \
  -e BETTERDB_OFFLINE_LICENSE_FILE=/run/secrets/betterdb-license.jwt \
  -v betterdb-data:/app/data \
  betterdb/monitor

Проверьте с помощью GET /api/license/status → source: offline-token, mode: offline, airGapped: true.

Постоянное хранение: смонтируйте записываемый том в /app/data, чтобы офлайн-лицензия и онлайн-токен переживания сбоев сохранялись после перезапусков. Контейнер работает под UID 1001, поэтому свежесозданный том должен быть передан ему через chown (показано выше) — иначе сохранение завершится ошибкой EACCES … license.jwt.

Полный процесс, приоритет проверки и сценарий ротации ключей см. в Автономные и изолированные лицензии и Справочник по конфигурации.

Детали Docker-образа

• Базовый образ: node:20-alpine
• Сжатый размер: ~360MB (latest / -no-ai) / ~640MB (версионный образ с зависимостями локальной LLM экспериментального ИИ-помощника)
• Платформы: linux/amd64, linux/arm64
• Содержит: Backend API + статические файлы фронтенда (обслуживаются Fastify)
• Не включает: поддержку SQLite (используйте PostgreSQL или Memory storage)

Операции с контейнером

docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

Хранилища

BetterDB Monitor сохраняет журнал аудита, аналитику, захваты и данные об аномалиях в одно из трёх хранилищ:

Метрики Prometheus

Метрики публикуются на GET /api/prometheus/metrics в текстовом формате Prometheus: аудит ACL, клиентские подключения, паттерны slowlog/commandlog, память, пропускная способность, keyspace, репликация, статистика слотов кластера и метрики рантайма Node.js — все с префиксом betterdb_.

scrape_configs:
  - job_name: 'betterdb-monitor'
    metrics_path: '/api/prometheus/metrics'
    static_configs:
      - targets: ['your-monitor-host:3001']

Полный справочник метрик: docs/prometheus-metrics.md и docs/prometheus-integration.md.

Разработка

Структура проекта

betterdb-monitor/
├── apps/
│   ├── api/                 # NestJS backend (Fastify)
│   └── web/                 # React frontend (Vite)
├── packages/                # Published packages (see below)
├── docs/                    # Documentation site (Jekyll)
├── docker-compose.yml       # Local Valkey (port 6380) and Redis (port 6382) for testing
└── package.json             # Workspace root

Пакеты

В этом монорепозитории распространяется несколько самостоятельных пакетов. Полный список см. в packages/.

Технологический стек

• Бэкенд: NestJS с адаптером Fastify, iovalkey для подключений к Valkey/Redis, строгий режим TypeScript. Порт 3001.
• Фронтенд: React + TypeScript, Vite, TailwindCSS, Recharts. Dev-сервер на порту 5173.
• Монорепозиторий: pnpm workspaces + Turborepo.

Локальная настройка

Предварительные требования: Node.js >= 20.0.0, pnpm >= 9.0.0, Docker.

pnpm install
cp .env.example .env
pnpm docker:dev        # local Valkey (6380) and Redis (6382)
pnpm dev               # web on :5173, api on :3001

Чтобы подключиться к Redis вместо Valkey, задайте DB_PORT=6382 в .env.

pnpm dev:api           # API only
pnpm dev:web           # frontend only
pnpm docker:dev:down   # stop local databases
pnpm build             # production build
pnpm test              # API tests

Сборка Docker-образов:

pnpm docker:build      # local build
pnpm docker:publish    # multi-arch build & push (requires buildx)

Добавление новых функций

1. Добавьте новые эндпоинты в apps/api/src/
2. Добавьте соответствующие API-вызовы в apps/web/src/api/
3. Добавьте общие типы в packages/shared/src/types/

Стиль кода

• Строгий режим TypeScript, явные возвращаемые типы, без any
• Настроены ESLint + Prettier

Лицензия

• Содержимое в docs/ лицензируется по CC BY-SA 4.0.
• Содержимое в proprietary/ покрывается коммерческой лицензией (см. proprietary/LICENSE). Эти функции бесплатны в период раннего доступа.
• Всё остальное — MIT.