monitor

BetterDB Monitor

The monitoring layer that Valkey deserves.

BetterDB persists what Valkey throws away - slowlogs, command patterns, client activity, anomaly signals - so you can debug what happened at 3am, not just what's happening now. Built for Valkey 8.x with native support for COMMANDLOG, CLUSTER SLOT-STATS, and per-thread I/O metrics. Redis 6+ compatible for everything else.

Website | Docker Hub | npm | Documentation | Blog

BetterDB is built by BetterDB Inc., a public benefit company operating under the OCV Open Charter.

Quick Start (Docker)

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

Point your browser to http://localhost:3001. To monitor a specific instance:

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

Connecting to a database on your host machine? Inside the container localhost is the container itself, not your host — so use host.docker.internal as the database host. On Docker Desktop (macOS/Windows) it works out of the box; on Linux add --add-host=host.docker.internal:host-gateway to the docker run command so the name resolves. The dashboard's one-click "connect to local instance" button auto-detects this and pre-fills the right host for you.

Two image variants are published, both multi-arch (linux/amd64, linux/arm64):

Tag	What it is
latest, X.Y.Z-no-ai	Default image - every monitoring feature included, without the dependencies for the experimental local-LLM AI Helper
X.Y.Z	Adds the experimental AI Helper (bring your own Ollama; disabled by default via AI_ENABLED)

See Docker Production Deployment for persistent storage, custom ports, licensing, and air-gapped setups.

Quick Start (Kubernetes / Helm)

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

Then kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001 and open http://localhost:3001, or enable the chart's ingress. PostgreSQL-backed history, bring-your-own Secrets, and air-gapped licensing are all covered in the Kubernetes guide and the chart README.

Quick Start (CLI)

Run BetterDB Monitor without Docker:

npx @betterdb/monitor

On first run, an interactive setup wizard guides you through database connection, storage backend (SQLite, PostgreSQL, or in-memory), and server settings. Configuration is saved to ~/.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

Requires Node.js >= 20.0.0 and a Valkey or Redis instance to monitor. For SQLite storage, also npm install -g better-sqlite3.

What You Get

See everything, keep everything

• Historical analytics - query slowlogs, command patterns, client activity, and latency across any time range. The data that used to disappear after a log rotation.
• COMMANDLOG support - Valkey 8.1+ exclusive. Large requests and large replies, not just the slow ones.
• MONITOR capture sessions - record real traffic on demand: live tail, filter, replay, export to JSON/CSV, and cross-reference against connection history.
• Hot key tracking - top keys by access frequency with rank movement over time. Key Analytics (Pro, free in early access) adds type, TTL, and size distributions from live sampling.
• Cluster visibility - topology graphs, SLOT-STATS heatmaps, per-slot CPU and key distribution.
• CPU & I/O thread metrics - per-thread visibility that no Redis tool can provide.
• Client analytics - see exactly which service is responsible for what, attributed by client name and pattern.
• ACL audit trail - track who accessed what, persisted for compliance and post-incident debugging.

Understand and act

• Anomaly detection (Pro, free in early access) - automatic baseline learning with correlated events and plain-English diagnoses. 20+ detectors, no manual thresholds.
• Capacity forecasting - projected time-to-ceiling for memory, ops/sec, CPU, and fragmentation.
• Webhooks - HMAC-signed alert deliveries with retries and a full delivery log.
• Live migration - move between Redis and Valkey with a three-phase analysis, execution, and validation workflow.

Built for the AI era

• Vector search observability - FT.SEARCH ops/sec and latency with per-index health for valkey-search and RediSearch. See docs/vector-ai.
• Inference latency - p50/p95/p99 per index, with SLA breach alerts (Pro, free in early access).
• Semantic cache intelligence (Pro, free in early access) - hit-rate health, similarity-threshold recommendations, and an approve/reject proposal workflow. Agent memory observability included.
• AI traces - OTLP span waterfalls from your AI application, correlated with the live Valkey state underneath each request. See docs/opentelemetry.md.

Plugs into everything

• MCP server - 60 tools for Claude Code, Cursor, or any MCP client via @betterdb/mcp.
• Prometheus endpoint - 100+ betterdb_* metrics. See docs/prometheus-metrics.md.
• OpenTelemetry - ingest OTLP traces, and mirror metrics and events to any OTLP backend. See docs/opentelemetry.md.
• REST API - everything in the UI is an API call, documented via OpenAPI.

