Направьте браузер на `http://localhost:3001`. Чтобы отслеживать конкретный экземпляр:```bash
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

Тогда выполните `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` и откройте `http://localhost:3001`, либо включите ingress в чарте. История на базе PostgreSQL, собственные Secrets и лицензирование в изолированной сети описаны в [руководстве по Kubernetes](https://docs.betterdb.com/kubernetes) и [README чарта](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md).

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

Запустите BetterDB Monitor без Docker:```bash
npx @betterdb/monitor

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

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

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

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

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

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

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

- **Наблюдаемость векторного поиска** — операции/сек и задержки FT.SEARCH с проверкой здоровья по каждому индексу для [valkey-search](https://github.com/valkey-io/valkey-search) и RediSearch. См. [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **Задержка инференса** — p50/p95/p99 по каждому индексу с оповещениями о нарушении SLA (Pro, бесплатно в раннем доступе).
- **Интеллект семантического кэша** (Pro, бесплатно в раннем доступе) — проверка здоровья коэффициента попаданий, рекомендации по порогам схожести и рабочий процесс предложений с одобрением/отклонением. Включает наблюдаемость памяти агента.
- **Трассировки ИИ** — водопадные диаграммы спанов OTLP из вашего ИИ-приложения, коррелируемые с живым состоянием Valkey под каждым запросом. См. [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).

### Интегрируется со всем

- **MCP-сервер** — 60 инструментов для Claude Code, Cursor или любого MCP-клиента через [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Конечная точка Prometheus** — более 100 метрик `betterdb_*`. См. [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** — приём OTLP-трассировок, зеркалирование метрик и событий в любой OTLP-бэкенд. См. [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **REST API** — всё в интерфейсе является вызовом API, документировано через OpenAPI.

## Доступ к данным на ваш выбор

| Интерфейс | Подробности |
|-----------|-------------|
| Веб-интерфейс | `http://localhost:3001` |
| MCP-сервер | `npx @betterdb/mcp` (stdio) — создайте токен в разделе Настройки → MCP Tokens |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| REST API (OpenAPI) | `http://localhost:3001/docs` |
| Проверка состояния | `http://localhost:3001/api/health` |

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

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

| База данных | Минимальная версия | Поддерживаемые функции |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Все функции, включая COMMANDLOG (8.1+) и CLUSTER SLOT-STATS |
| **Redis** | 6+ | Все функции, кроме эксклюзивных для Valkey COMMANDLOG и CLUSTER SLOT-STATS |

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

Управляемые сервисы также поддерживаются — руководства для AWS ElastiCache, MemoryDB, Redis Cloud и Upstash находятся в [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers), а [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) подключается к экземплярам, доступным только через VPC, по исходящему WebSocket.

## Развёртывание в Docker для продакшена

Образ Docker содержит приложение для мониторинга (бэкенд + фронтенд). Он требует:
1. Экземпляр Valkey/Redis для мониторинга
2. Экземпляр PostgreSQL для хранения данных (или используйте хранение в памяти)

### Запуск с хранением в PostgreSQL```bash
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

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

Если ваш Valkey и PostgreSQL работают на одном хосте:```bash
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

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

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

Полный процесс, порядок приоритета проверки и инструкцию по ротации ключей см. в
**[Offline & Air-Gapped Licenses](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** и
**[Configuration reference](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.

### Сведения об образе Docker

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

### Операции с контейнером```bash
docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

Полная справка по метрикам: [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) и [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/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

Чтобы подключиться к Redis вместо Valkey, задайте `DB_PORT=6382` в файле `.env`.```bash
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

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

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](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).