BetterDB Monitor

La capa de monitoreo que Valkey se merece.

BetterDB persiste lo que Valkey descarta: slowlogs, patrones de comandos, actividad de clientes, señales de anomalías... para que puedas depurar qué ocurrió a las 3 de la madrugada, no solo lo que está pasando ahora. Diseñado para Valkey 8.x con soporte nativo para COMMANDLOG, CLUSTER SLOT-STATS y métricas de E/S por hilo. Compatible con Redis 6+ para todo lo demás.

Sitio web | Docker Hub | npm | Documentación | Blog

BetterDB es desarrollado por BetterDB Inc., una empresa de beneficio público que opera bajo la OCV Open Charter.

Inicio rápido (Docker)

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

Apunta tu navegador a http://localhost:3001. Para monitorear una instancia específica:

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

Se publican dos variantes de imagen, ambas multi-arquitectura (linux/amd64, linux/arm64):

Consulta Implementación de producción con Docker para almacenamiento persistente, puertos personalizados, licencias y entornos aislados (air-gapped).

Inicio rápido (CLI)

Ejecuta BetterDB Monitor sin Docker:

npx @betterdb/monitor

En la primera ejecución, un asistente de configuración interactivo te guía a través de la conexión a la base de datos, el backend de almacenamiento (SQLite, PostgreSQL o en memoria) y los ajustes del servidor. La configuración se guarda en ~/.betterdb/config.json.

npm install -g @betterdb/monitor   # instalación global
betterdb --setup                   # re-ejecutar el asistente de configuración
betterdb --port 8080               # sobrescribir el puerto del servidor
betterdb --db-host 1.2.3.4         # sobrescribir el host de la base de datos
betterdb --help                    # todas las opciones

Requiere Node.js >= 20.0.0 y una instancia de Valkey o Redis para monitorear. Para almacenamiento SQLite, ejecuta también npm install -g better-sqlite3.

Qué obtienes

Ve todo, consérvalo todo

• Analíticas históricas: consulta slowlogs, patrones de comandos, actividad de clientes y latencia en cualquier rango de tiempo. Los datos que solían desaparecer tras una rotación de logs.
• Soporte de COMMANDLOG: exclusivo de Valkey 8.1+. Peticiones grandes y respuestas grandes, no solo las lentas.
• Sesiones de captura MONITOR: graba tráfico real bajo demanda: seguimiento en vivo, filtrado, reproducción, exportación a JSON/CSV y referencias cruzadas con el historial de conexiones.
• Seguimiento de claves calientes: principales claves por frecuencia de acceso con evolución de su posición en el ranking. Key Analytics (Pro, gratuito durante el acceso anticipado) añade distribuciones de tipo, TTL y tamaño a partir de muestreo en vivo.
• Visibilidad de clúster: grafos de topología, mapas de calor SLOT-STATS, distribución de CPU y claves por slot.
• Métricas de hilos de CPU y E/S: visibilidad por hilo que ninguna herramienta de Redis puede ofrecer.
• Analíticas de clientes: ve exactamente qué servicio es responsable de qué, atribuido por nombre y patrón de cliente.
• Registro de auditoría ACL: rastrea quién accedió a qué, persistido para cumplimiento normativo y depuración posterior a incidentes.

Comprende y actúa

• Detección de anomalías (Pro, gratuito durante el acceso anticipado): aprendizaje automático de línea base con eventos correlacionados y diagnósticos en lenguaje sencillo. Más de 20 detectores, sin umbrales manuales.
• Previsión de capacidad: tiempo proyectado hasta el límite de memoria, operaciones/seg, CPU y fragmentación.
• Webhooks: entregas de alertas firmadas con HMAC, con reintentos y un registro de entrega completo.
• Migración en vivo: muévete entre Redis y Valkey con un flujo de trabajo de tres fases: análisis, ejecución y validación.

Diseñado para la era de la IA

