Punta il browser su `http://localhost:3001`. Per monitorare un'istanza specifica:```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

Allora `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` e apri `http://localhost:3001`, oppure abilita l'ingress del chart. La cronologia basata su PostgreSQL, i Secrets portati da te e la licenza air-gapped sono tutti trattati nella [guida Kubernetes](https://docs.betterdb.com/kubernetes) e nel [README del chart](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md).

## Avvio rapido (CLI)

Esegui BetterDB Monitor senza Docker:```bash
npx @betterdb/monitor

Richiede Node.js >= 20.0.0 e un'istanza Valkey o Redis da monitorare. Per l'archiviazione SQLite, anche `npm install -g better-sqlite3`.

## Cosa Ottieni

### Vedi tutto, conserva tutto

- **Analisi storiche** - interroga slowlog, pattern di comandi, attività dei client e latenza su qualsiasi intervallo di tempo. I dati che sparivano dopo una rotazione dei log.
- **Supporto COMMANDLOG** - esclusivo di Valkey 8.1+. Richieste grandi e risposte grandi, non solo quelle lente.
- **Sessioni di cattura MONITOR** - registra il traffico reale su richiesta: live tail, filtro, replay, esportazione in JSON/CSV e confronto incrociato con la cronologia delle connessioni.
- **Tracciamento delle hot key** - chiavi principali per frequenza di accesso con movimento del ranking nel tempo. Key Analytics (Pro, gratuito in early access) aggiunge distribuzioni di tipo, TTL e dimensione dal campionamento live.
- **Visibilità del cluster** - grafici di topologia, heatmap SLOT-STATS, distribuzione di CPU e chiavi per slot.
- **Metriche CPU e thread I/O** - visibilità per thread che nessuno strumento Redis può fornire.
- **Analisi dei client** - vedi esattamente quale servizio è responsabile di cosa, attribuito per nome client e pattern.
- **Trail di audit ACL** - traccia chi ha acceduto a cosa, persistito per conformità e debug post-incidente.

### Comprendi e agisci

- **Rilevamento anomalie** (Pro, gratuito in early access) - apprendimento automatico della baseline con eventi correlati e diagnosi in linguaggio semplice. Più di 20 rilevatori, nessuna soglia manuale.
- **Previsione della capacità** - tempo previsto fino al limite per memoria, ops/sec, CPU e frammentazione.
- **Webhook** - consegne di alert firmate HMAC con retry e log di consegna completo.
- **Migrazione live** - spostati tra Redis e Valkey con un flusso di lavoro in tre fasi: analisi, esecuzione e validazione.

### Progettato per l'era dell'AI

- **Osservabilità della ricerca vettoriale** - ops/sec e latenza FT.SEARCH con salute per indice per [valkey-search](https://github.com/valkey-io/valkey-search) e RediSearch. Vedi [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **Latenza di inferenza** - p50/p95/p99 per indice, con alert di violazione SLA (Pro, gratuito in early access).
- **Intelligenza della cache semantica** (Pro, gratuito in early access) - salute del tasso di hit, raccomandazioni sulla soglia di similarità e flusso di lavoro di proposte approva/rifiuta. Osservabilità della memoria dell'agente inclusa.
- **Trace AI** - waterfall di span OTLP dalla tua applicazione AI, correlati con lo stato live di Valkey sotto ogni richiesta.

### Si integra con tutto

- **Server MCP** - 60 strumenti per Claude Code, Cursor o qualsiasi client MCP tramite [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Endpoint Prometheus** - più di 100 metriche `betterdb_*`. Vedi [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - rispecchia metriche ed eventi verso qualsiasi backend OTLP.
- **API REST** - tutto nella UI è una chiamata API, documentata tramite OpenAPI.

## Accedi ai Tuoi Dati a Modo Tuo

| Interfaccia | Dettagli |
|-----------|---------|
| Web UI | `http://localhost:3001` |
| Server MCP | `npx @betterdb/mcp` (stdio) - crea un token in Impostazioni → Token MCP |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| API REST (OpenAPI) | `http://localhost:3001/docs` |
| Health check | `http://localhost:3001/api/health` |

