convez.ai
PluginDevOps & InfraestruturaIntermediário
BetterDB-inc

BetterDB Monitor

BetterDB-inc/monitor

Monitoramento, slowlog e auditoria para Valkey/Redis

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin de monitoramento em tempo real para Valkey e Redis com análise de slowlog e auditoria completa. Oferece dashboard web com visualização de métricas, CLI para integração em pipelines e MCP server para agentes de IA. Ideal para debug de performance e compliance de operações em bancos de dados em memória.

Instalação

$npx convez-ai BetterDB-inc/monitor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1,3 mil
Forks
85
Acompanhando
38
Saúde
50%
Último commit
há 1 dia
Versão
v0.56.0
Issues abertas
62
Contribuidores
8

Casos de uso

  • Diagnóstico de queries lentas e gargalos de performance
  • Auditoria e rastreamento de operações em Redis/Valkey
  • Integração com agentes de IA para análise automática de dados

Veredito

Ferramenta madura e bem-estruturada para monitoramento de Redis/Valkey em production. A arquitetura em monorepo (NestJS + React + MCP) cobre casos de uso técnicos reais, mas a curva de setup (Docker, monorepo) é mais alta que alternativas.

README

A tradução para o português deste README ainda está na fila.

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

PackageLanguageRegistry
@betterdb/semantic-cacheTypeScriptnpm
betterdb-semantic-cachePythonPyPI
@betterdb/agent-cacheTypeScriptnpm
betterdb-agent-cachePythonPyPI

Tools

PackageLanguageRegistry
@betterdb/monitorTypeScriptnpm
@betterdb/mcpTypeScriptnpm
@betterdb/agentTypeScriptnpm

Benchmarking

PackageLanguageDescription
cache-benchmarkPythonReplay 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
  1. Copy environment variables:
cp .env.example .env
  1. 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
  1. Start development servers:
pnpm dev

The application will be available at:

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

VariableRequiredDefaultDescription
DB_HOSTYeslocalhostValkey/Redis host to monitor
DB_PORTNo6379Valkey/Redis port
DB_PASSWORDNo-Valkey/Redis password
DB_USERNAMENodefaultValkey/Redis ACL username
DB_TYPENoautoDatabase type: auto, valkey, or redis
STORAGE_TYPENomemoryStorage backend: memory or postgres
STORAGE_URLConditional-PostgreSQL connection URL (required if STORAGE_TYPE=postgres)
PORTNo3001Application HTTP port
NODE_ENVNoproductionNode environment
ANOMALY_DETECTION_ENABLEDNotrueEnable anomaly detection
ANOMALY_PROMETHEUS_INTERVAL_MSNo30000Prometheus summary update interval (ms)

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

DatabaseMinimum VersionSupported Features
Valkey8.0+All features including COMMANDLOG and CLUSTER SLOT-STATS
Redis6.0+All features except COMMANDLOG and CLUSTER SLOT-STATS

Feature Compatibility Matrix

