BetterDB Monitor

Die Monitoring-Ebene, die Valkey verdient.

BetterDB bewahrt, was Valkey verwirft – Slowlogs, Befehlsmuster, Client-Aktivität, Anomalie-Signale –, damit Sie debuggen können, was um 3 Uhr morgens passiert ist, und nicht nur, was gerade passiert. Entwickelt für Valkey 8.x mit nativer Unterstützung für COMMANDLOG, CLUSTER SLOT-STATS und Pro-Thread-I/O-Metriken. Redis 6+ kompatibel für alles andere.

Website | Docker Hub | npm | Dokumentation | Blog

BetterDB wird von BetterDB Inc. entwickelt, einem Unternehmen des öffentlichen Nutzens, das unter der OCV Open Charter arbeitet.

Schnellstart (Docker)

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

Öffnen Sie Ihren Browser unter http://localhost:3001. Um eine bestimmte Instanz zu überwachen:

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

Es werden zwei Image-Varianten veröffentlicht, beide Multi-Arch (linux/amd64, linux/arm64):

Siehe Docker-Produktionsbereitstellung für persistenten Speicher, benutzerdefinierte Ports, Lizenzierung und Air-Gapped-Setups.

Schnellstart (CLI)

BetterDB Monitor ohne Docker ausführen:

npx @betterdb/monitor

Beim ersten Start führt Sie ein interaktiver Setup-Assistent durch Datenbankverbindung, Speicher-Backend (SQLite, PostgreSQL oder In-Memory) und Servereinstellungen. Die Konfiguration wird unter ~/.betterdb/config.json gespeichert.

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

Erfordert Node.js >= 20.0.0 und eine zu überwachende Valkey- oder Redis-Instanz. Für SQLite-Speicher zusätzlich npm install -g better-sqlite3.

Was Sie bekommen

Alles sehen, alles behalten

• Historische Analysen – Slowlogs, Befehlsmuster, Client-Aktivität und Latenz über beliebige Zeiträume abfragen. Die Daten, die nach einer Log-Rotation früher verschwanden.
• COMMANDLOG-Unterstützung – exklusiv für Valkey 8.1+. Große Anfragen und große Antworten, nicht nur die langsamen.
• MONITOR-Aufnahmesitzungen – echten Datenverkehr bei Bedarf aufzeichnen: Live-Tail, Filtern, Wiedergabe, Export nach JSON/CSV und Querverweise mit der Verbindungshistorie.
• Hot-Key-Tracking – Top-Keys nach Zugriffshäufigkeit mit Rangbewegung im Zeitverlauf. Key Analytics (Pro, im Early Access kostenlos) ergänzt Typ-, TTL- und Größenverteilungen aus Live-Stichproben.
• Cluster-Sichtbarkeit – Topologiegraphen, SLOT-STATS-Heatmaps, CPU- und Schlüsselverteilung pro Slot.
• CPU- und I/O-Thread-Metriken – Sichtbarkeit pro Thread, die kein Redis-Tool bieten kann.
• Client-Analysen – genau sehen, welcher Dienst wofür verantwortlich ist, zugeordnet nach Client-Name und Muster.
• ACL-Protokollkette – nachvollziehen, wer worauf zugegriffen hat, gespeichert für Compliance und Debugging nach Vorfällen.

Verstehen und handeln

• Anomalieerkennung (Pro, im Early Access kostenlos) – automatisches Baseline-Lernen mit korrelierten Ereignissen und Klartext-Diagnosen. 20+ Detektoren, keine manuellen Schwellwerte.
• Kapazitätsprognose – voraussichtliche Zeit bis zur Obergrenze für Speicher, Ops/Sek., CPU und Fragmentierung.
• Webhooks – HMAC-signierte Alarmzustellungen mit Wiederholungen und vollständigem Zustellungsprotokoll.
• Live-Migration – Wechsel zwischen Redis und Valkey mit einem dreiphasigen Workflow aus Analyse, Ausführung und Validierung.

Gebaut für das KI-Zeitalter

