betterdb-inc/monitorEchtzeit-Überwachung und Slowlog-Analyse für Valkey- und Redis-Datenbanken mit Anomalieerkennung, ACL-Auditierung und Prometheus-Metrikenexport.
# BetterDB Monitor
[](https://hub.docker.com/r/betterdb/monitor)
[](https://hub.docker.com/r/betterdb/monitor/tags)
[](https://artifacthub.io/packages/search?repo=betterdb-monitor)
[](https://www.npmjs.com/package/@betterdb/monitor)
[](https://www.npmjs.com/package/@betterdb/monitor)
[](https://github.com/betterdb-inc/monitor/actions/workflows/api-tests.yml)
[](LICENSE)
[](https://valkey.io)
[](https://redis.io)
**Die Monitoring-Schicht, die Valkey verdient.**
BetterDB persistiert, was Valkey verwirft – Slowlogs, Befehlsmuster, Client-Aktivität, Anomaliesignale – damit du debuggen kannst, was um 3 Uhr morgens passiert ist, und nicht nur, was gerade jetzt passiert. Entwickelt für Valkey 8.x mit nativer Unterstützung für COMMANDLOG, CLUSTER SLOT-STATS und I/O-Metriken pro Thread. Redis 6+ kompatibel für alles andere.
[Website](https://betterdb.com) | [Docker Hub](https://hub.docker.com/r/betterdb/monitor) | [npm](https://www.npmjs.com/package/@betterdb/monitor) | [Dokumentation](https://docs.betterdb.com) | [Blog](https://betterdb.com/blog)
BetterDB wird von [BetterDB Inc.](https://betterdb.com) entwickelt, einem gemeinnützigen Unternehmen, das unter der [OCV Open Charter](https://github.com/OpenCoreVentures/ocv-public-benefit-company) operiert.
## Schnellstart (Docker)
```bash
docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest
```
Richten Sie Ihren Browser auf `http://localhost:3001`. Um eine bestimmte Instanz zu überwachen:
```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
```
> **Verbindung zu einer Datenbank auf Ihrem Host-Rechner herstellen?** Innerhalb des Containers
> ist `localhost` der Container selbst, nicht Ihr Host — verwenden Sie daher
> `host.docker.internal` als Datenbank-Host. Auf **Docker Desktop
> (macOS/Windows)** funktioniert dies ohne weitere Konfiguration; unter **Linux** fügen Sie
> `--add-host=host.docker.internal:host-gateway` zum `docker run`-Befehl hinzu, damit
> der Name aufgelöst wird. Die Ein-Klick-Schaltfläche „Mit lokaler Instanz verbinden“ im Dashboard
> erkennt dies automatisch und füllt den richtigen Host für Sie vor.
Es werden zwei Image-Varianten veröffentlicht, beide Multi-Arch (`linux/amd64`, `linux/arm64`):
| Tag | Was es ist |
|-----|------------|
| `latest`, `X.Y.Z-no-ai` | Standard-Image – alle Monitoring-Funktionen enthalten, ohne die Abhängigkeiten für den experimentellen lokalen LLM AI Helper |
| `X.Y.Z` | Fügt den experimentellen AI Helper hinzu (eigenes Ollama mitbringen; standardmäßig deaktiviert über `AI_ENABLED`) |
Siehe [Docker Production Deployment](#docker-production-deployment) für persistenten Speicher, benutzerdefinierte Ports, Lizenzierung und Air-Gapped-Setups.
## Schnellstart (Kubernetes / Helm)
```bash
helm repo add betterdb https://docs.betterdb.com/charts
helm repo update
helm install betterdb-monitor betterdb/betterdb-monitor \
--namespace betterdb --create-namespace \
--set db.host=my-valkey.default.svc.cluster.local \
--set db.password=yourpassword
```
Dann `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` und öffne `http://localhost:3001`, oder aktiviere das Ingress des Charts. PostgreSQL-gestützte Historie, eigene Secrets und Air-Gapped-Lizenzierung werden im [Kubernetes-Leitfaden](https://docs.betterdb.com/kubernetes) und der [Chart-README](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md) behandelt.
## Schnellstart (CLI)
Führe BetterDB Monitor ohne Docker aus:
```bash
npx @betterdb/monitor
```
Beim ersten Start führt Sie ein interaktiver Einrichtungsassistent durch die Datenbankverbindung, das Speicher-Backend (SQLite, PostgreSQL oder In-Memory) und die Servereinstellungen. Die Konfiguration wird in `~/.betterdb/config.json` gespeichert.
```bash
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-Speicherung zusätzlich `npm install -g better-sqlite3`.
## Was Sie erhalten
### Alles sehen, alles behalten
- **Historische Analysen** - Slowlogs, Befehlsmuster, Client-Aktivität und Latenz über jeden Zeitraum abfragen. Die Daten, die früher nach einer Log-Rotation verschwunden sind.
- **COMMANDLOG-Unterstützung** - exklusiv für Valkey 8.1+. Große Anfragen und große Antworten, nicht nur die langsamen.
- **MONITOR-Aufzeichnungssitzungen** - echten Datenverkehr bei Bedarf aufzeichnen: Live-Tail, Filter, Replay, Export nach JSON/CSV und Abgleich mit der Verbindungshistorie.
- **Hot-Key-Tracking** - Top-Keys nach Zugriffshäufigkeit mit Rangverschiebung über die Zeit. Key Analytics (Pro, in der Early-Access-Phase kostenlos) ergänzt Typ-, TTL- und Größenverteilungen aus Live-Sampling.
- **Cluster-Sichtbarkeit** - Topologie-Graphen, SLOT-STATS-Heatmaps, CPU- und Key-Verteilung pro Slot.
- **Automatische Cluster-Registrierung** - eine Cluster-Verbindung kann jeden Knoten automatisch als eigene überwachte Verbindung registrieren, synchron gehalten, während der Cluster skaliert. Siehe [docs/cluster-auto-registration.md](https://github.com/betterdb-inc/monitor/blob/master/docs/cluster-auto-registration.md).
- **CPU- & 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-Audit-Trail** - nachverfolgen, wer worauf zugegriffen hat, persistiert für Compliance und Post-Incident-Debugging.
### Verstehen und handeln
- **Anomalieerkennung** (Pro, in der Early-Access-Phase kostenlos) - automatisches Baseline-Lernen mit korrelierten Ereignissen und Diagnosen in verständlicher Sprache. Über 20 Detektoren, keine manuellen Schwellenwerte.
- **Kapazitätsprognose** - prognostizierte Zeit bis zum Erreichen der Obergrenze für Speicher, Ops/Sek., CPU und Fragmentierung.
- **Webhooks** - HMAC-signierte Alert-Zustellungen mit Wiederholungsversuchen und vollständigem Zustellungsprotokoll.
- **Live-Migration** - Wechsel zwischen Redis und Valkey mit einem dreiphasigen Workflow aus Analyse, Ausführung und Validierung.
### Gebaut für die KI-Ära
- **Vektor-Suche-Observability** - FT.SEARCH Ops/Sek. und Latenz mit Index-Health pro Index für [valkey-search](https://github.com/valkey-io/valkey-search) und RediSearch. Siehe [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **Inferenzlatenz** - p50/p95/p99 pro Index, mit SLA-Verletzungsalarmen (Pro, in der Early-Access-Phase kostenlos).
- **Semantische Cache-Intelligenz** (Pro, in der Early-Access-Phase kostenlos) - Hit-Rate-Health, Empfehlungen für Ähnlichkeitsschwellenwerte und ein Genehmigen/Ablehnen-Vorschlagsworkflow. Agent-Memory-Observability inklusive.
- **KI-Traces** - OTLP-Span-Wasserfälle aus Ihrer KI-Anwendung, korreliert mit dem Live-Valkey-Zustand unter jeder Anfrage. Siehe [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
### Lässt sich überall integrieren
- **MCP-Server** - 60 Tools für Claude Code, Cursor oder jeden MCP-Client über [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Prometheus-Endpunkt** - über 100 `betterdb_*`-Metriken. Siehe [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - OTLP-Traces aufnehmen und Metriken und Ereignisse an jedes OTLP-Backend spiegeln. Siehe [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **REST-API** - alles in der UI ist ein API-Aufruf, dokumentiert via OpenAPI.
## Greifen Sie auf Ihre Daten zu, wie Sie möchten
| Schnittstelle | Details |
|-----------|---------|
| Web-UI | `http://localhost:3001` |
| MCP-Server | `npx @betterdb/mcp` (stdio) - erstellen Sie ein Token unter Settings → MCP Tokens (erforderlich in der Cloud, optional bei Self-Hosting) |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| REST-API (OpenAPI) | `http://localhost:3001/docs` |
| Health-Check | `http://localhost:3001/api/health` |
> **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
| Datenbank | Mindestversion | Unterstützte Funktionen |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Alle Funktionen einschließlich COMMANDLOG (8.1+) und CLUSTER SLOT-STATS |
| **Redis** | 6+ | Alle Funktionen außer dem Valkey-exklusiven COMMANDLOG und CLUSTER SLOT-STATS |
Das Backend verwendet einen einheitlichen Adapter über den wire-kompatiblen `iovalkey`-Client und erkennt Valkey vs. Redis automatisch aus der `INFO`-Antwort (`DB_TYPE=auto`). Fähigkeiten wie COMMANDLOG und SLOT-STATS werden pro Version erkannt, und die UI degradiert gracefully, wenn eine Funktion nicht verfügbar ist.
Managed Services werden ebenfalls unterstützt - Anleitungen für AWS ElastiCache, MemoryDB, Redis Cloud und Upstash finden Sie in [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers), und [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/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 verwenden Sie Speicher-Storage)
### Ausführen mit PostgreSQL-Speicherung
```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
```
### Ausführung auf benutzerdefiniertem Port
Legen Sie die Umgebungsvariable `PORT` fest und passen Sie die `-p`-Zuordnung an:
```bash
docker run -d \
--name betterdb-monitor \
-p 8080:8080 \
-e PORT=8080 \
-e DB_HOST=your-valkey-host \
betterdb/monitor
```
### Ausführung mit Host-Netzwerk (Zugriff auf localhost-Dienste)
Wenn Valkey und PostgreSQL auf demselben Host laufen:
```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
```
### Umgebungsvariablen
| Variable | Erforderlich | Standard | Beschreibung |
|----------|----------|---------|-------------|
| `DB_HOST` | Ja | `localhost` | Zu überwachender Valkey/Redis-Host |
| `DB_PORT` | Nein | `6379` | Valkey/Redis-Port |
| `DB_PASSWORD` | Nein | - | Valkey/Redis-Passwort |
| `DB_USERNAME` | Nein | `default` | Valkey/Redis-ACL-Benutzername |
| `DB_TYPE` | Nein | `auto` | Datenbanktyp: `auto`, `valkey` oder `redis` |
| `DB_TLS` | Nein | `false` | Auf `true` setzen, um sich mit der überwachten Datenbank über TLS zu verbinden (erforderlich bei Managed-Anbietern wie Aiven oder ElastiCache Serverless) |
| `STORAGE_TYPE` | Nein | `memory` | Storage-Backend: `memory` oder `postgres` |
| `STORAGE_URL` | Bedingt | - | PostgreSQL-Verbindungs-URL (erforderlich, wenn `STORAGE_TYPE=postgres`) |
| `STORAGE_SSL_CA` | Nein | - | Pfad (oder vertrauenswürdige HTTPS-URL) zu einem CA-Zertifikat, das zur Verifizierung des PostgreSQL-Servers verwendet wird. Bei Managed-Anbietern mit eigener CA (z. B. Aiven) hier die Projekt-CA angeben für vollständige Chain- und Hostname-Verifizierung. Hat Vorrang vor `STORAGE_SSL_NO_VERIFY` |
| `STORAGE_SSL_NO_VERIFY` | Nein | `false` | Verbindung zu PostgreSQL über TLS **ohne** Verifizierung des Serverzertifikats (verschlüsselt, aber nicht authentifiziert). Praktisch für Managed-Anbieter, die ihre eigene CA präsentieren und `sslmode=require` erzwingen, wenn `STORAGE_SSL_CA` nicht bereitgestellt werden kann. In der Produktion `STORAGE_SSL_CA` bevorzugen |
| `PORT` | Nein | `3001` | HTTP-Port der Anwendung |
| `NODE_ENV` | Nein | `production` | Node-Umgebung |
| `ANOMALY_DETECTION_ENABLED` | Nein | `true` | Anomalieerkennung aktivieren |
| `ANOMALY_PROMETHEUS_INTERVAL_MS` | Nein | `30000` | Aktualisierungsintervall der Prometheus-Zusammenfassung (ms) |
| `BETTERDB_LICENSE_KEY` | Nein | - | Online-Lizenzschlüssel (Pro/Enterprise), wird über das Netzwerk validiert |
| `BETTERDB_OFFLINE_LICENSE_FILE` | Nein | - | Pfad zu einer signierten Offline-Lizenz `.jwt` für **air-gapped** Hosts (siehe unten) |
| `BETTERDB_OFFLINE_LICENSE` | Nein | - | Offline-Lizenz-Token als Inline-JWT-String |
| `BETTERDB_DATA_DIR` | Nein | `/app/data` | Verzeichnis für persistierten Lizenzstatus (beschreibbares Volume einbinden) |
| `ENCRYPTION_KEY` | Nein | - | Schlüssel (min. 16 Zeichen) zur Envelope-Verschlüsselung gespeicherter Verbindungspasswörter und SSH-Tunnel-Geheimnisse im Ruhezustand. Ohne ihn werden Geheimnisse im Klartext gespeichert |
| `BETTERDB_SSH_KEY_DIR` | Nein | - | Verzeichnis, in dem serverseitige SSH-Private-Keys liegen müssen. Aktiviert die Key-Quelle „Server-Dateipfad" für [SSH-Tunnel](#ssh-tunnels); der Key-Pfad einer Verbindung muss darin aufgelöst werden. Nicht gesetzt deaktiviert dateibasierte Keys (inline eingefügte Keys funktionieren weiterhin) |
| `BETTERDB_TELEMETRY` | Nein | `true` | Auf `false` setzen, um anonyme Telemetrie zu deaktivieren |
Vollständige Referenz, einschließlich KI-, Webhook-Tuning und Health-Gate-Schwellenwerten: [docs/configuration.md](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md). Für OTLP-Trace-Ingest und Metrik-/Event-Export siehe [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
### SSH-Tunnel
Verbindungen können eine Datenbank über einen SSH-Bastion-/Jump-Host erreichen, anstatt sich direkt zu verbinden — nützlich für Valkey/Redis in einem privaten Subnetz, ElastiCache oder MemoryDB. Beim Hinzufügen einer Verbindung **Connect via SSH tunnel** aktivieren und SSH-Host, Port und Benutzername angeben. Ein einzelner Hop wird unterstützt.
Die Authentifizierung erfolgt entweder über ein Passwort oder einen Private Key. Private Keys stammen aus einer von zwei Quellen:
- **Key einfügen** (inline): Der PEM-Key-Inhalt wird mit der Verbindung übermittelt. Er wird **nur dann verschlüsselt im Ruhezustand gespeichert, wenn `ENCRYPTION_KEY` gesetzt ist** (Envelope-Verschlüsselung); ohne diesen Schlüssel wird er im Klartext gespeichert, wie Verbindungspasswörter. Funktioniert überall, einschließlich Managed-/Cloud-Deployments.
- **Server-Dateipfad**: Der Key liegt bereits im Dateisystem des Monitor-Servers und wird per Pfad referenziert. Dies erfordert das Setzen der Umgebungsvariable `BETTERDB_SSH_KEY_DIR` auf das Verzeichnis, das die erlaubten Keys enthält, und der referenzierte Pfad muss darin aufgelöst werden, sodass die API niemals dazu gebracht werden kann, beliebige Dateien zu lesen. `BETTERDB_SSH_KEY_DIR` nicht gesetzt lassen, um diese Option zu deaktivieren.
Optional den **Host-Key-Fingerprint** des SSH-Servers (`SHA256:...`) an der Verbindung festnageln; wenn gesetzt, wird der Tunnel abgelehnt, es sei denn, der Server präsentiert einen passenden Key, was Man-in-the-Middle-Angriffe auf dem Bastion-Pfad verhindert. Leer gelassen wird die Serveridentität nicht verifiziert (eine Warnung wird protokolliert).
Der Tunnel leitet über `127.0.0.1` an die Datenbank weiter; wenn TLS aktiviert ist, wird das Zertifikat weiterhin gegen den echten Datenbank-Hostnamen validiert. `ENCRYPTION_KEY` setzen, damit SSH-Passwörter, Key-Passphrasen und Inline-Keys im Ruhezustand verschlüsselt sind.
**Bekannte Einschränkung — Cluster-/Sentinel-Topologien:** Nur die von Ihnen konfigurierte Verbindung wird getunnelt. Cluster- und Sentinel-Überwachung fächert sich zu den anderen Knoten auf, wobei die Adressen verwendet werden, die diese Knoten bekanntgeben (`CLUSTER NODES` / Sentinel), und diese Verbindungen pro Knoten werden direkt hergestellt, nicht durch den Tunnel. Wenn die anderen Knoten nur über die Bastion erreichbar sind (z. B. ElastiCache/MemoryDB in einem privaten Subnetz), sind Ansichten pro Knoten nicht verfügbar. SSH-Tunnel für Single-Node-/Primary-Überwachung verwenden oder den Monitor dort platzieren, wo er die Cluster-Knoten direkt erreichen kann.
### Lizenzierung & 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** - `BETTERDB_LICENSE_KEY` setzen. Der Monitor validiert ihn
gegen `betterdb.com` und cached ein lokal verifiziertes **signiertes Token**, sodass Ihr
Tier auch bei kurzen Ausfällen und Neustarts weiter funktioniert.
- **Offline-/Air-Gapped-Lizenz-Token** - für Hosts mit **überhaupt keinem Internetzugang**
(siehe unten).
#### Wie Air-Gapped-Lizenzierung funktioniert
Jede Berechtigung ist ein **signiertes RS256-JWT**. Der Monitor verifiziert es **lokal**
gegen öffentliche Schlüssel, die im Image eingebettet sind - er muss niemals einen Lizenzserver
erreichen, um einem Token zu vertrauen. So kann ein Air-Gapped-Host kostenpflichtige Tiers ohne
jegliche Konnektivität ausführen:
1. Auf einer internetverbundenen Maschine bei
[betterdb.com/account/licenses](https://www.betterdb.com/account/licenses) anmelden und
**Ihr Offline-Lizenz-Token herunterladen** (`.jwt`, Pro/Enterprise). Es enthält keine
Geheimnisse und kann nicht manipuliert werden - jede Änderung bricht die Signatur.
2. Es auf den Air-Gapped-Host übertragen, wie auch immer Sie möchten (USB, Konfigurationsmanagement, ein
Docker/Kubernetes-Secret-Mount).
3. Es über `BETTERDB_OFFLINE_LICENSE_FILE` (Pfad), `BETTERDB_OFFLINE_LICENSE`
(Inline-String) bereitstellen oder in der UI unter **Settings → License → "Air-gapped
environment? Activate an offline license."** einfügen.
Wenn ein Offline-Token konfiguriert ist und **kein** `BETTERDB_LICENSE_KEY` gesetzt ist,
führt der Monitor **keine ausgehenden Anfragen** aus - Lizenzprüfungen, Telemetrie und Update-
Pings sind alle deaktiviert. Er führt das gewährte Tier aus, bis das Token abläuft (perpetuale
Lizenzen werden jährlich neu heruntergeladen), und fällt dann auf Community zurück.
```bash
# 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
```
Verifiziere mit `GET /api/license/status` → `source: offline-token`, `mode: offline`,
`airGapped: true`.
> **Persistenz:** Binde ein beschreibbares Volume unter `/app/data` ein, damit die Offline-Lizenz und
> das Online-Ausfall-Toleranz-Token Neustarts überleben. Der Container läuft als **UID 1001**,
> daher muss ein neu erstelltes Volume mit `chown` an diese UID übergeben werden (wie oben gezeigt) – andernfalls
> schlägt die Persistenz mit `EACCES … license.jwt` fehl.
Für den vollständigen Ablauf, die Verifizierungsreihenfolge und das Runbook zur Schlüsselrotation siehe
**[Offline- & Air-Gapped-Lizenzen](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** und die
**[Konfigurationsreferenz](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.
### Docker-Image-Details
- **Basis-Image**: `node:20-alpine`
- **Komprimierte Größe**: ~360MB (`latest` / `-no-ai`) / ~640MB (versioniertes Image mit den lokalen LLM-Abhängigkeiten des experimentellen AI Helpers)
- **Plattformen**: `linux/amd64`, `linux/arm64`
- **Enthält**: Backend-API + Frontend-Statikdateien (bereitgestellt von Fastify)
- **Ausgeschlossen**: SQLite-Unterstützung (verwende PostgreSQL oder Memory-Speicher)
### Container-Operationen
```bash
docker logs -f betterdb-monitor # follow logs
docker stop betterdb-monitor # stop
docker rm betterdb-monitor # remove
```
## Storage-Backends
BetterDB Monitor speichert Audit-Trail, Analysen, Captures und Anomaliedaten in einem von vier Backends:
| Backend | Anwendungsfall | Hinweise |
|---------|----------|-------|
| `memory` | Tests, ephemere Umgebungen | Standard in Docker; alle Daten gehen beim Neustart verloren |
| `postgres` | Produktion | `STORAGE_TYPE=postgres` + `STORAGE_URL=postgresql://user:pass@host:port/db` |
| `turso` | Produktion / serverloses SQLite | `STORAGE_TYPE=turso` + `STORAGE_URL=libsql://...` + `STORAGE_AUTH_TOKEN`; funktioniert in Docker |
| `sqlite` | Lokale Entwicklung / CLI | Natives Modul aus dem `latest` Docker-Image entfernt; `STORAGE_SQLITE_FILEPATH` optional |
## 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-Laufzeitmetriken – alle mit dem Präfix `betterdb_`.
```yaml
scrape_configs:
- job_name: 'betterdb-monitor'
metrics_path: '/api/prometheus/metrics'
static_configs:
- targets: ['your-monitor-host:3001']
```
Vollständige Metrik-Referenz: [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) und [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/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. Siehe [`packages/`](https://github.com/betterdb-inc/monitor/blob/master/packages) für die vollständige Liste.
| Paket | Sprache | Registry |
|---|---|---|
| [`@betterdb/monitor`](https://github.com/betterdb-inc/monitor/blob/master/packages/cli) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/monitor) |
| [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/mcp) |
| [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/agent) |
| [`@betterdb/semantic-cache`](https://github.com/betterdb-inc/monitor/blob/master/packages/semantic-cache) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/semantic-cache) |
| [`betterdb-semantic-cache`](https://github.com/betterdb-inc/monitor/blob/master/packages/semantic-cache-py) | Python | [PyPI](https://pypi.org/project/betterdb-semantic-cache/) |
| [`@betterdb/agent-cache`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent-cache) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/agent-cache) |
| [`betterdb-agent-cache`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent-cache-py) | Python | [PyPI](https://pypi.org/project/betterdb-agent-cache/) |
| [`cache-benchmark`](https://github.com/betterdb-inc/monitor/blob/master/packages/cache-benchmark) | Python | Replay-Harness zum Benchmarking von semantischen Caches |
### 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.
### Lokales Setup
Voraussetzungen: Node.js >= 20.0.0, pnpm >= 9.0.0, Docker.
```bash
pnpm install
cp .env.example .env
pnpm docker:dev # local Valkey (6380) and Redis (6382)
pnpm dev # web on :5173, api on :3001
```
Um sich anstelle von Valkey mit Redis zu verbinden, setzen Sie `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
```
Docker-Image-Builds:
```bash
pnpm docker:build # local build
pnpm docker:publish # multi-arch build & push (requires buildx)
```
### Neue Funktionen hinzufügen
1. Neue Endpunkte in `apps/api/src/` hinzufügen
2. Entsprechende API-Aufrufe in `apps/web/src/api/` hinzufügen
3. Gemeinsame Typen in `packages/shared/src/types/` hinzufügen
### Code-Stil
- 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/` fallen unter eine kommerzielle Lizenz (siehe `proprietary/LICENSE`). Diese Funktionen sind während des Early Access kostenlos.
- Alles andere steht unter [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).