Pointez votre navigateur vers `http://localhost:3001`. Pour surveiller une instance spécifique :```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

Puis `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` et ouvrez `http://localhost:3001`, ou activez l'ingress du chart. L'historique basé sur PostgreSQL, l'apport de vos propres Secrets et la licence en environnement isolé sont tous couverts dans le [guide Kubernetes](https://docs.betterdb.com/kubernetes) et le [README du chart](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md).

## Démarrage rapide (CLI)

Exécutez BetterDB Monitor sans Docker :```bash
npx @betterdb/monitor

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

- **Analyses historiques** - interrogez les slowlogs, les modèles de commandes, l'activité des clients et la latence sur n'importe quelle plage temporelle. Les données qui disparaissaient auparavant après une rotation des logs.
- **Prise en charge de COMMANDLOG** - exclusivité Valkey 8.1+. Les requêtes volumineuses et les réponses volumineuses, pas seulement les lentes.
- **Sessions de capture MONITOR** - enregistrez le trafic réel à la demande : suivi en direct, filtrage, rejeu, export au format JSON/CSV et recoupement avec l'historique des connexions.
- **Suivi des hot keys** - principales clés 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, TTL et taille à partir d'un échantillonnage en direct.
- **Visibilité du cluster** - graphiques de topologie, heatmaps SLOT-STATS, CPU par slot et distribution des clés.
- **Métriques des threads CPU et I/O** - visibilité par thread qu'aucun outil Redis ne peut fournir.
- **Analyses des clients** - voyez exactement quel service est responsable de quoi, attribué par nom et modèle de client.
- **Piste d'audit ACL** - suivez qui a accédé à quoi, conservé 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, sans seuils manuels.
- **Prévision de capacité** - temps projeté avant saturation pour la mémoire, les ops/sec, le CPU et la fragmentation.
- **Webhooks** - livraisons d'alertes signées HMAC avec nouvelles tentatives et journal complet des livraisons.
- **Migration à chaud** - passez de Redis à Valkey avec un workflow en trois phases : analyse, exécution et validation.

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

- **Observabilité de la recherche vectorielle** - ops/sec et latence de FT.SEARCH avec santé par index pour [valkey-search](https://github.com/valkey-io/valkey-search) et RediSearch. Voir [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **Latence d'inférence** - p50/p95/p99 par index, avec alertes de violation de SLA (Pro, gratuit en accès anticipé).
- **Intelligence du cache sémantique** (Pro, gratuit en accès anticipé) - santé du taux de succès, recommandations de seuil de similarité et workflow de proposition approuver/rejeter. 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 chaque requête. Voir [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).

### Se branche partout

- **Serveur MCP** - 60 outils pour Claude Code, Cursor ou tout client MCP via [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Endpoint Prometheus** - plus de 100 métriques `betterdb_*`. Voir [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - ingérez des traces OTLP et répliquez les métriques et événements vers n'importe quel backend OTLP. Voir [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **API REST** - tout dans l'interface utilisateur est un appel API, documenté via OpenAPI.

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

| Interface | Détails |
|-----------|---------|
| Interface web | `http://localhost:3001` |
| Serveur MCP | `npx @betterdb/mcp` (stdio) - créez un token sous Settings → MCP Tokens (requis sur le cloud, facultatif en auto-hébergé) |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| API REST (OpenAPI) | `http://localhost:3001/docs` |
| Vérification de l'état | `http://localhost:3001/api/health` |

> **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 exemple `http://localhost:3001/health`.

## Bases de données prises en charge

| Base de données | Version minimale | Fonctionnalités prises en charge |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Toutes les fonctionnalités, y compris COMMANDLOG (8.1+) et CLUSTER SLOT-STATS |
| **Redis** | 6+ | Toutes les fonctionnalités sauf COMMANDLOG et CLUSTER SLOT-STATS, exclusifs à Valkey |

Le backend utilise un adaptateur unifié au-dessus du client `iovalkey` compatible au niveau du protocole et détecte automatiquement Valkey vs 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 utilisateur se dégrade gracieusement 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](https://github.com/betterdb-inc/monitor/blob/master/docs/providers), et [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) atteint les instances uniquement accessibles via VPC par le biais d'un WebSocket sortant.

## Déploiement Docker en production

L'image Docker contient l'application de surveillance (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```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

### Exécuter avec le réseau de l'hôte (accéder aux services localhost)

Si votre Valkey et PostgreSQL s'exécutent sur le même hôte :```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

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

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

Pour le flux complet, la priorité de vérification et le runbook de rotation des clés, consultez
**[Licences hors ligne et air-gapped](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** et la
**[Référence de configuration](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.

### Détails de l'image Docker

- **Image de base** : `node:20-alpine`
- **Taille compressée** : ~360MB (`latest` / `-no-ai`) / ~640MB (image versionnée avec les dépendances LLM locales de l'AI Helper expérimental)
- **Plateformes** : `linux/amd64`, `linux/arm64`
- **Contient** : API backend + fichiers statiques frontend (servis par Fastify)
- **Exclu** : Support SQLite (utilisez PostgreSQL ou le stockage Memory)

### Opérations sur le conteneur```bash
docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

Référence complète des métriques : [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) et [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/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

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

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