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

Then `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, les Secrets apportés par vos soins et les licences hors ligne 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

Requires Node.js >= 20.0.0 et une instance Valkey ou Redis à surveiller. Pour le stockage SQLite, utilisez aussi `npm install -g better-sqlite3`.

## Ce que vous obtenez

### Tout voir, tout conserver

- **Analyses historiques** - interrogez les slowlogs, les schémas de commandes, l'activité des clients et la latence sur n'importe quelle plage temporelle. Les données qui disparaissaient après une rotation des journaux.
- **Prise en charge de COMMANDLOG** - exclusif à Valkey 8.1+. Grandes requêtes et grandes réponses, pas seulement les lentes.
- **Sessions de capture MONITOR** - enregistrez le trafic réel à la demande : suivi en direct, filtrage, relecture, export vers JSON/CSV et recoupement avec l'historique des connexions.
- **Suivi des clés chaudes** - 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** - graphes de topologie, cartes thermiques SLOT-STATS, répartition du CPU et des clés par slot.
- **Métriques CPU et threads d'E/S** - 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 schéma 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 délai avant saturation pour la mémoire, les opérations/s, le CPU et la fragmentation.
- **Webhooks** - livraisons d'alertes signées HMAC avec nouvelles tentatives et journal de livraison complet.
- **Migration en direct** - déplacez-vous entre Redis et Valkey 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 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 dépassement 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 seuils de similarité et flux de travail de propositions 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 sur tout

- **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).
- **Point de terminaison 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 reflétez les métriques et événements vers tout backend OTLP. Voir [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **API REST** - tout dans l'interface 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 jeton sous Paramètres → Jetons MCP |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| API REST (OpenAPI) | `http://localhost:3001/docs` |
| Vérification de santé | `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 ex. `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é sur le client `iovalkey` compatible filaire 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 se dégrade élégamment lorsqu'une fonctionnalité n'est pas disponible.

Les services géré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 VPC-only via 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 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 en écriture 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`é en conséquence (voir 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, voir
**[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** : ~360 Mo (`latest` / `-no-ai`) / ~640 Mo (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** : prise en charge SQLite (utilisez PostgreSQL ou le stockage Memory)

### Opérations du 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 vous 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 points de terminaison 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).