• Observabilidad de búsqueda vectorial: operaciones/seg de FT.SEARCH y latencia con estado de salud por índice para valkey-search y RediSearch. Consulta docs/vector-ai.
• Latencia de inferencia: p50/p95/p99 por índice, con alertas de incumplimiento de SLA (Pro, gratuito durante el acceso anticipado).
• Inteligencia de caché semántica (Pro, gratuito durante el acceso anticipado): salud de la tasa de aciertos, recomendaciones de umbral de similitud y un flujo de trabajo de propuestas aprobar/rechazar. Observabilidad de memoria de agentes incluida.
• Trazas de IA: cascadas de spans OTLP desde tu aplicación de IA, correlacionadas con el estado en vivo de Valkey subyacente a cada petición.

Se integra con todo

• Servidor MCP: 60 herramientas para Claude Code, Cursor o cualquier cliente MCP mediante @betterdb/mcp.
• Endpoint Prometheus: más de 100 métricas betterdb_*. Consulta docs/prometheus-metrics.md.
• OpenTelemetry: replica métricas y eventos a cualquier backend OTLP.
• API REST: todo en la interfaz es una llamada a la API, documentada mediante OpenAPI.

Accede a tus datos a tu manera

Nota: En las compilaciones de producción (Docker, CLI), las rutas de la API se sirven bajo el prefijo /api. En el desarrollo local (pnpm dev) no hay prefijo; por ejemplo, http://localhost:3001/health.

Bases de datos compatibles

El backend utiliza un adaptador unificado sobre el cliente compatible por cable iovalkey y detecta automáticamente Valkey vs Redis a partir de la respuesta INFO (DB_TYPE=auto). Capacidades como COMMANDLOG y SLOT-STATS se detectan según la versión, y la interfaz degrada con elegancia cuando una función no está disponible.

Los servicios gestionados también son compatibles: hay guías para AWS ElastiCache, MemoryDB, Redis Cloud y Upstash en docs/providers, y @betterdb/agent llega a instancias solo-VPC mediante un WebSocket de salida.

Implementación de producción con Docker

La imagen de Docker contiene la aplicación de monitoreo (backend + frontend). Requiere:

1. Una instancia de Valkey/Redis para monitorear
2. Una instancia de PostgreSQL para la persistencia de datos (o usa almacenamiento en memoria)

Ejecutar con almacenamiento PostgreSQL

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

Ejecutar en un puerto personalizado

Establece la variable de entorno PORT y haz coincidir el mapeo -p:

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

Ejecutar con red del host (acceso a servicios localhost)

Si tu Valkey y PostgreSQL se ejecutan en el mismo 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

Variables de entorno

Referencia completa, incluyendo IA, exportación OTLP, ajuste de webhooks y umbrales de compuerta de salud: docs/configuration.md.

Licencias y soporte para entornos aislados (air-gapped)

BetterDB Monitor desbloquea las funciones Pro/Enterprise de una de dos maneras, según si el host tiene acceso a internet:

• Clave de licencia en línea: establece BETTERDB_LICENSE_KEY. El monitor la valida contra betterdb.com y almacena en caché un token firmado verificado localmente, de modo que tu nivel sigue funcionando durante cortes y reinicios breves.
• Token de licencia offline / air-gapped: para hosts sin acceso a internet en absoluto (ver más abajo).

Cómo funciona la licencia air-gapped

Cada derecho es un JWT RS256 firmado. El monitor lo verifica localmente contra las claves públicas integradas en la imagen: nunca necesita contactar con un servidor de licencias para confiar en un token. Así, un host aislado puede ejecutar niveles de pago con cero conectividad:

1. En una máquina con acceso a internet, inicia sesión en betterdb.com/account/licenses y descarga tu token de licencia offline (.jwt, Pro/Enterprise). No contiene secretos y no puede ser manipulado: cualquier edición rompe la firma.
2. Transfiérelo al host aislado como prefieras (USB, gestión de configuración, un montaje de secreto Docker/Kubernetes).
3. Provéelo mediante BETTERDB_OFFLINE_LICENSE_FILE (ruta), BETTERDB_OFFLINE_LICENSE (cadena en línea), o pégalo en la interfaz en Settings → License → "Air-gapped environment? Activate an offline license."

Cuando se configura un token offline y no se establece BETTERDB_LICENSE_KEY, el monitor realiza cero solicitudes salientes: las comprobaciones de licencia, la telemetría y los avisos de actualización están todos desactivados. Ejecuta el nivel concedido hasta que el token expire (las licencias perpetuas se vuelven a descargar anualmente) y luego vuelve a Community.