Access Your Data Your Way

Interface	Details
Web UI	http://localhost:3001
MCP server	npx @betterdb/mcp (stdio) - create a token under Settings → MCP Tokens (required on cloud, optional on self-hosted)
Prometheus	http://localhost:3001/api/prometheus/metrics
REST API (OpenAPI)	http://localhost:3001/docs
Health check	http://localhost:3001/api/health

Note: In production builds (Docker, CLI) API routes are served under the /api prefix. In local development (pnpm dev) there is no prefix - e.g. http://localhost:3001/health.

Supported Databases

Database	Minimum Version	Supported Features
Valkey	8.0+	All features including COMMANDLOG (8.1+) and CLUSTER SLOT-STATS
Redis	6+	All features except the Valkey-exclusive COMMANDLOG and CLUSTER SLOT-STATS

The backend uses a unified adapter over the wire-compatible iovalkey client and auto-detects Valkey vs Redis from the INFO response (DB_TYPE=auto). Capabilities like COMMANDLOG and SLOT-STATS are detected per version, and the UI gracefully degrades when a feature isn't available.

Managed services are supported too - guides for AWS ElastiCache, MemoryDB, Redis Cloud, and Upstash live in docs/providers, and @betterdb/agent reaches VPC-only instances over an outbound WebSocket.

Docker Production Deployment

The Docker image contains the monitoring application (backend + frontend). It requires:

1. A Valkey/Redis instance to monitor
2. A PostgreSQL instance for data persistence (or use memory storage)

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

Set the PORT environment variable and match the -p mapping:

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)

If your Valkey and PostgreSQL are running on the same 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

Environment Variables

Variable	Required	Default	Description
DB_HOST	Yes	localhost	Valkey/Redis host to monitor
DB_PORT	No	6379	Valkey/Redis port
DB_PASSWORD	No	-	Valkey/Redis password
DB_USERNAME	No	default	Valkey/Redis ACL username
DB_TYPE	No	auto	Database type: auto, valkey, or redis
STORAGE_TYPE	No	memory	Storage backend: memory or postgres
STORAGE_URL	Conditional	-	PostgreSQL connection URL (required if STORAGE_TYPE=postgres)
PORT	No	3001	Application HTTP port
NODE_ENV	No	production	Node environment
ANOMALY_DETECTION_ENABLED	No	true	Enable anomaly detection
ANOMALY_PROMETHEUS_INTERVAL_MS	No	30000	Prometheus summary update interval (ms)
BETTERDB_LICENSE_KEY	No	-	Online license key (Pro/Enterprise), validated over the network
BETTERDB_OFFLINE_LICENSE_FILE	No	-	Path to a signed offline license .jwt for air-gapped hosts (see below)
BETTERDB_OFFLINE_LICENSE	No	-	Offline license token as an inline JWT string
BETTERDB_DATA_DIR	No	/app/data	Directory for persisted license state (mount a writable volume)
ENCRYPTION_KEY	No	-	Key (min 16 chars) used to envelope-encrypt stored connection passwords and SSH tunnel secrets at rest. Without it, secrets are stored in plaintext
BETTERDB_SSH_KEY_DIR	No	-	Directory that server-side SSH private keys must live in. Enables the "server file path" key source for SSH tunnels; a connection's key path must resolve inside it. Unset disables file-based keys (inline pasted keys still work)
BETTERDB_TELEMETRY	No	true	Set false to disable anonymous telemetry

Full reference, including AI, webhook tuning, and health-gate thresholds: docs/configuration.md. For OTLP trace ingest and metrics/event export, see docs/opentelemetry.md.

SSH Tunnels

Connections can reach a database through an SSH bastion/jump host instead of connecting directly — useful for Valkey/Redis in a private subnet, ElastiCache, or MemoryDB. Enable Connect via SSH tunnel when adding a connection and provide the SSH host, port, and username. A single hop is supported.

Authentication is either a password or a private key. Private keys come from one of two sources:

• Paste key (inline): the PEM key content is submitted with the connection. It is stored encrypted at rest only when ENCRYPTION_KEY is set (envelope encryption); without that key it is stored in plaintext, like connection passwords. Works everywhere, including managed/cloud deployments.
• Server file path: the key already lives on the monitor server's filesystem and is referenced by path. This requires setting the BETTERDB_SSH_KEY_DIR environment variable to the directory holding the allowed keys, and the referenced path must resolve inside it, so the AP