BetterDB Monitor

La couche de supervision que Valkey mérite.

BetterDB persiste ce que Valkey jette - slowlogs, motifs de commandes, activité client, signaux d'anomalie - afin que vous puissiez déboguer ce qui s'est passé à 3 h du matin, pas seulement ce qui se passe maintenant. Conçu pour Valkey 8.x avec prise en charge native de COMMANDLOG, CLUSTER SLOT-STATS et des métriques I/O par thread. Compatible Redis 6+ pour tout le reste.

Site web | Docker Hub | npm | Documentation | Blog

BetterDB est développé par BetterDB Inc., une société à but d'intérêt public opérant sous l'OCV Open Charter.

Démarrage rapide (Docker)

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

Ouvrez votre navigateur sur http://localhost:3001. Pour surveiller une instance spécifique :

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

Deux variantes d'image sont publiées, toutes deux multi-architectures (linux/amd64, linux/arm64) :

Voir Déploiement en production avec Docker pour le stockage persistant, les ports personnalisés, les licences et les configurations air-gapped.

Démarrage rapide (CLI)

Exécutez BetterDB Monitor sans Docker :

npx @betterdb/monitor

Au premier lancement, un assistant de configuration interactif vous guide à travers la connexion à la base de données, le backend de stockage (SQLite, PostgreSQL ou en mémoire) et les paramètres du serveur. La configuration est enregistrée dans ~/.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

Nécessite Node.js >= 20.0.0 et une instance Valkey ou Redis à surveiller. Pour le stockage SQLite, exécutez également npm install -g better-sqlite3.

Ce que vous obtenez

Tout voir, tout conserver

• Analyse historique - interrogez les slowlogs, les motifs de commandes, l'activité client et la latence sur n'importe quelle plage de temps. Les données qui disparaissaient autrefois après une rotation des journaux.
• Prise en charge COMMANDLOG - Exclusif à Valkey 8.1+. Les requêtes et réponses volumineuses, pas seulement les lentes.
• Sessions de capture MONITOR - enregistrez le trafic réel à la demande : suivi en direct, filtrage, relecture, export JSON/CSV et recoupement avec l'historique des connexions.
• Suivi des clés chaudes - clés les plus utilisées par fréquence d'accès avec évolution du classement dans le temps. Key Analytics (Pro, gratuit en accès anticipé) ajoute les distributions de type, de TTL et de taille à partir d'un échantillonnage en direct.
• Visibilité cluster - graphes de topologie, cartes de chaleur SLOT-STATS, répartition CPU et clés par slot.
• Métriques CPU et threads d'E/S - visibilité par thread qu'aucun outil Redis ne peut offrir.
• Analyse client - voyez exactement quel service est responsable de quoi, attribué par nom et motif de client.
• Piste d'audit ACL - suivez qui a accédé à quoi, conservée pour la conformité et le débogage post-incident.

Comprendre et agir

• Détection d'anomalies (Pro, gratuit en accès anticipé) - apprentissage automatique de la ligne de base avec événements corrélés et diagnostics en langage clair. Plus de 20 détecteurs, aucun seuil manuel.
• Prévision de capacité - projection du temps avant plafonnement pour la mémoire, les opérations/s, le CPU et la fragmentation.
• Webhooks - livraison d'alertes signées HMAC avec nouvelles tentatives et journal complet des livraisons.
• Migration en direct - passez de Redis à Valkey (ou l'inverse) avec un flux de travail en trois phases : analyse, exécution et validation.

Conçu pour l'ère de l'IA

• Observabilité de la recherche vectorielle - opérations/s et latence FT.SEARCH avec état de santé par index pour valkey-search et RediSearch. Voir docs/vector-ai.
• Latence d'inférence - p50/p95/p99 par index, avec alertes de dépassement de SLA (Pro, gratuit en accès anticipé).
• Intelligence de cache sémantique (Pro, gratuit en accès anticipé) - état de santé du taux de succès, recommandations de seuil de similarité et flux de travail d'approbation/rejet des propositions. Observabilité de la mémoire des agents incluse.
• Traces IA - cascades de spans OTLP depuis votre application IA, corrélées avec l'état Valkey en direct sous-jacent à chaque requête.

S'intègre à tout

• Serveur MCP - 60 outils pour Claude Code, Cursor, ou tout client MCP via @betterdb/mcp.
• Point de terminaison Prometheus - plus de 100 métriques betterdb_*. Voir docs/prometheus-metrics.md.
• OpenTelemetry - dupliquez les métriques et événements vers n'importe quel backend OTLP.
• API REST - tout ce qui est dans l'interface est un appel API, documenté via OpenAPI.

Accédez à vos données à votre façon

Remarque : Dans les builds de production (Docker, CLI), les routes API sont servies sous le préfixe /api. En développement local (pnpm dev), il n'y a pas de préfixe - par ex. http://localhost:3001/health.

Bases de données prises en charge

Le backend utilise un adaptateur unifié reposant sur le client iovalkey compatible au niveau du protocole et fait la différence entre Valkey et Redis à partir de la réponse INFO (DB_TYPE=auto). Les capacités comme COMMANDLOG et SLOT-STATS sont détectées par version, et l'interface se dégrade élégamment lorsqu'une fonctionnalité n'est pas disponible.

Les services managés sont également pris en charge - des guides pour AWS ElastiCache, MemoryDB, Redis Cloud et Upstash se trouvent dans docs/providers, et @betterdb/agent atteint les instances VPC-only via un WebSocket sortant.

Déploiement en production avec Docker

L'image Docker contient l'application de supervision (backend + frontend). Elle nécessite :

1. Une instance Valkey/Redis à surveiller
2. Une instance PostgreSQL pour la persistance des données (ou utilisez le stockage en mémoire)

Exécution avec stockage 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

Exécution sur un port personnalisé

Définissez la variable d'environnement PORT et faites correspondre le mappage -p :

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

Exécution avec le réseau de l'hôte (accès aux services localhost)

Si votre Valkey et PostgreSQL s'exécutent sur le même hôte :

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

Variables d'environnement

Référence complète, incluant l'IA, l'export OTLP, le réglage des webhooks et les seuils de health-gate : docs/configuration.md.

Licences et prise en charge air-gapped

BetterDB Monitor débloque les fonctionnalités Pro/Enterprise de deux manières, selon que l'hôte dispose ou non d'un accès Internet :

• Clé de licence en ligne - définissez BETTERDB_LICENSE_KEY. Le moniteur la valide auprès de betterdb.com et met en cache un jeton signé vérifié localement, afin que votre offre continue de fonctionner pendant les pannes courtes et les redémarrages.
• Jeton de licence hors ligne / air-gapped - pour les hôtes sans aucun accès Internet (voir ci-dessous).

Comment fonctionne la licence air-gapped

Chaque droit est un JWT RS256 signé. Le moniteur le vérifie localement à l'aide des clés publiques intégrées à l'image - il n'a jamais besoin de contacter un serveur de licences pour faire confiance à un jeton. Ainsi, un hôte air-gapped peut exécuter les offres payantes avec zéro connectivité :

1. Sur une machine connectée à Internet, connectez-vous sur betterdb.com/account/licenses et téléchargez votre jeton de licence hors ligne (.jwt, Pro/Enterprise). Il ne contient aucun secret et ne peut pas être falsifié - toute modification casse la signature.
2. Transférez-le vers l'hôte air-gapped comme vous le souhaitez (USB, gestion de configuration, montage d'un secret Docker/Kubernetes).
3. Fournissez-le via BETTERDB_OFFLINE_LICENSE_FILE (chemin), BETTERDB_OFFLINE_LICENSE (chaîne intégrée), ou collez-le dans l'interface sous Paramètres → Licence → « Environnement air-gapped ? Activer une licence hors ligne. »

