BetterDB Monitor

Il livello di monitoraggio che Valkey merita.

BetterDB conserva ciò che Valkey scarta - slowlog, pattern di comandi, attività dei client, segnali di anomalie - così puoi eseguire il debug di ciò che è accaduto alle 3 di notte, non solo di ciò che sta accadendo ora. Progettato per Valkey 8.x con supporto nativo per COMMANDLOG, CLUSTER SLOT-STATS e metriche I/O per thread. Compatibile con Redis 6+ per tutto il resto.

Sito web | Docker Hub | npm | Documentazione | Blog

BetterDB è sviluppato da BetterDB Inc., una società a beneficio pubblico che opera secondo l'OCV Open Charter.

Quick Start (Docker)

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

Apri il browser all'indirizzo http://localhost:3001. Per monitorare un'istanza specifica:

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

Sono disponibili due varianti di immagine, entrambe multi-arch (linux/amd64, linux/arm64):

Vedi Docker Production Deployment per storage persistente, porte personalizzate, licenze e configurazioni air-gapped.

Quick Start (CLI)

Esegui BetterDB Monitor senza Docker:

npx @betterdb/monitor

Al primo avvio, una procedura guidata interattiva ti accompagna attraverso la connessione al database, il backend di storage (SQLite, PostgreSQL o in-memory) e le impostazioni del server. La configurazione viene salvata in ~/.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

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

Cosa Ottieni

Vedi tutto, conserva tutto

• Analisi storica - interroga slowlog, pattern di comandi, attività dei client e latenza su qualsiasi intervallo di tempo. I dati che prima sparivano dopo una rotazione dei log.
• Supporto COMMANDLOG - esclusivo di Valkey 8.1+. Grandi richieste e grandi risposte, non solo quelle lente.
• Sessioni di cattura MONITOR - registra il traffico reale su richiesta: coda live, filtro, replay, esportazione in JSON/CSV e riferimento incrociato con la cronologia delle connessioni.
• Tracciamento delle hot key - chiavi principali per frequenza di accesso con movimento in classifica 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, mappe di calore SLOT-STATS, CPU per slot e distribuzione delle chiavi.
• Metriche dei thread CPU e 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.
• Traccia di audit ACL - traccia chi ha avuto accesso a cosa, persistita 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 per il raggiungimento del tetto per memoria, ops/sec, CPU e frammentazione.
• Webhook - consegna di avvisi firmati HMAC con tentativi e registro 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 di FT.SEARCH con salute per indice per valkey-search e RediSearch. Vedi docs/vector-ai.
• 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) - salute del tasso di hit, raccomandazioni sulla soglia di similarità e un flusso di lavoro di proposte approva/rifiuta. Osservabilità della memoria dell'agente inclusa.
• Tracce AI - waterfall di span OTLP dalla tua applicazione AI, correlati con lo stato live di Valkey alla base di ogni richiesta.

Si integra con tutto

• Server MCP - 60 strumenti per Claude Code, Cursor o qualsiasi client MCP tramite @betterdb/mcp.
• Endpoint Prometheus - oltre 100 metriche betterdb_*. Vedi docs/prometheus-metrics.md.
• OpenTelemetry - rispecchia metriche ed eventi verso qualsiasi backend OTLP.
• API REST - tutto nell'interfaccia è una chiamata API, documentata tramite OpenAPI.

Accedi ai tuoi dati a modo tuo

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

Database Supportati

Il backend utilizza un adapter unificato sul client iovalkey compatibile a livello di protocollo e rileva automaticamente Valkey vs Redis dalla risposta INFO (DB_TYPE=auto). Funzionalità come COMMANDLOG e SLOT-STATS vengono rilevate in base alla versione e l'interfaccia utente si degrada in modo elegante quando una funzionalità non è disponibile.

Anche i servizi gestiti sono supportati - le guide per AWS ElastiCache, MemoryDB, Redis Cloud e Upstash si trovano in docs/providers e @betterdb/agent raggiunge le istanze solo-VPC tramite un WebSocket in uscita.

Docker Production Deployment

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 lo storage in memoria)

Run with PostgreSQL Storage

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

Run on Custom Port

