Aponte 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

Em seguida, `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` e abra `http://localhost:3001`, ou ative o ingress do chart. Histórico com backend PostgreSQL, bring-your-own Secrets e licenciamento air-gapped estã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 monitorizar. Para armazenamento SQLite, também `npm install -g better-sqlite3`.

## O Que Obtém

### Veja tudo, guarde tudo

- **Análise histórica** - 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 COMMANDLOG** - exclusivo do Valkey 8.1+. Pedidos grandes e respostas grandes, não apenas os lentos.
- **Sessões de captura MONITOR** - grave tráfego real a pedido: live tail, filtro, replay, exportação para JSON/CSV e referência cruzada com o histórico de conexões.
- **Rastreamento de hot keys** - principais chaves por frequência de acesso com movimento de ranking ao longo do tempo. O Key Analytics (Pro, gratuito em acesso antecipado) adiciona tipo, TTL e distribuições de tamanho a partir de amostragem em tempo real.
- **Visibilidade de cluster** - grafos de topologia, heatmaps SLOT-STATS, CPU por slot e distribuição de chaves.
- **Métricas de threads de CPU e I/O** - visibilidade por thread que nenhuma ferramenta Redis consegue fornecer.
- **Análise de clientes** - veja exatamente qual serviço é responsável pelo quê, atribuído por nome e padrão de cliente.
- **Trilha de auditoria ACL** - acompanhe quem acedeu ao quê, persistido para conformidade e depuração pós-incidente.

### Compreenda e aja

- **Deteção de anomalias** (Pro, gratuito em acesso antecipado) - aprendizagem automática de baseline com eventos correlacionados e diagnósticos em linguagem simples. Mais de 20 detetores, sem limiares manuais.
- **Previsão de capacidade** - tempo projetado até ao limite para memória, ops/seg, CPU e fragmentação.
- **Webhooks** - entregas de alertas assinadas com HMAC com tentativas repetidas e um registo completo de entregas.
- **Migração ao vivo** - mova entre Redis e Valkey com um fluxo de trabalho de três fases: análise, execução e validação.

### Construído para a era da IA

- **Observabilidade de pesquisa 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. Consulte [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ântica** (Pro, gratuito em acesso antecipado) - saúde da taxa de acertos, recomendações de limiar de similaridade e um fluxo de trabalho de proposta de aprovação/rejeição. Observabilidade de memória de agentes incluída.
- **Rastreios de IA** - cascatas de spans OTLP da sua aplicação de IA, correlacionadas com o estado Valkey ao vivo subjacente a cada pedido. Consulte [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).

### Liga-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_*`. Consulte [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - ingira rastreios OTLP e espelhe métricas e eventos para qualquer backend OTLP. Consulte [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **API REST** - tudo na UI é uma chamada à API, documentada via OpenAPI.

## Aceda aos Seus Dados à Sua Maneira

| Interface | Detalhes |
|-----------|---------|
| Web UI | `http://localhost:3001` |
| Servidor MCP | `npx @betterdb/mcp` (stdio) - crie um token em Settings → MCP Tokens (obrigatório na cloud, opcional em self-hosted) |
| 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`. Em desenvolvimento local (`pnpm dev`) não há prefixo - por exemplo, `http://localhost:3001/health`.

## Bases de Dados Suportadas

| Base de Dados | Versão Mínima | Funcionalidades Suportadas |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | Todas as funcionalidades, incluindo COMMANDLOG (8.1+) e CLUSTER SLOT-STATS |
| **Redis** | 6+ | Todas as funcionalidades exceto o COMMANDLOG e o CLUSTER SLOT-STATS exclusivos do Valkey |

O backend usa um adaptador unificado sobre o cliente `iovalkey` compatível com o protocolo e deteta automaticamente Valkey vs Redis a partir da resposta `INFO` (`DB_TYPE=auto`). Capacidades como COMMANDLOG e SLOT-STATS são detetadas por versão, e a UI degrada-se graciosamente quando uma funcionalidade não está disponível.

Serviços geridos 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 o [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) alcança instâncias apenas em VPC através de um WebSocket de saída.

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

A imagem Docker contém a aplicação de monitorização (backend + frontend). Requer:
1. Uma instância Valkey/Redis para monitorizar
2. Uma instância PostgreSQL para persistência de dados (ou use armazenamento em memória)

### Executar 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 em execução 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 falhas online sobrevivam a reinicializações. O contêiner é executado como **UID 1001**,
> portanto, um volume recém-criado deve receber `chown` para esse UID (conforme mostrado acima) - caso contrário, a
> persistência falhará com `EACCES … license.jwt`.

Para o fluxo completo, a precedência de verificação e o 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 comprimido**: ~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 se 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

### Adicionando Novos Recursos

1. Adicione novos endpoints em `apps/api/src/`
2. Adicione as chamadas de API correspondentes em `apps/web/src/api/`
3. Adicione 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/` está licenciado sob CC BY-SA 4.0.
- O conteúdo em `proprietary/` é coberto por uma licença comercial (consulte `proprietary/LICENSE`). Esses recursos são gratuitos durante o acesso antecipado.
- Todo o restante está sob [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).