Lorsqu'un jeton hors ligne est configuré et qu'aucun BETTERDB_LICENSE_KEY n'est défini, le moniteur n'effectue aucune requête sortante - les vérifications de licence, la télémétrie et les pings de mise à jour sont tous désactivés. Il exécute l'offre accordée jusqu'à l'expiration du jeton (les licences perpétuelles sont re-téléchargées chaque année), puis revient à 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

Vérifiez avec GET /api/license/status → source: offline-token, mode: offline, airGapped: true.

Persistance : montez un volume accessible en écriture sur /app/data afin que la licence hors ligne et le jeton de grâce en ligne pour pannes survivent aux redémarrages. Le conteneur s'exécute en tant qu'UID 1001 ; un volume fraîchement créé doit donc être chowné vers cet UID (comme montré ci-dessus) - sinon la persistance échoue avec EACCES … license.jwt.

Pour le flux complet, la précédence de vérification et le runbook de rotation des clés, consultez Offline & Air-Gapped Licenses et la référence de configuration.

Détails de l'image Docker

• Image de base : node:20-alpine
• Taille compressée : ~360 Mo (latest / -no-ai) / ~640 Mo (image versionnée avec les dépendances LLM locales de l'Assistant IA expérimental)
• Plateformes : linux/amd64, linux/arm64
• Contenu : API backend + fichiers statiques frontend (servis par Fastify)
• Exclus : prise en charge SQLite (utilisez PostgreSQL ou le stockage mémoire)

Opérations du conteneur

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

Backends de stockage

BetterDB Monitor persiste la piste d'audit, les analyses, les captures et les données d'anomalies dans l'un de ces trois backends :

Métriques Prometheus

Les métriques sont exposées sur GET /api/prometheus/metrics au format texte Prometheus : audit ACL, connexions clientes, motifs slowlog/commandlog, mémoire, débit, keyspace, réplication, statistiques des slots de cluster et métriques d'exécution Node.js - toutes préfixées betterdb_.

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

Référence complète des métriques : docs/prometheus-metrics.md et docs/prometheus-integration.md.

Développement

Structure du projet

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

Paquets

Ce monorepo fournit plusieurs paquets autonomes. Voir packages/ pour la liste complète.

Pile technique

• Backend : NestJS avec adaptateur Fastify, iovalkey pour les connexions Valkey/Redis, mode strict TypeScript. Port 3001.
• Frontend : React + TypeScript, Vite, TailwindCSS, Recharts. Serveur de développement sur le port 5173.
• Monorepo : pnpm workspaces + Turborepo.

Installation locale

Prérequis : 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

Pour vous connecter à Redis au lieu de Valkey, définissez DB_PORT=6382 dans .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

Builds d'images Docker :

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

Ajout de nouvelles fonctionnalités

1. Ajoutez de nouveaux endpoints dans apps/api/src/
2. Ajoutez les appels API correspondants dans apps/web/src/api/
3. Ajoutez les types partagés dans packages/shared/src/types/

Style de code

• Mode strict TypeScript, types de retour explicites, pas de any
• ESLint + Prettier configurés

Licence

• Le contenu sous docs/ est sous licence CC BY-SA 4.0.
• Le contenu sous proprietary/ est couvert par une licence commerciale (voir proprietary/LICENSE). Ces fonctionnalités sont gratuites pendant l'accès anticipé.
• Tout le reste est sous licence MIT.