BetterDB Monitor

A camada de monitoramento que a Valkey merece.

O BetterDB persiste o que a Valkey descarta — slowlogs, padrões de comandos, atividade de clientes, sinais de anomalia — para que você possa depurar o que aconteceu às 3h da manhã, e não apenas o que está acontecendo agora. Construído para Valkey 8.x com suporte nativo a COMMANDLOG, CLUSTER SLOT-STATS e métricas de I/O por thread. Compatível com Redis 6+ para todo o resto.

Website | Docker Hub | npm | Documentação | Blog

O BetterDB é desenvolvido pela BetterDB Inc., uma empresa de benefício público que opera sob a OCV Open Charter.

Início Rápido (Docker)

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

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

Duas variantes de imagem são publicadas, ambas multi-arquitetura (linux/amd64, linux/arm64):

Consulte Implantação de Produção com Docker para armazenamento persistente, portas personalizadas, licenciamento e configurações air-gapped.

Início Rápido (CLI)

Execute o BetterDB Monitor sem Docker:

npx @betterdb/monitor

Na primeira execução, um assistente de configuração interativo orienta você pela conexão com o banco de dados, backend de armazenamento (SQLite, PostgreSQL ou em memória) e configurações do servidor. A configuração é salva em ~/.betterdb/config.json.

npm install -g @betterdb/monitor   # instalação global
betterdb --setup                   # reexecuta o assistente de configuração
betterdb --port 8080               # substitui a porta do servidor
betterdb --db-host 1.2.3.4         # substitui o host do banco de dados
betterdb --help                    # todas as opções

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, guarde 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 — registre 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 variação de posição ao longo do tempo. O Key Analytics (Pro, gratuito no acesso antecipado) adiciona distribuições de tipo, TTL e tamanho a partir de amostragem ao vivo.
• Visibilidade de cluster — grafos de topologia, mapas de calor SLOT-STATS, CPU por slot e distribuição de chaves.
• Métricas de thread de CPU e I/O — visibilidade por thread que nenhuma ferramenta Redis pode fornecer.
• Analíticos de clientes — veja exatamente qual serviço é responsável por 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 no 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 três fases: análise, execução e validação.

Construído para a era da IA

• Observabilidade de busca vetorial — ops/seg do FT.SEARCH e latência com saúde por índice para valkey-search e RediSearch. Consulte docs/vector-ai.
• Latência de inferência — p50/p95/p99 por índice, com alertas de violação de SLA (Pro, gratuito no acesso antecipado).
• Inteligência de cache semântico (Pro, gratuito no acesso antecipado) — saúde da taxa de acertos, recomendações de limite de similaridade e um fluxo de trabalho de propostas 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 ao vivo da Valkey sob cada requisição.

Integra-se a tudo

• Servidor MCP — 60 ferramentas para Claude Code, Cursor ou qualquer cliente MCP via @betterdb/mcp.
• Endpoint Prometheus — mais de 100 métricas betterdb_*. Consulte docs/prometheus-metrics.md.
• OpenTelemetry — espelhe métricas e eventos para qualquer backend OTLP.
• API REST — tudo na interface é uma chamada de API, documentada via OpenAPI.

Acesse Seus Dados do Seu Jeito

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

O backend usa um adaptador unificado sobre o cliente iovalkey, compatível em nível de protocolo, 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, e o @betterdb/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)

Executar com Armazenamento 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

Executar em Porta Personalizada

Defina a variável de ambiente PORT e faça o mapeamento correspondente no -p:

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

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

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

Variáveis de Ambiente

Referência completa, incluindo IA, exportação OTLP, ajuste de webhooks e limites de health-gate: docs/configuration.md.

Licenciamento e Suporte Air-Gapped

O BetterDB Monitor desbloqueia recursos Pro/Enterprise de uma de duas maneiras, dependendo de o host ter acesso à internet:

