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

Luego `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, el uso de tus propios Secrets y las licencias en entornos aislados se cubren en la [guía de Kubernetes](https://docs.betterdb.com/kubernetes) y 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 que monitorizar. Para almacenamiento SQLite, también `npm install -g better-sqlite3`.

## Lo que obtienes

### Verlo todo, conservarlo todo

- **Analíticas históricas** - consulta slowlogs, patrones de comandos, actividad de clientes y latencia en cualquier rango temporal. Los datos que solían desaparecer tras una rotación de logs.
- **Soporte de COMMANDLOG** - exclusivo de Valkey 8.1+. Solicitudes y respuestas grandes, no solo las lentas.
- **Sesiones de captura MONITOR** - graba tráfico real bajo demanda: tail en vivo, filtrado, replay, exportación a JSON/CSV y referencias cruzadas con el historial de conexiones.
- **Seguimiento de hot keys** - claves más accedidas por frecuencia con movimiento de ranking 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** - grafos de topología, mapas de calor de SLOT-STATS, CPU por slot y distribución de claves.
- **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 de ACL** - rastrea quién accedió a qué, persistido para cumplimiento y depuración posterior a incidentes.

### Comprender y actuar

- **Detección de anomalías** (Pro, gratis en acceso anticipado) - aprendizaje automático de líneas base con eventos correlacionados y diagnósticos en lenguaje natural. 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 tres fases: análisis, ejecución y validación.

### 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 la tasa de aciertos, recomendaciones de umbral de similitud y un flujo de trabajo de propuestas de aprobación/rechazo. Incluye observabilidad de memoria de agentes.
- **Trazas de IA** - cascadas de spans OTLP desde tu aplicación de IA, correlacionadas con el estado en vivo de Valkey subyacente a cada solicitud. Consulta [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).

### Se conecta 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 de 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** - ingiere trazas OTLP y replica métricas y eventos a cualquier backend OTLP. Consulta [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **API REST** - todo en la interfaz de usuario es una llamada a la 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 Settings → MCP Tokens |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| API REST (OpenAPI) | `http://localhost:3001/docs` |
| Comprobación de estado | `http://localhost:3001/api/health` |

> **Nota**: En compilaciones de producción (Docker, CLI) las rutas de la API se sirven bajo el prefijo `/api`. En desarrollo local (`pnpm dev`) no hay prefijo - por ejemplo, `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 a nivel de protocolo y detecta automáticamente Valkey frente a Redis a partir de la respuesta de `INFO` (`DB_TYPE=auto`). Capacidades como COMMANDLOG y SLOT-STATS se detectan por versión, y la interfaz de usuario se degrada de forma elegante cuando una función no está disponible.

También se admiten servicios gestionados: las guías para AWS ElastiCache, MemoryDB, Redis Cloud y Upstash están 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) llega a instancias solo accesibles desde VPC mediante un WebSocket saliente.

## Despliegue de producción con Docker

La imagen de Docker contiene la aplicación de monitorización (backend + frontend). Requiere:
1. Una instancia de Valkey/Redis que monitorizar
2. Una instancia de PostgreSQL para la persistencia de datos (o usar 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 de localhost)

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

Verificar 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 interrupción online sobrevivan a los reinicios. El contenedor se ejecuta como **UID 1001**,
> por lo que un volumen recién creado debe recibir `chown` a ese UID (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 de backend + archivos estáticos del frontend (servidos por Fastify)
- **Excluido**: 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

### Agregar nuevas funcionalidades

1. Agrega nuevos endpoints en `apps/api/src/`
2. Agrega las llamadas API correspondientes en `apps/web/src/api/`
3. Agrega 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 (ver `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).