# totalmente offline: no se requiere red
docker volume create betterdb-data
docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d   # volumen escribible por UID 1001 (una sola vez)

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

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

Persistencia: monta un volumen escribible en /app/data para que la licencia offline y el token de gracia por cortes en línea sobrevivan a los reinicios. El contenedor se ejecuta como UID 1001, por lo que un volumen recién creado debe ser chowneado al mismo (se muestra arriba); de lo contrario, la persistencia falla con EACCES … license.jwt.

Para el flujo completo, la precedencia de verificación y el runbook de rotación de claves, consulta Offline & Air-Gapped Licenses y la referencia de configuración.

Detalles de la imagen Docker

• Imagen base: node:20-alpine
• Tamaño comprimido: ~360MB (latest / -no-ai) / ~640MB (imagen versionada con las dependencias de LLM local del asistente de IA experimental)
• Plataformas: linux/amd64, linux/arm64
• Contiene: API backend + archivos estáticos del frontend (servidos por Fastify)
• Excluido: soporte SQLite (usa PostgreSQL o almacenamiento en memoria)

Operaciones con contenedores

docker logs -f betterdb-monitor        # seguir logs
docker stop betterdb-monitor           # detener
docker rm betterdb-monitor             # eliminar

Backends de almacenamiento

BetterDB Monitor persiste el registro de auditoría, analíticas, capturas y datos de anomalías en uno de tres backends:

Métricas Prometheus

Las métricas se exponen en GET /api/prometheus/metrics en formato de texto Prometheus: auditoría ACL, conexiones de clientes, patrones de slowlog/commandlog, memoria, rendimiento, keyspace, replicación, estadísticas de slots del clúster y métricas del runtime de Node.js, todas con el prefijo betterdb_.

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

Referencia completa de métricas: docs/prometheus-metrics.md y docs/prometheus-integration.md.

Desarrollo

Estructura del proyecto

betterdb-monitor/
├── apps/
│   ├── api/                 # Backend NestJS (Fastify)
│   └── web/                 # Frontend React (Vite)
├── packages/                # Paquetes publicados (ver más abajo)
├── docs/                    # Sitio de documentación (Jekyll)
├── docker-compose.yml       # Valkey local (puerto 6380) y Redis (puerto 6382) para pruebas
└── package.json             # Raíz del workspace

Paquetes

Este monorepo incluye varios paquetes independientes. Consulta packages/ para la lista completa.

Stack tecnológico

• Backend: NestJS con adaptador Fastify, iovalkey para conexiones Valkey/Redis, TypeScript en modo estricto. Puerto 3001.
• Frontend: React + TypeScript, Vite, TailwindCSS, Recharts. Servidor de desarrollo en el puerto 5173.
• Monorepo: workspaces de pnpm + Turborepo.

Configuración local

Requisitos previos: Node.js >= 20.0.0, pnpm >= 9.0.0, Docker.

pnpm install
cp .env.example .env
pnpm docker:dev        # Valkey local (6380) y Redis (6382)
pnpm dev               # web en :5173, api en :3001

Para conectarte a Redis en lugar de Valkey, establece DB_PORT=6382 en .env.

pnpm dev:api           # solo API
pnpm dev:web           # solo frontend
pnpm docker:dev:down   # detener bases de datos locales
pnpm build             # compilación de producción
pnpm test              # pruebas de API

Compilación de imágenes Docker:

pnpm docker:build      # compilación local
pnpm docker:publish    # compilación y publicación multi-arquitectura (requiere buildx)

Añadir nuevas funciones

1. Añade nuevos endpoints en apps/api/src/
2. Añade las llamadas correspondientes a la API en apps/web/src/api/
3. Añade tipos compartidos en packages/shared/src/types/

Estilo de código

• TypeScript en modo estricto, tipos de retorno explícitos, sin any
• ESLint + Prettier configurados

Licencia

• El contenido bajo docs/ está licenciado bajo CC BY-SA 4.0.
• El contenido bajo proprietary/ está cubierto por una licencia comercial (consulta proprietary/LICENSE). Estas funciones son gratuitas durante el acceso anticipado.
• Todo lo demás es MIT.