• Chave de licença online — defina BETTERDB_LICENSE_KEY. O monitor a valida contra betterdb.com e armazena em cache um token assinado verificado localmente, para que seu plano continue funcionando durante quedas curtas e reinicializações.
• Token de licença offline / air-gapped — para hosts sem nenhum acesso à internet (veja abaixo).

Como funciona o licenciamento air-gapped

Cada direito é um JWT RS256 assinado. O monitor o verifica localmente contra chaves públicas embutidas na imagem — ele nunca precisa alcançar um servidor de licenças para confiar em um token. Assim, um host air-gapped pode executar planos pagos com zero conectividade:

1. Em uma máquina com acesso à internet, faça login em betterdb.com/account/licenses e baixe seu token de licença offline (.jwt, Pro/Enterprise). Ele não contém segredos e não pode ser adulterado — qualquer edição quebra a assinatura.
2. Transfira-o para o host air-gapped como preferir (USB, gerenciamento de configuração, um mount de segredo no Docker/Kubernetes).
3. Forneça-o via BETTERDB_OFFLINE_LICENSE_FILE (caminho), BETTERDB_OFFLINE_LICENSE (string inline) ou cole-o na interface em Configurações → Licença → "Ambiente air-gapped? Ative uma licença offline."

Quando um token offline está configurado e nenhum BETTERDB_LICENSE_KEY é definido, o monitor faz zero requisições de saída — verificações de licença, telemetria e pings de atualização são todos desabilitados. Ele executa o plano concedido até o token expirar (licenças perpétuas são baixadas novamente anualmente) e então reverte para Community.

# totalmente offline - nenhuma rede necessária
docker volume create betterdb-data
docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d   # volume gravável pelo UID 1001 (uma 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

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 quedas online sobrevivam a reinicializações. O contêiner roda como UID 1001, portanto um volume recém-criado deve ser chownado 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 e a Referência de configuração.

Detalhes da Imagem Docker

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

Operações do Contêiner

docker logs -f betterdb-monitor        # seguir logs
docker stop betterdb-monitor           # parar
docker rm betterdb-monitor             # remover

Backends de Armazenamento

O BetterDB Monitor persiste trilha de auditoria, analíticos, capturas e dados de anomalias em um de três backends:

Métricas Prometheus

As métricas são expostas em GET /api/prometheus/metrics no formato de texto do Prometheus: auditoria ACL, conexões de clientes, padrões de slowlog/commandlog, memória, throughput, keyspace, replicação, estatísticas de slots de cluster e métricas de runtime Node.js — todas prefixadas com betterdb_.

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

Referência completa de métricas: docs/prometheus-metrics.md e docs/prometheus-integration.md.

Desenvolvimento

Estrutura do Projeto

betterdb-monitor/
├── apps/
│   ├── api/                 # Backend NestJS (Fastify)
│   └── web/                 # Frontend React (Vite)
├── packages/                # Pacotes publicados (veja abaixo)
├── docs/                    # Site de documentação (Jekyll)
├── docker-compose.yml       # Valkey local (porta 6380) e Redis (porta 6382) para testes
└── package.json             # Raiz do workspace

Pacotes

Este monorepo inclui vários pacotes independentes. Consulte packages/ para a lista completa.

Stack Tecnológico

• Backend: NestJS com adaptador Fastify, iovalkey para conexões Valkey/Redis, TypeScript em modo estrito. Porta 3001.
• Frontend: React + TypeScript, Vite, TailwindCSS, Recharts. Servidor de desenvolvimento na porta 5173.
• Monorepo: pnpm workspaces + Turborepo.

Configuração Local

Pré-requisitos: Node.js >= 20.0.0, pnpm >= 9.0.0, Docker.

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

Para conectar ao Redis em vez da Valkey, defina DB_PORT=6382 no .env.

pnpm dev:api           # somente API
pnpm dev:web           # somente frontend
pnpm docker:dev:down   # parar bancos de dados locais
pnpm build             # build de produção
pnpm test              # testes de API

Builds de imagem Docker:

pnpm docker:build      # build local
pnpm docker:publish    # build multi-arquitetura & push (requer buildx)

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/ é 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 resto é MIT.