Aponte o seu navegador para `http://localhost:3001`. Para monitorar uma instância 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

Então execute `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` e abra `http://localhost:3001`, ou habilite o ingress do chart. Histórico com suporte a PostgreSQL, Secrets trazidos por você e licenciamento em ambiente isolado (air-gapped) são todos abordados no [guia do Kubernetes](https://docs.betterdb.com/kubernetes) e no [README do chart](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md).

## Início Rápido (CLI)

Execute o BetterDB Monitor sem Docker:```bash
npx @betterdb/monitor

Requer Node.js >= 20.0.0 e uma instância Valkey ou Redis para monitorar. Para armazenamento SQLite, também `npm install -g better-sqlite3`.

## O Que Você Obtém

### Veja tudo, mantenha tudo

- **Analíticos históricos** - consulte slowlogs, padrões de comandos, atividade de clientes e latência em qualquer intervalo de tempo. Os dados que costumavam desaparecer após uma rotação de logs.
- **Suporte a COMMANDLOG** - exclusivo do Valkey 8.1+. Requisições grandes e respostas grandes, não apenas as lentas.
- **Sessões de captura MONITOR** - grave tráfego real sob demanda: acompanhamento ao vivo, filtro, replay, exportação para JSON/CSV e referência cruzada com o histórico de conexões.
- **Rastreamento de chaves quentes** - principais chaves por frequência de acesso com movimento de classificação ao longo do tempo. Key Analytics (Pro, gratuito em acesso antecipado) adiciona distribuições de tipo, TTL e tamanho a partir de amostragem ao vivo.
- **Visibilidade de cluster** - gráficos de topologia, mapas de calor SLOT-STATS, distribuição de CPU e chaves por slot.
- **Métricas de CPU e threads de I/O** - visibilidade por thread que nenhuma ferramenta Redis pode fornecer.
- **Analíticos de clientes** - veja exatamente qual serviço é responsável pelo quê, atribuído por nome e padrão de cliente.
- **Trilha de auditoria ACL** - rastreie quem acessou o quê, persistido para conformidade e depuração pós-incidente.

### Entenda e aja

- **Detecção de anomalias** (Pro, gratuito em acesso antecipado) - aprendizado automático de linha de base com eventos correlacionados e diagnósticos em linguagem simples. Mais de 20 detectores, sem limites manuais.
- **Previsão de capacidade** - tempo projetado até o teto para memória, ops/seg, CPU e fragmentação.
- **Webhooks** - entregas de alertas assinadas com HMAC, com novas tentativas e um registro completo de entregas.
- **Migração ao vivo** - mova entre Redis e Valkey com um fluxo de trabalho de análise, execução e validação em três fases.

### Construído para a era da IA

- **Observabilidade de busca vetorial** - ops/seg e latência de FT.SEARCH com saúde por índice para [valkey-search](https://github.com/valkey-io/valkey-search) e RediSearch. Veja [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **Latência de inferência** - p50/p95/p99 por índice, com alertas de violação de SLA (Pro, gratuito em acesso antecipado).
- **Inteligência de cache semântico** (Pro, gratuito em acesso antecipado) - saúde da taxa de acertos, recomendações de limite de similaridade e um fluxo de trabalho de proposta aprovar/rejeitar. Observabilidade de memória de agente incluída.
- **Rastreamentos de IA** - cascatas de spans OTLP do seu aplicativo de IA, correlacionadas com o estado Valkey ao vivo por trás de cada requisição. Veja [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).

### Integra-se a tudo

- **Servidor MCP** - 60 ferramentas para Claude Code, Cursor ou qualquer cliente MCP via [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **Endpoint Prometheus** - mais de 100 métricas `betterdb_*`. Veja [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - ingira rastreamentos OTLP e espelhe métricas e eventos para qualquer backend OTLP. Veja [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **API REST** - tudo na interface é uma chamada de API, documentada via OpenAPI.

## Acesse Seus Dados do Seu Jeito

| Interface | Detalhes |
|-----------|---------|
| Web UI | `http://localhost:3001` |
| Servidor MCP | `npx @betterdb/mcp` (stdio) - crie um token em Configurações → Tokens MCP |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| API REST (OpenAPI) | `http://localhost:3001/docs` |
| Verificação de saúde | `http://localhost:3001/api/health` |

> **Nota**: Em builds de produção (Docker, CLI), as rotas da API são servidas sob o prefixo `/api`. No desenvolvimento local (`pnpm dev`) não há prefixo - ex.: `http://localhost:3001/health`.

## Bancos de Dados Suportados

| Banco de Dados | Versão Mínima | Recursos Suportados |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Todos os recursos, incluindo COMMANDLOG (8.1+) e CLUSTER SLOT-STATS |
| **Redis** | 6+ | Todos os recursos, exceto COMMANDLOG e CLUSTER SLOT-STATS exclusivos do Valkey |

O backend usa um adaptador unificado sobre o cliente `iovalkey` compatível por fio e detecta automaticamente Valkey vs Redis a partir da resposta `INFO` (`DB_TYPE=auto`). Recursos como COMMANDLOG e SLOT-STATS são detectados por versão, e a interface degrada graciosamente quando um recurso não está disponível.

Serviços gerenciados também são suportados - guias para AWS ElastiCache, MemoryDB, Redis Cloud e Upstash estão em [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers), e [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) alcança instâncias somente VPC por meio de um WebSocket de saída.

## Implantação de Produção com Docker

A imagem Docker contém o aplicativo de monitoramento (backend + frontend). Ela requer:
1. Uma instância Valkey/Redis para monitorar
2. Uma instância PostgreSQL para persistência de dados (ou use armazenamento em memória)

### Execute com Armazenamento 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

### Executar com Rede do Host (Acessar serviços localhost)

Se o seu Valkey e PostgreSQL estiverem rodando no mesmo 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

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

> **Persistência:** monte um volume gravável em `/app/data` para que a licença offline e
> o token de tolerância a indisponibilidade online sobrevivam a reinicializações. O contêiner executa como **UID 1001**,
> portanto, um volume recém-criado deve ser `chown`ed para ele (mostrado acima) - caso contrário,
> a persistência falha com `EACCES … license.jwt`.

Para o fluxo completo, precedência de verificação e runbook de rotação de chaves, consulte
**[Licenças Offline e Air-Gapped](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** e a
**[Referência de configuração](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.

### Detalhes da Imagem Docker

- **Imagem Base**: `node:20-alpine`
- **Tamanho compactado**: ~360MB (`latest` / `-no-ai`) / ~640MB (imagem versionada com as dependências de LLM local do AI Helper experimental)
- **Plataformas**: `linux/amd64`, `linux/arm64`
- **Contém**: API de backend + arquivos estáticos do frontend (servidos pelo Fastify)
- **Excluído**: suporte a SQLite (use PostgreSQL ou armazenamento em memória)

### Operações do Contêiner```bash
docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

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

## Desenvolvimento

### Estrutura do Projeto```
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 conectar ao Redis em vez do Valkey, defina `DB_PORT=6382` no `.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

### Adicionar Novos Recursos

1. Adicionar novos endpoints em `apps/api/src/`
2. Adicionar chamadas de API correspondentes em `apps/web/src/api/`
3. Adicionar tipos compartilhados em `packages/shared/src/types/`

### Estilo de Código

- TypeScript em modo estrito, tipos de retorno explícitos, sem `any`
- ESLint + Prettier configurados

## Licença

- O conteúdo em `docs/` é licenciado sob CC BY-SA 4.0.
- O conteúdo em `proprietary/` é coberto por uma licença comercial (ver `proprietary/LICENSE`). Esses recursos são gratuitos durante o acesso antecipado.
- Todo o resto é [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).