FeatureCommandValkeyRedis
Server InfoINFOYesYes
Health CheckPINGYesYes
SlowlogSLOWLOGYesYes (2.2+)
Client ListCLIENT LISTYesYes (2.4+)
Latency MonitorLATENCYYesYes (2.8+)
Memory StatsMEMORY STATSYesYes (4.0+)
ACL LogACL LOGYesYes (6.0+)
Command LogCOMMANDLOGYes (8.1+)No (Valkey-only)
Cluster Slot StatsCLUSTER SLOT-STATSYes (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

MetricTypeLabelsDescription
betterdb_acl_deniedgauge-Total ACL denied events captured
betterdb_acl_denied_by_reasongaugereasonACL denied events by reason
betterdb_acl_denied_by_usergaugeusernameACL denied events by username

Client Connection Metrics

MetricTypeLabelsDescription
betterdb_client_connections_currentgauge-Current number of client connections
betterdb_client_connections_peakgauge-Peak connections in retention period
betterdb_client_connections_by_namegaugeclient_nameCurrent connections by client name
betterdb_client_connections_by_usergaugeuserCurrent connections by ACL user

Slowlog Metrics

MetricTypeLabelsDescription
betterdb_slowlog_pattern_countgaugepatternNumber of slow queries per pattern
betterdb_slowlog_pattern_avg_duration_usgaugepatternAverage duration in microseconds per pattern
betterdb_slowlog_pattern_percentagegaugepatternPercentage of slow queries per pattern

COMMANDLOG Metrics (Valkey 8.1+)

MetricTypeLabelsDescription
betterdb_commandlog_large_requestgauge-Total large request entries
betterdb_commandlog_large_replygauge-Total large reply entries
betterdb_commandlog_large_request_by_patterngaugepatternLarge request count by command pattern
betterdb_commandlog_large_reply_by_patterngaugepatternLarge reply count by command pattern

Node.js Process Metrics

MetricTypeLabelsDescription
betterdb_process_cpu_user_seconds_totalcounter-Total user CPU time spent in seconds
betterdb_process_cpu_system_seconds_totalcounter-Total system CPU time spent in seconds
betterdb_process_cpu_seconds_totalcounter-Total user and system CPU time spent in seconds
betterdb_process_start_time_secondsgauge-Start time of the process since unix epoch in seconds
betterdb_process_resident_memory_bytesgauge-Resident memory size in bytes
betterdb_process_virtual_memory_bytesgauge-Virtual memory size in bytes
betterdb_process_heap_bytesgauge-Process heap size in bytes
betterdb_process_open_fdsgauge-Number of open file descriptors
betterdb_process_max_fdsgauge-Maximum number of open file descriptors

Node.js Event Loop Metrics

MetricTypeLabelsDescription
betterdb_nodejs_eventloop_lag_secondsgauge-Lag of event loop in seconds
betterdb_nodejs_eventloop_lag_min_secondsgauge-Minimum recorded event loop delay
betterdb_nodejs_eventloop_lag_max_secondsgauge-Maximum recorded event loop delay
betterdb_nodejs_eventloop_lag_mean_secondsgauge-Mean of recorded event loop delays
betterdb_nodejs_eventloop_lag_stddev_secondsgauge-Standard deviation of recorded event loop delays
betterdb_nodejs_eventloop_lag_p50_secondsgauge-50th percentile of recorded event loop delays
betterdb_nodejs_eventloop_lag_p90_secondsgauge-90th percentile of recorded event loop delays
betterdb_nodejs_eventloop_lag_p99_secondsgauge-99th percentile of recorded event loop delays

Node.js Runtime Metrics

MetricTypeLabelsDescription
betterdb_nodejs_active_resourcesgaugetypeActive resources keeping the event loop alive
betterdb_nodejs_active_resources_totalgauge-Total number of active resources
betterdb_nodejs_active_handlesgaugetypeActive libuv handles by type
betterdb_nodejs_active_handles_totalgauge-Total number of active handles
betterdb_nodejs_active_requestsgaugetypeActive libuv requests by type
betterdb_nodejs_active_requests_totalgauge-Total number of active requests
betterdb_nodejs_version_infogaugeversion, major, minor, patchNode.js version info

Node.js Heap Metrics

MetricTypeLabelsDescription
betterdb_nodejs_heap_size_total_bytesgauge-Process heap size from Node.js in bytes
betterdb_nodejs_heap_size_used_bytesgauge-Process heap size used from Node.js in bytes
betterdb_nodejs_external_memory_bytesgauge-Node.js external memory size in bytes
betterdb_nodejs_heap_space_size_total_bytesgaugespaceProcess heap space size total in bytes
betterdb_nodejs_heap_space_size_used_bytesgaugespaceProcess heap space size used in bytes
betterdb_nodejs_heap_space_size_available_bytesgaugespaceProcess heap space size available in bytes

Node.js GC Metrics

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

Ver o original no GitHub

Bom para

Relacionados