• Vektorsuche-Beobachtbarkeit – FT.SEARCH-Ops/Sek. und Latenz mit Gesundheit pro Index für valkey-search und RediSearch. Siehe docs/vector-ai.
• Inferenz-Latenz – p50/p95/p99 pro Index, mit SLA-Verletzungsalarmen (Pro, im Early Access kostenlos).
• Intelligenz für semantische Caches (Pro, im Early Access kostenlos) – Gesundheit der Trefferquote, Empfehlungen für Ähnlichkeitsschwellen und ein Genehmigen/Ablehnen-Workflow für Vorschläge. Inklusive Beobachtbarkeit des Agentenspeichers.
• KI-Traces – OTLP-Span-Wasserfälle aus Ihrer KI-Anwendung, korreliert mit dem Live-Valkey-Zustand unter jeder Anfrage.

Integriert sich in alles

• MCP-Server – 60 Tools für Claude Code, Cursor oder jeden MCP-Client über @betterdb/mcp.
• Prometheus-Endpunkt – 100+ betterdb_*-Metriken. Siehe docs/prometheus-metrics.md.
• OpenTelemetry – Metriken und Ereignisse an jedes OTLP-Backend spiegeln.
• REST-API – alles in der UI ist ein API-Aufruf, dokumentiert über OpenAPI.

Zugriff auf Ihre Daten nach Ihren Wünschen

Hinweis: In Produktions-Builds (Docker, CLI) werden API-Routen unter dem Präfix /api bereitgestellt. In der lokalen Entwicklung (pnpm dev) gibt es kein Präfix – z. B. http://localhost:3001/health.

Unterstützte Datenbanken

Das Backend verwendet einen einheitlichen Adapter über den drahtkompatiblen iovalkey-Client und erkennt automatisch, ob Valkey oder Redis vorliegt, anhand der INFO-Antwort (DB_TYPE=auto). Funktionen wie COMMANDLOG und SLOT-STATS werden pro Version erkannt, und die UI deaktiviert Funktionen elegant, wenn sie nicht verfügbar sind.

Verwaltete Dienste werden ebenfalls unterstützt – Anleitungen für AWS ElastiCache, MemoryDB, Redis Cloud und Upstash finden Sie in docs/providers, und @betterdb/agent erreicht VPC-only-Instanzen über einen ausgehenden WebSocket.

Docker-Produktionsbereitstellung

Das Docker-Image enthält die Monitoring-Anwendung (Backend + Frontend). Es erfordert:

1. Eine zu überwachende Valkey/Redis-Instanz
2. Eine PostgreSQL-Instanz für die Datenpersistenz (oder Speicher im Arbeitsspeicher)

Mit PostgreSQL-Speicher ausführen

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

Auf benutzerdefiniertem Port ausführen

Setzen Sie die Umgebungsvariable PORT und passen Sie das -p-Mapping an:

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

Mit Host-Netzwerk ausführen (Zugriff auf localhost-Dienste)

Wenn Ihre Valkey- und PostgreSQL-Instanzen auf demselben Host laufen:

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

Umgebungsvariablen

Vollständige Referenz, einschließlich KI, OTLP-Export, Webhook-Konfiguration und Health-Gate-Schwellwerte: docs/configuration.md.

Lizenzierung und Air-Gapped-Unterstützung

BetterDB Monitor schaltet Pro/Enterprise-Funktionen auf eine von zwei Arten frei, je nachdem, ob der Host Internetzugang hat:

• Online-Lizenzschlüssel – setzen Sie BETTERDB_LICENSE_KEY. Der Monitor validiert ihn gegen betterdb.com und speichert ein lokal verifiziertes signiertes Token im Cache, sodass Ihre Stufe auch bei kurzen Ausfällen und Neustarts funktioniert.
• Offline-/Air-Gapped-Lizenz-Token – für Hosts ohne jeglichen Internetzugang (siehe unten).

So funktioniert Air-Gapped-Lizenzierung

Jede Berechtigung ist ein signiertes RS256-JWT. Der Monitor verifiziert es lokal anhand der im Image eingebetteten öffentlichen Schlüssel – er muss nie einen Lizenzserver kontaktieren, um einem Token zu vertrauen. Ein Air-Gapped-Host kann kostenpflichtige Stufen also ohne jegliche Konnektivität ausführen:

1. Melden Sie sich auf einem internetverbundenen Rechner unter betterdb.com/account/licenses an und laden Sie Ihr Offline-Lizenz-Token herunter (.jwt, Pro/Enterprise). Es enthält keine Geheimnisse und kann nicht manipuliert werden – jede Änderung bricht die Signatur.
2. Übertragen Sie es auf beliebigem Weg auf den Air-Gapped-Host (USB, Konfigurationsmanagement, ein Docker/Kubernetes-Secret-Mount).
3. Geben Sie es über BETTERDB_OFFLINE_LICENSE_FILE (Pfad), BETTERDB_OFFLINE_LICENSE (Inline-String) an oder fügen Sie es in der UI unter Einstellungen → Lizenz → „Air-gapped-Umgebung? Offline-Lizenz aktivieren." ein.

Wenn ein Offline-Token konfiguriert ist und kein BETTERDB_LICENSE_KEY gesetzt ist, stellt der Monitor keine ausgehenden Anfragen – Lizenzprüfungen, Telemetrie und Update-Pings sind alle deaktiviert. Er führt die gewährte Stufe aus, bis das Token abläuft (unbefristete Lizenzen werden jährlich neu heruntergeladen), und kehrt dann zu Community zurück.

# 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

Überprüfen Sie mit GET /api/license/status → source: offline-token, mode: offline, airGapped: true.

Persistenz: Binden Sie ein beschreibbares Volume unter /app/data ein, damit die Offline-Lizenz und das Online-Ausfall-Gnaden-Token Neustarts überstehen. Der Container läuft als UID 1001, daher muss ein neu erstelltes Volume ihm chowned werden (wie oben gezeigt) – andernfalls schlägt die Persistenz mit EACCES … license.jwt fehl.

Den vollständigen Ablauf, die Verifizierungsreihenfolge und das Runbook zur Schlüsselrotation finden Sie unter Offline- & Air-Gapped-Lizenzen und der Konfigurationsreferenz.

Docker-Image-Details

• Basis-Image: node:20-alpine
• Komprimierte Größe: ~360MB (latest / -no-ai) / ~640MB (versionsgebundenes Image mit den lokalen-LLM-Abhängigkeiten des experimentellen AI-Helpers)
• Plattformen: linux/amd64, linux/arm64
• Enthält: Backend-API + statische Frontend-Dateien (bereitgestellt von Fastify)
• Ausgeschlossen: SQLite-Unterstützung (PostgreSQL- oder Memory-Speicher verwenden)

Container-Operationen

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

Speicher-Backends

BetterDB Monitor speichert Audit-Trail, Analysen, Aufzeichnungen und Anomaliedaten in einem von drei Backends:

Prometheus-Metriken

Metriken werden unter GET /api/prometheus/metrics im Prometheus-Textformat bereitgestellt: ACL-Audit, Client-Verbindungen, Slowlog-/Commandlog-Muster, Speicher, Durchsatz, Keyspace, Replikation, Cluster-Slot-Statistiken und Node.js-Runtime-Metriken – alle mit dem Präfix betterdb_.

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

Vollständige Metrikreferenz: docs/prometheus-metrics.md und docs/prometheus-integration.md.

Entwicklung

Projektstruktur

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

Pakete

Dieses Monorepo enthält mehrere eigenständige Pakete. Die vollständige Liste finden Sie unter packages/.

Tech-Stack

• Backend: NestJS mit Fastify-Adapter, iovalkey für Valkey/Redis-Verbindungen, TypeScript Strict Mode. Port 3001.
• Frontend: React + TypeScript, Vite, TailwindCSS, Recharts. Dev-Server auf Port 5173.
• Monorepo: pnpm workspaces + Turborepo.

Lokale Einrichtung

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

Um eine Verbindung zu Redis statt Valkey herzustellen, setzen Sie 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

Docker-Image-Builds:

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

Hinzufügen neuer Funktionen

1. Fügen Sie neue Endpunkte in apps/api/src/ hinzu
2. Fügen Sie entsprechende API-Aufrufe in apps/web/src/api/ hinzu
3. Fügen Sie gemeinsame Typen in packages/shared/src/types/ hinzu

Codestil

• TypeScript Strict Mode, explizite Rückgabetypen, kein any
• ESLint + Prettier konfiguriert

Lizenz

• Inhalte unter docs/ sind unter CC BY-SA 4.0 lizenziert.
• Inhalte unter proprietary/ unterliegen einer kommerziellen Lizenz (siehe proprietary/LICENSE). Diese Funktionen sind während des Early Access kostenlos.
• Alles andere ist MIT.