BetterDB Monitor

A monorepo application for monitoring Valkey/Redis databases with a NestJS backend and React frontend.

Website | Docker Hub | npm | Documentation | Blog

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

Project Structure

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

Packages

This monorepo ships several standalone packages. See packages/ for the full list.

Caching

Package	Language	Registry
@betterdb/semantic-cache	TypeScript	npm
betterdb-semantic-cache	Python	PyPI
@betterdb/agent-cache	TypeScript	npm
betterdb-agent-cache	Python	PyPI

Tools

Package	Language	Registry
@betterdb/monitor	TypeScript	npm
@betterdb/mcp	TypeScript	npm
@betterdb/agent	TypeScript	npm

Benchmarking

Package	Language	Description
cache-benchmark	Python	Replay harness for benchmarking semantic caches against public datasets

Tech Stack

Backend

• NestJS with Fastify adapter
• iovalkey for Valkey/Redis connections
• TypeScript with strict mode
• Runs on port 3001

Frontend

• React with TypeScript
• Vite for build tooling
• TailwindCSS for styling
• Recharts for data visualization
• Runs on port 5173

Monorepo

• pnpm workspaces for dependency management
• Turborepo for build orchestration

Quick Start

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 9.0.0
• Docker (for local Valkey or Redis instances)

Installation

1. Install dependencies:

pnpm install

2. Copy environment variables:

cp .env.example .env

3. Start local database instances (Valkey on 6380, Redis on 6382):

pnpm docker:up

To connect to Redis instead of Valkey, update .env:

DB_PORT=6382

4. Start development servers:

pnpm dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001

Individual Commands

Run only the API:

pnpm dev:api

Run only the web frontend:

pnpm dev:web

Stop Docker containers:

pnpm docker:down

Build for production:

pnpm build

CLI Installation (npx)

The easiest way to run BetterDB Monitor without Docker:

npx @betterdb/monitor

On first run, an interactive setup wizard will guide you through configuration:

• Database connection (host, port, credentials)
• Storage backend (SQLite, PostgreSQL, or in-memory)
• Server port and other settings

Configuration is saved to ~/.betterdb/config.json.

Global Installation

npm install -g @betterdb/monitor
betterdb

CLI Options

betterdb --setup           # Re-run setup wizard, then start server
betterdb --port 8080       # Override server port
betterdb --db-host 1.2.3.4 # Override database host
betterdb --help            # Show all options

SQLite Storage (Optional)

To use SQLite storage with the CLI, install better-sqlite3:

npm install -g better-sqlite3

Requirements

• Node.js >= 20.0.0
• A Valkey or Redis instance to monitor

---

Docker Production Deployment

Building the Docker Image

pnpm docker:build

For multi-arch builds (AMD64 + ARM64), first set up buildx:

docker buildx create --name mybuilder --use --bootstrap

Then build:

pnpm docker:build:multiarch

Running the Docker Container

The Docker image contains only 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)

Basic Run (Memory 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=memory \
  betterdb/monitor

Run on Custom Port

You can run the application on any port by setting the PORT environment variable with -e PORT=<port>:

docker run -d \
  --name betterdb-monitor \
  -p 8080:8080 \
  -e PORT=8080 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  -e STORAGE_TYPE=memory \
  betterdb/monitor

Note: When not using --network host, make sure the -p flag port mapping matches the PORT environment variable (e.g., -p 8080:8080 -e PORT=8080).

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

Auto-Remove Previous Container

To automatically remove any existing container with the same name:

docker rm -f betterdb-monitor 2>/dev/null; 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

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)

Licensing & Air-Gapped Support

BetterDB Monitor unlocks Pro/Enterprise features in one of two ways, depending on whether the host has internet access:

• Online license key — set BETTERDB_LICENSE_KEY. The monitor validates it against betterdb.com and caches a locally-verified signed token, so your tier keeps working through short outages and restarts.
• Offline / air-gapped license token — for hosts with no internet access at all (see below).

