Apri il browser all'indirizzo `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

Poi `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 personalizzati e le licenze 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 dei comandi, attività dei client e latenza su qualsiasi intervallo temporale. I dati che prima scomparivano dopo una rotazione dei log.
- **Supporto COMMANDLOG** - esclusivo di Valkey 8.1+. Richieste e risposte di grandi dimensioni, non solo quelle lente.
- **Sessioni di cattura MONITOR** - registra il traffico reale su richiesta: live tail, filtro, replay, esportazione in JSON/CSV e correlazione incrociata con la cronologia delle connessioni.
- **Tracciamento delle hot key** - chiavi più accedute per frequenza con movimento del rank nel tempo. Key Analytics (Pro, gratuito in early access) aggiunge distribuzioni di tipo, TTL e dimensione dal campionamento live.
- **Visibilità del cluster** - grafi della topologia, heatmap SLOT-STATS, CPU per slot e distribuzione delle chiavi.
- **Metriche dei thread CPU e I/O** - visibilità per thread che nessun tool Redis può fornire.
- **Analisi dei client** - vedi esattamente quale servizio è responsabile di cosa, attribuito per nome e pattern del client.
- **Audit trail ACL** - traccia chi ha acceduto a cosa, persistito per conformità e debug post-incidente.

### Comprendi e agisci

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

### Costruito per l'era dell'AI

- **Osservabilità della ricerca vettoriale** - ops/sec e latenza di FT.SEARCH con stato 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 avvisi di violazione SLA (Pro, gratuito in early access).
- **Intelligenza della cache semantica** (Pro, gratuito in early access) - stato dell'hit-rate, raccomandazioni sulla soglia di similarità e un flusso di lavoro di proposta approva/rifiuta. Osservabilità della memoria dell'agente inclusa.
- **Tracce AI** - waterfall degli span OTLP dalla tua applicazione AI, correlati con lo stato live di Valkey sottostante ogni richiesta. Vedi [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).

### Si integra con tutto

- **Server MCP** - 60 tool per Claude Code, Cursor o qualsiasi client MCP tramite [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Endpoint Prometheus** - oltre 100 metriche `betterdb_*`. Vedi [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - acquisisci tracce OTLP e rispecchia metriche ed eventi verso qualsiasi backend OTLP. Vedi [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **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 Settings → MCP Tokens |
| 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 - ad esempio `http://localhost:3001/health`.

## Database Supportati

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

Il backend utilizza un adapter unificato sul client wire-compatible `iovalkey` e rileva automaticamente Valkey vs Redis dalla risposta `INFO` (`DB_TYPE=auto`). Capacità 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 di Produzione con Docker

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 (oppure usa l'archiviazione in memoria)

### Esecuzione 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 il tuo 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` in modo che la licenza offline e
> il token di tolleranza per interruzioni online sopravvivano ai riavvii. Il container viene eseguito come **UID 1001**,
> quindi un volume appena creato deve essere `chown`ato a tale UID (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)**.

### Docker Image Details

- **Base Image**: `node:20-alpine`
- **Compressed size**: ~360MB (`latest` / `-no-ai`) / ~640MB (versioned image with the experimental AI Helper's local-LLM dependencies)
- **Platforms**: `linux/amd64`, `linux/arm64`
- **Contains**: Backend API + Frontend static files (served by Fastify)
- **Excluded**: SQLite support (use PostgreSQL or Memory storage)

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

Riferimento completo delle 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, impostare `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 chiamate API corrispondenti 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, nessun `any`
- ESLint + Prettier configurati

## Licenza

- Il contenuto sotto `docs/` è concesso in licenza secondo CC BY-SA 4.0.
- Il contenuto sotto `proprietary/` è coperto 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).