> **Nota**: Nelle build di produzione (Docker, CLI) le route API sono servite sotto il prefisso `/api`. Nello sviluppo locale (`pnpm dev`) non c'è prefisso - es. `http://localhost:3001/health`.

## Database Supportati

| Database | Versione Minima | Funzionalità Supportate |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Tutte le funzionalità inclusi COMMANDLOG (8.1+) e CLUSTER SLOT-STATS |
| **Redis** | 6+ | Tutte le funzionalità tranne COMMANDLOG e CLUSTER SLOT-STATS esclusivi di Valkey |

Il backend usa un adapter unificato sul client `iovalkey` compatibile via wire e rileva automaticamente Valkey vs Redis dalla risposta `INFO` (`DB_TYPE=auto`). Funzionalità come COMMANDLOG e SLOT-STATS vengono rilevate per versione, e la UI degrada con grazia quando una funzionalità non è disponibile.

Anche i servizi gestiti sono supportati - guide per AWS ElastiCache, MemoryDB, Redis Cloud e Upstash si trovano in [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers), e [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) raggiunge istanze solo-VPC tramite un WebSocket in uscita.

## Deployment Docker in Produzione

L'immagine Docker contiene l'applicazione di monitoraggio (backend + frontend). Richiede:
1. Un'istanza Valkey/Redis da monitorare
2. Un'istanza PostgreSQL per la persistenza dei dati (o usa l'archiviazione in memoria)

### Esegui con Archiviazione 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

### Esecuzione con rete host (accesso ai servizi localhost)

Se Valkey e PostgreSQL sono in esecuzione sullo stesso host:```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

Verifica con `GET /api/license/status` → `source: offline-token`, `mode: offline`,
`airGapped: true`.

> **Persistenza:** monta un volume scrivibile su `/app/data` così che la licenza offline e
> il token di tolleranza per le interruzioni online sopravvivano ai riavvii. Il container viene eseguito come **UID 1001**,
> quindi un volume appena creato deve essere `chown`ato a tale utente (come mostrato sopra) - altrimenti
> la persistenza fallisce con `EACCES … license.jwt`.

Per il flusso completo, la precedenza di verifica e il runbook di rotazione delle chiavi, consulta
**[Offline & Air-Gapped Licenses](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** e il
**[Configuration reference](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.

### Dettagli dell'Immagine Docker

- **Immagine Base**: `node:20-alpine`
- **Dimensione compressa**: ~360MB (`latest` / `-no-ai`) / ~640MB (immagine versionata con le dipendenze LLM locali dell'AI Helper sperimentale)
- **Piattaforme**: `linux/amd64`, `linux/arm64`
- **Contiene**: API Backend + file statici del Frontend (serviti da Fastify)
- **Escluso**: supporto SQLite (usa PostgreSQL o archiviazione Memory)

### Operazioni sul Container```bash
docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

Riferimento completo alle metriche: [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) e [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-integration.md).

## Sviluppo

### Struttura del Progetto```
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

Per connettersi a Redis invece di Valkey, imposta `DB_PORT=6382` in `.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

### Aggiunta di Nuove Funzionalità

1. Aggiungi nuovi endpoint in `apps/api/src/`
2. Aggiungi le corrispondenti chiamate API in `apps/web/src/api/`
3. Aggiungi i tipi condivisi in `packages/shared/src/types/`

### Stile del Codice

- TypeScript in modalità strict, tipi di ritorno espliciti, niente `any`
- ESLint + Prettier configurati

## Licenza

- I contenuti in `docs/` sono concessi in licenza CC BY-SA 4.0.
- I contenuti in `proprietary/` sono coperti da una licenza commerciale (vedi `proprietary/LICENSE`). Queste funzionalità sono gratuite durante l'accesso anticipato.
- Tutto il resto è [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).