How air-gapped licensing works

Every entitlement is a signed RS256 JWT. The monitor verifies it locally against public keys embedded in the image — it never has to reach a license server to trust a token. So an air-gapped host can run paid tiers with zero connectivity:

1. On an internet-connected machine, sign in at betterdb.com/account/licenses and download your offline license token (.jwt, Pro/Enterprise). It contains no secrets and can't be tampered with — any edit breaks the signature.
2. Transfer it to the air-gapped host however you like (USB, config management, a Docker/Kubernetes secret mount).
3. Provide it via BETTERDB_OFFLINE_LICENSE_FILE (path), BETTERDB_OFFLINE_LICENSE (inline string), or paste it in the UI under Settings → License → “Air-gapped environment? Activate an offline license.”

When an offline token is configured and no BETTERDB_LICENSE_KEY is set, the monitor makes zero outbound requests — license checks, telemetry, and update pings are all disabled. It runs the granted tier until the token expires (perpetual licenses re-download yearly), then reverts to 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

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

Persistence: mount a writable volume at /app/data so the offline license and the online outage-grace token survive restarts. The container runs as UID 1001, so a freshly-created volume must be chowned to it (shown above) — otherwise persistence fails with EACCES … license.jwt.

For the full flow, verification precedence, and key-rotation runbook see Offline & Air-Gapped Licenses and the Configuration reference.

Accessing the Application

Once running, access the web interface at:

• Web UI: http://localhost:3001
• Health Check: http://localhost:3001/health
• Prometheus Metrics: http://localhost:3001/prometheus/metrics

Docker Image Details

• Base Image: node:20-alpine
• Size: ~188MB (optimized, no build tools)
• Platforms: linux/amd64, linux/arm64
• Contains: Backend API + Frontend static files (served by Fastify)
• Excluded: SQLite support (use PostgreSQL or Memory storage)

Checking Container Logs

docker logs -f betterdb-monitor

Stopping the Container

docker stop betterdb-monitor
docker rm betterdb-monitor

Features

Current Features

• Database connection health monitoring
• Auto-detection of Valkey vs Redis
• Version detection
• Capability detection (Command Log, Slot Stats)
• Auto-refresh every 5 seconds
• Full Redis 6.x and 7.x support (85-90% feature parity with Valkey)
• Graceful degradation for Valkey-only features

Vector / AI

For deployments running RediSearch or valkey-search, BetterDB ships a dedicated Vector / AI tab that surfaces FT.SEARCH ops/sec and average latency over time alongside per-index health (docs, records, deleted docs, indexing failures, backfill progress). Stale Prometheus labels are reconciled when indexes are dropped, and the tab hides automatically when the Search module isn't available. See docs/vector-ai/ for the full walkthrough and screenshots.

Supported Database Versions

Database	Minimum Version	Supported Features
Valkey	8.0+	All features including COMMANDLOG and CLUSTER SLOT-STATS
Redis	6.0+	All features except COMMANDLOG and CLUSTER SLOT-STATS

Feature Compatibility Matrix

Feature	Command	Valkey	Redis
Server Info	INFO	Yes	Yes
Health Check	PING	Yes	Yes
Slowlog	SLOWLOG	Yes	Yes (2.2+)
Client List	CLIENT LIST	Yes	Yes (2.4+)
Latency Monitor	LATENCY	Yes	Yes (2.8+)
Memory Stats	MEMORY STATS	Yes	Yes (4.0+)
ACL Log	ACL LOG	Yes	Yes (6.0+)
Command Log	COMMANDLOG	Yes (8.1+)	No (Valkey-only)
Cluster Slot Stats	CLUSTER SLOT-STATS	Yes (8.0+)	No (Valkey-only)

Architecture Highlights

Unified Adapter Pattern: The backend uses a unified UnifiedDatabaseAdapter that works seamlessly with both Valkey and Redis through the wire-compatible iovalkey client library.

