Apunta tu navegador a `http://localhost:3001`. Para monitorear una instancia específica:```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

Entonces ejecuta `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` y abre `http://localhost:3001`, o habilita el ingress del chart. El historial respaldado por PostgreSQL, los Secrets traídos por el usuario y las licencias en entornos aislados (air-gapped) están cubiertos en la [guía de Kubernetes](https://docs.betterdb.com/kubernetes) y en el [README del chart](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md).

## Inicio rápido (CLI)

Ejecuta BetterDB Monitor sin Docker:```bash
npx @betterdb/monitor

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

## Lo que obtienes

### Ve todo, conserva 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+. Solicitudes 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 contra el historial de conexiones.
- **Seguimiento de claves calientes** - claves principales por frecuencia de acceso con movimiento de rango a lo largo del tiempo. Key Analytics (Pro, gratis en acceso anticipado) añade distribuciones de tipo, TTL y tamaño a partir de muestreo en vivo.
- **Visibilidad de clúster** - gráficos de topología, mapas de calor SLOT-STATS, CPU por slot y distribución de claves.
- **Métricas de CPU y subprocesos de E/S** - visibilidad por subproceso que ninguna herramienta de Redis puede ofrecer.
- **Analíticas de clientes** - ve exactamente qué servicio es responsable de qué, atribuido por nombre de cliente y patrón.
- **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, gratis en 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 para memoria, ops/seg, CPU y fragmentación.
- **Webhooks** - entregas de alertas firmadas con HMAC con reintentos y un registro completo de entregas.
- **Migración en vivo** - muévete entre Redis y Valkey con un flujo de trabajo de análisis, ejecución y validación en tres fases.

### Diseñado para la era de la IA

- **Observabilidad de búsqueda vectorial** - ops/seg y latencia de FT.SEARCH con salud por índice para [valkey-search](https://github.com/valkey-io/valkey-search) y RediSearch. Consulta [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **Latencia de inferencia** - p50/p95/p99 por índice, con alertas de incumplimiento de SLA (Pro, gratis en acceso anticipado).
- **Inteligencia de caché semántica** (Pro, gratis en acceso anticipado) - salud de 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 debajo de cada solicitud.

### Se integra con todo

- **Servidor MCP** - 60 herramientas para Claude Code, Cursor o cualquier cliente MCP mediante [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Endpoint Prometheus** - más de 100 métricas `betterdb_*`. Consulta [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - replica métricas y eventos a cualquier backend OTLP.
- **API REST** - todo en la interfaz es una llamada API, documentada mediante OpenAPI.

## Accede a tus datos a tu manera

| Interfaz | Detalles |
|-----------|---------|
| Interfaz web | `http://localhost:3001` |
| Servidor MCP | `npx @betterdb/mcp` (stdio) - crea un token en Configuración → Tokens MCP |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| API REST (OpenAPI) | `http://localhost:3001/docs` |
| Verificación de salud | `http://localhost:3001/api/health` |

> **Nota**: En compilaciones de producción (Docker, CLI) las rutas de API se sirven bajo el prefijo `/api`. En desarrollo local (`pnpm dev`) no hay prefijo - p. ej. `http://localhost:3001/health`.

## Bases de datos compatibles

| Base de datos | Versión mínima | Funciones compatibles |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Todas las funciones, incluidos COMMANDLOG (8.1+) y CLUSTER SLOT-STATS |
| **Redis** | 6+ | Todas las funciones excepto COMMANDLOG y CLUSTER SLOT-STATS, exclusivos de Valkey |

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

Los servicios gestionados también son compatibles - las guías para AWS ElastiCache, MemoryDB, Redis Cloud y Upstash se encuentran en [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers), y [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) alcanza instancias solo-VPC mediante un WebSocket saliente.

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

### Ejecutar con red del host (acceder a servicios localhost)

Si tu Valkey y PostgreSQL se están ejecutando en el mismo host:```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

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

> **Persistencia:** monta un volumen con permisos de escritura en `/app/data` para que la licencia offline y
> el token de gracia por caída en línea sobrevivan a los reinicios. El contenedor se ejecuta como **UID 1001**,
> por lo que un volumen recién creado debe ser `chown`ed a ese usuario (como 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
**[Licencias Offline y Air-Gapped](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** y la
**[Referencia de configuración](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.

### 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 AI Helper experimental)
- **Plataformas**: `linux/amd64`, `linux/arm64`
- **Contiene**: API backend + archivos estáticos del frontend (servidos por Fastify)
- **Excluye**: soporte de SQLite (usa PostgreSQL o almacenamiento en memoria)

### Operaciones del Contenedor```bash
docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

Referencia completa de métricas: [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) y [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-integration.md).

## Desarrollo

### Estructura del Proyecto```
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

Para conectarse a Redis en lugar de Valkey, establezca `DB_PORT=6382` en `.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

### Añadir Nuevas Funcionalidades

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

### Estilo de Código

- Modo estricto de TypeScript, 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 funcionalidades son gratuitas durante el acceso anticipado.
- Todo lo demás está bajo [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).