Imposta la variabile d'ambiente PORT e fai corrispondere il mapping -p:

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

Run with Host Network (Access localhost services)

Se Valkey e PostgreSQL sono in esecuzione sullo stesso host:

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

Variabili d'ambiente

Riferimento completo, inclusi AI, esportazione OTLP, regolazione dei webhook e soglie dei health gate: docs/configuration.md.

Licensing & Air-Gapped Support

BetterDB Monitor sblocca le funzionalità Pro/Enterprise in uno dei due modi seguenti, a seconda che l'host abbia accesso a Internet:

• Chiave di licenza online - imposta BETTERDB_LICENSE_KEY. Il monitor la valida verso betterdb.com e memorizza nella cache un token firmato verificato localmente, così il tuo piano continua a funzionare attraverso brevi interruzioni e riavvii.
• Token di licenza offline / air-gapped - per host con nessun accesso a Internet (vedi sotto).

Come funziona la licenza air-gapped

Ogni diritto è un JWT RS256 firmato. Il monitor lo verifica localmente tramite le chiavi pubbliche incorporate nell'immagine - non deve mai contattare un server di licenza per fidarsi di un token. Quindi un host air-gapped può eseguire i piani a pagamento con zero connettività:

1. Su una macchina connessa a Internet, accedi a betterdb.com/account/licenses e scarica il tuo token di licenza offline (.jwt, Pro/Enterprise). Non contiene segreti e non può essere alterato - qualsiasi modifica rompe la firma.
2. Trasferiscilo sull'host air-gapped come preferisci (USB, gestione della configurazione, un mount di secret Docker/Kubernetes).
3. Forniscilo tramite BETTERDB_OFFLINE_LICENSE_FILE (percorso), BETTERDB_OFFLINE_LICENSE (stringa inline) oppure incollalo nell'interfaccia in Impostazioni → Licenza → "Ambiente air-gapped? Attiva una licenza offline."

Quando è configurato un token offline e nessuna BETTERDB_LICENSE_KEY è impostata, il monitor effettua zero richieste in uscita - controlli della licenza, telemetria e ping di aggiornamento sono tutti disabilitati. Esegue il piano concesso fino alla scadenza del token (le licenze perpetue vengono riscaricate ogni anno), poi torna alla 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

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

Persistenza: monta un volume scrivibile in /app/data così la licenza offline e il token di grazia per le interruzioni online sopravvivono ai riavvii. Il container viene eseguito come UID 1001, quindi un volume appena creato deve essere chownato a tale utente (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, vedi Licenze offline e air-gapped e il Riferimento di configurazione.

Dettagli dell'immagine Docker

• Immagine base: node:20-alpine
• Dimensione compressa: ~360MB (latest / -no-ai) / ~640MB (immagine versionata con le dipendenze local-LLM 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 storage in memoria)

Operazioni sul container

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

Backend di storage

BetterDB Monitor salva la traccia di audit, le analisi, le catture e i dati sulle anomalie in uno dei tre backend:

Metriche Prometheus

Le metriche sono esposte su GET /api/prometheus/metrics nel formato testo di Prometheus: audit ACL, connessioni client, pattern slowlog/commandlog, memoria, throughput, keyspace, replica, statistiche degli slot del cluster e metriche di runtime Node.js - tutte con prefisso betterdb_.

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

Riferimento completo delle metriche: docs/prometheus-metrics.md e 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

Pacchetti

Questo monorepo include diversi pacchetti standalone. Vedi packages/ per l'elenco completo.

Stack tecnologico

• Backend: NestJS con adapter Fastify, iovalkey per le connessioni Valkey/Redis, TypeScript in modalità strict. Porta 3001.
• Frontend: React + TypeScript, Vite, TailwindCSS, Recharts. Server di sviluppo sulla porta 5173.
• Monorepo: pnpm workspaces + Turborepo.

Configurazione locale

Prerequisiti: 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

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

Build delle immagini Docker:

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

Aggiungere 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 sotto CC BY-SA 4.0.
• I contenuti in proprietary/ sono coperti da una licenza commerciale (vedi proprietary/LICENSE). Queste funzionalità sono gratuite durante l'early access.
• Tutto il resto è MIT.