Auto-detection: The application automatically detects whether it's connecting to Valkey or Redis by inspecting the INFO response.

Capability Detection: Features like Command Log (Valkey 8.1+) and Slot Stats (Valkey 8.0+) are automatically detected based on database type and version. The UI gracefully degrades when connecting to Redis, showing only supported features.

Graceful Degradation: When connected to Redis, Valkey-specific features return clear error messages indicating they're not supported, while all shared features work identically.

Prometheus Metrics

Metrics are exposed at GET /prometheus/metrics in Prometheus text format.

ACL Audit Metrics

Metric	Type	Labels	Description
betterdb_acl_denied	gauge	-	Total ACL denied events captured
betterdb_acl_denied_by_reason	gauge	reason	ACL denied events by reason
betterdb_acl_denied_by_user	gauge	username	ACL denied events by username

Client Connection Metrics

Metric	Type	Labels	Description
betterdb_client_connections_current	gauge	-	Current number of client connections
betterdb_client_connections_peak	gauge	-	Peak connections in retention period
betterdb_client_connections_by_name	gauge	client_name	Current connections by client name
betterdb_client_connections_by_user	gauge	user	Current connections by ACL user

Slowlog Metrics

Metric	Type	Labels	Description
betterdb_slowlog_pattern_count	gauge	pattern	Number of slow queries per pattern
betterdb_slowlog_pattern_avg_duration_us	gauge	pattern	Average duration in microseconds per pattern
betterdb_slowlog_pattern_percentage	gauge	pattern	Percentage of slow queries per pattern

COMMANDLOG Metrics (Valkey 8.1+)

Metric	Type	Labels	Description
betterdb_commandlog_large_request	gauge	-	Total large request entries
betterdb_commandlog_large_reply	gauge	-	Total large reply entries
betterdb_commandlog_large_request_by_pattern	gauge	pattern	Large request count by command pattern
betterdb_commandlog_large_reply_by_pattern	gauge	pattern	Large reply count by command pattern

Node.js Process Metrics

Metric	Type	Labels	Description
betterdb_process_cpu_user_seconds_total	counter	-	Total user CPU time spent in seconds
betterdb_process_cpu_system_seconds_total	counter	-	Total system CPU time spent in seconds
betterdb_process_cpu_seconds_total	counter	-	Total user and system CPU time spent in seconds
betterdb_process_start_time_seconds	gauge	-	Start time of the process since unix epoch in seconds
betterdb_process_resident_memory_bytes	gauge	-	Resident memory size in bytes
betterdb_process_virtual_memory_bytes	gauge	-	Virtual memory size in bytes
betterdb_process_heap_bytes	gauge	-	Process heap size in bytes
betterdb_process_open_fds	gauge	-	Number of open file descriptors
betterdb_process_max_fds	gauge	-	Maximum number of open file descriptors

Node.js Event Loop Metrics

Metric	Type	Labels	Description
betterdb_nodejs_eventloop_lag_seconds	gauge	-	Lag of event loop in seconds
betterdb_nodejs_eventloop_lag_min_seconds	gauge	-	Minimum recorded event loop delay
betterdb_nodejs_eventloop_lag_max_seconds	gauge	-	Maximum recorded event loop delay
betterdb_nodejs_eventloop_lag_mean_seconds	gauge	-	Mean of recorded event loop delays
betterdb_nodejs_eventloop_lag_stddev_seconds	gauge	-	Standard deviation of recorded event loop delays
betterdb_nodejs_eventloop_lag_p50_seconds	gauge	-	50th percentile of recorded event loop delays
betterdb_nodejs_eventloop_lag_p90_seconds	gauge	-	90th percentile of recorded event loop delays
betterdb_nodejs_eventloop_lag_p99_seconds	gauge	-	99th percentile of recorded event loop delays

Node.js Runtime Metrics

Metric	Type	Labels	Description
betterdb_nodejs_active_resources	gauge	type	Active resources keeping the event loop alive
betterdb_nodejs_active_resources_total	gauge	-	Total number of active resources
betterdb_nodejs_active_handles	gauge	type	Active libuv handles by type
betterdb_nodejs_active_handles_total	gauge	-	Total number of active handles
betterdb_nodejs_active_requests	gauge	type	Active libuv requests by type
betterdb_nodejs_active_requests_total	gauge	-	Total number of active requests
betterdb_nodejs_version_info	gauge	version, major, minor, patch	Node.js version info

Node.js Heap Metrics

Metric	Type	Labels	Description
betterdb_nodejs_heap_size_total_bytes	gauge	-	Process heap size from Node.js in bytes
betterdb_nodejs_heap_size_used_bytes	gauge	-	Process heap size used from Node.js in bytes
betterdb_nodejs_external_memory_bytes	gauge	-	Node.js external memory size in bytes
betterdb_nodejs_heap_space_size_total_bytes	gauge	space	Process heap space size total in bytes
betterdb_nodejs_heap_space_size_used_bytes	gauge	space	Process heap space size used in bytes
betterdb_nodejs_heap_space_size_available_bytes	gauge	space	Process heap space size available in bytes

Node.js GC Metrics

Metric	Type	Labels	Description
betterdb_nodejs_gc_duration_seconds	histogram	kind	Garbage collection duration (major, minor, incremental, weakcb)

Configuration

Database Connection (Valkey/Redis)

Edit .env to configure the Valkey/Redis database connection:

DB_HOST=localhost
DB_PORT=6379
DB_USERNAME=default
DB_PASSWORD=devpassword
DB_TYPE=auto  # 'valkey' | 'redis' | 'auto'

Storage Backend

BetterDB Monitor supports multiple storage backends for persisting audit trail and client analytics data:

SQLite (Local Development Only)

STORAGE_TYPE=sqlite
STORAGE_SQLITE_FILEPATH=./data/audit.db  # Optional, defaults to this path

• Use Case: Local development
• Pros: No external database required, simple setup
• Cons: Not available in Docker production builds
• Data Location: apps/api/data/audit.db

PostgreSQL (Recommended for Production)

STORAGE_TYPE=postgres
STORAGE_URL=postgresql://username:password@host:port/database

• Use Case: Production and local development
• Pros: Full relational database, better for production workloads
• Cons: Requires PostgreSQL instance
• Example: postgresql://dev:devpass@localhost:5432/postgres

Memory (Testing/Ephemeral)

STORAGE_TYPE=memory

• Use Case: Testing, ephemeral environments
• Pros: No persistence required, fast
• Cons: All data lost on restart

Running Locally with Different Storage Backends

With SQLite:

STORAGE_TYPE=sqlite \
DB_HOST=localhost \
DB_PORT=6380 \
DB_PASSWORD=devpassword \
pnpm dev:api

With PostgreSQL:

# Start PostgreSQL (if using docker-compose)
docker compose up -d postgres

# Run API with PostgreSQL
STORAGE_TYPE=postgres \
STORAGE_URL=postgresql://betterdb:devpassword@localhost:5432/betterdb \
DB_HOST=localhost \
DB_PORT=6380 \
DB_PASSWORD=devpassword \
pnpm dev:api

With Memory:

STORAGE_TYPE=memory \
DB_HOST=localhost \
DB_PORT=6380 \
DB_PASSWORD=devpassword \
pnpm dev:api

Development

Adding New Features

The codebase is structured to make it easy to add new monitoring features:

1. Add new endpoints in apps/api/src/
2. Add corresponding API calls in apps/web/src/api/
3. Add shared types in packages/shared/src/types/

Code Style

• TypeScript strict mode is enabled
• Explicit return types required on functions
• No any types allowed
• ESLint + Prettier configured

License

MIT