Documentação codeDB

O que é o codeDB

O codeDB é uma plataforma SaaS de monitoramento de SQL Server que coleta métricas em tempo real diretamente das instâncias do seu servidor Windows e as apresenta em um portal web com dashboards, alertas automáticos e relatórios históricos.

A plataforma foi criada para DBAs e gestores de TI que precisam de visibilidade contínua sobre a saúde do banco de dados sem a complexidade de configurar ferramentas de observabilidade do zero.

Como funciona

O codeDB é composto por três partes que trabalham em conjunto:

Fluxo resumido: Agente (coleta a cada 5 min) → API codeDB (processa e armazena) → Portal Web (exibe em tempo real).

Pré-requisitos

Servidor onde o agente será instalado

Permissões no SQL Server

O login configurado no agente precisa da permissão VIEW SERVER STATE para consultar as DMVs de monitoramento. Veja o script completo na seção C — Permissões SQL Server do apêndice técnico.

Primeiros Passos

Instalação do Agente

Passo 1 — Executar o instalador

Execute codeDB-Agent-Setup.exe como administrador. O instalador copiará os arquivos para C:\codeDB-Agent\, instalará o gerenciador de serviço NSSM e registrará o agente como serviço Windows com inicialização automática.

Passo 2 — Gerenciador de Instâncias (GUI)

Ao final da instalação, o codeDB Agent Config é aberto automaticamente. Nele você irá:

• Inserir o Agent Token gerado no portal
• Selecionar a instância SQL Server (servidor e porta)
• Escolher o tipo de autenticação (Windows Auth ou SQL Login)
• Inserir usuário/senha do SQL (armazenados com criptografia AES)
• Clicar em Salvar e Iniciar Serviço

Passo 3 — Verificar o serviço

Após salvar, o serviço codeDB-Agent aparece no Gerenciador de Serviços do Windows (services.msc) com status Em execução. O serviço reinicia automaticamente em caso de falha.

Adicionando mais instâncias SQL

Se o servidor hospedar mais de uma instância SQL Server, abra o codeDB Agent Config novamente, clique em + Adicionar Instância e insira o token de um segundo ambiente criado no portal. Cada ambiente monitora uma instância separada.

Usando o Dashboard

Visão geral

A tela principal do portal exibe um card por instância monitorada com o Health Score (0–100), contador de alertas ativos e hora da última coleta. A cor indica a situação atual:

Detalhes de uma instância — 9 abas

Clique em qualquer card para abrir o painel de instância com 9 abas, atualizadas automaticamente a cada 60 segundos:

Query Intelligence

Disponível na aba 9 — Query Intelligence dentro do painel de uma instância. Identifica automaticamente as consultas SQL que merecem atenção usando regras determinísticas (sem IA) — não armazena todas as queries, apenas as que satisfazem critérios de relevância.

Os dados são agregados diariamente às 01:50 BRT e ficam disponíveis em quatro sub-abas:

Regras QRULE_* — o que cada uma detecta

As regras QRULE_004 e QRULE_005 exigem histórico mínimo (7 e 14 dias, respectivamente) — elas ativam automaticamente conforme os dados acumulam, sem nenhuma configuração necessária.

Impact Score (0–100)

O Impact Score é calculado diariamente para cada query com base em 6 dimensões ponderadas:

O score é relativo ao ambiente — não há threshold fixo. Queries com score alto são as que mais consomem recursos em comparação com as demais queries da mesma instância. Clique em qualquer query para abrir um drawer com o gráfico de tendência (Avg CPU e Max CPU nos últimos 14 dias) e o texto SQL da query.

Incidentes

Acesse em Incidentes no menu lateral. Esta tela centraliza, em três abas, toda a inteligência sobre problemas passados e recorrentes em todas as instâncias do ambiente.

Dashboard Gerencial

Acesse em Executive no menu lateral. Visão consolidada de saúde de todos os ambientes — projetada para gestores e líderes de TI que precisam de uma leitura rápida sem entrar em cada instância individualmente.

O codeDB separa Disponibilidade de Cobertura de Monitoramento: uma indisponibilidade da própria plataforma codeDB nunca reduz a disponibilidade do seu SQL Server. Consulte a seção Disponibilidade e Cobertura para entender o modelo de estados UP / DOWN / UNKNOWN.

Relatórios Semanais

Acesse em Relatórios no menu lateral. Todo domingo à noite o codeDB gera e envia automaticamente um relatório por e-mail para os responsáveis do ambiente. O e-mail chega segunda-feira às 08h (BRT) e resume toda a semana.

Na página de Relatórios você também pode disparar o envio manualmente e consultar o histórico de envios anteriores com data, destinatário e status (enviado / falhou / ignorado).

Insights Inteligentes

Acesse em Insights no menu lateral. Lista centralizada das recomendações operacionais geradas diariamente pelo codeDB para todas as instâncias do ambiente, com base em 14 regras que cruzam métricas históricas, tendências e padrões de uso.

Filtre por ambiente e severidade. Clique em qualquer insight para abrir diretamente o painel da instância afetada.

Modo TV / Wall

Disponível dentro do painel de uma instância, no ícone de TV no canto superior. O Modo TV exibe o monitoramento em tela cheia, pensado para NOCs, war rooms e monitores em salas de operação — atualiza automaticamente a cada 30 segundos sem interação.

Os widgets são configuráveis: ative, desative e reordene pelo painel de configurações (ícone de engrenagem). Preferências ficam salvas no perfil. O gauge do Health Score muda de cor conforme o status: verde (≥ 80), amarelo (50–79), laranja (30–49) e vermelho (< 30).

Segurança e LGPD

Autenticação em dois fatores (MFA)

O codeDB suporta TOTP (Time-based One-Time Password) para proteger sua conta com um segundo fator além da senha. Use Google Authenticator, Authy, Microsoft Authenticator ou qualquer app compatível com TOTP.

O secret TOTP é armazenado criptografado no banco de dados — nunca em texto claro. Para desativar o MFA, acesse o mesmo menu e informe a senha e um código válido.

Proteção de tokens e chaves

Trate tokens e API Keys como senhas: não inclua em código-fonte, repositórios Git ou logs. Use variáveis de ambiente ou cofres de secrets (AWS Secrets Manager, Azure Key Vault, etc.).

Privacidade de queries coletadas

Cada ambiente tem um modo de visibilidade para o texto das queries SQL coletadas pelo agente. Configure em Configurações → card do ambiente → Privacidade de Queries:

Seus direitos — LGPD Art. 18

Para detalhes completos consulte a Política de Privacidade e a Política de Cookies.

Termos de Uso e modelo de contrato

O codeDB usa o modelo click-wrap: ao clicar em "Criar Conta", o usuário aceita os Termos de Uso e a Política de Privacidade. Não há contrato separado para assinar. O aceite é registrado automaticamente no momento do cadastro, vinculado ao usuário e ao workspace.

Na primeira visita ao portal, um banner de cookies permite aceitar, recusar ou configurar as preferências de rastreamento. O consentimento é registrado no backend com timestamp e IP anonimizado. Para organizações que exigem MSA, DPA ou SLA assinado, entre em contato com o suporte — o aceite click-wrap atende à maioria dos casos.

Health Score

O Health Score é um número de 0 a 100 que resume a saúde da instância SQL Server em um único valor, calculado a cada 5 minutos.

O que compõe o score

• PLE (Page Life Expectancy) — principal indicador de pressão de memória. Valores abaixo de 300s penalizam significativamente o score.
• Buffer Cache Hit Ratio — abaixo de 95% indica leituras físicas frequentes do disco.
• TempDB — uso acima de 85% começa a penalizar o score.
• Bloqueios ativos — penalidade proporcional ao número de sessões bloqueadas.
• Jobs com falha — cada SQL Agent Job com falha reduz o score.
• Latência de I/O — arquivos com latência acima de 50ms indicam gargalo de disco.
• Wait stats dominantes — tipos de espera com mais de 40% do tempo total.
• Espaço em disco — volume com menos de 20% livre desconta 10 pts; menos de 10% desconta 25 pts (apenas o volume mais crítico penaliza).
• Crescimento súbito de log — arquivo .ldf crescendo ≥ 500 MB em um ciclo (~5 min) desconta 10 pts; ≥ 2.000 MB desconta 20 pts.

Quando o Health Score cai 10 ou mais pontos em dois snapshots consecutivos (~10 minutos), o sistema detecta automaticamente um incidente e inicia a análise de causa raiz.

Análise de Incidentes

A Análise de Incidentes (Root Cause Timeline) é a funcionalidade central do codeDB. Em vez de alertas isolados, ela constrói a narrativa completa de um incidente: o que aconteceu, em que sequência, qual a causa provável e o que fazer.

Acesse em Aba 7 — Análise de Incidentes dentro do painel de uma instância, ou em Incidentes no menu lateral para a visão global de todas as instâncias.

Como incidentes são detectados e encerrados

Fechamento refinado: oscilações pequenas (≤ 4 pontos) no Health Score não reiniciam o contador de estabilidade. Apenas quedas de ≥ 5 pontos recomeçam a contagem — evitando que ruído de coleta prolongue artificialmente um incidente que já foi resolvido.

Tipos de evento na timeline

Agrupamento por hora: quando um incidente tem mais de 20 eventos, a timeline os agrupa automaticamente em blocos de 1 hora — por exemplo: "09/06 09:00–10:00 — 12 críticos, 8 atenção". Cada grupo é colapsável, permitindo navegar rapidamente em incidentes de longa duração sem perder o detalhe de nenhum evento.

Os 6 tipos de causa raiz

O codeDB classifica automaticamente a causa raiz entre 6 tipos. Expanda cada um para ver os sinais que confirmam o diagnóstico e as ações recomendadas.

Nível de confiança da causa raiz

Padrões Recorrentes e Correlações

Padrões Recorrentes

Disponível em Incidentes → aba Padrões Recorrentes. O codeDB analisa os últimos 90 dias e identifica o mesmo tipo de problema acontecendo no mesmo dia da semana e no mesmo bloco de horário — sinal de uma causa sistêmica recorrente (ex: job de manutenção semanal, pico de carga diário).

Exemplo: Segunda | 00–04h | Pressão de Memória | 4 ocorrências | −18 pts | 45 min — toda segunda de madrugada há pressão de memória por ~45 min. Hipótese provável: job de rebuild de índices consumindo muita memória. Ação: revisar o job ou ajustar MAX MEMORY GRANT.

Correlações entre Instâncias

Disponível em Incidentes → aba Correlações. Quando múltiplas instâncias do mesmo ambiente sofrem incidentes em um intervalo de 15 minutos entre si, o codeDB as agrupa como incidentes correlacionados — sinal de uma causa compartilhada de infraestrutura.

API Pública

O codeDB disponibiliza uma API REST pública que permite integrar dados de incidentes e status das instâncias com ferramentas externas como Zabbix, Microsoft Teams, Grafana, ServiceNow e qualquer sistema que faça chamadas HTTP.

Criando uma API Key

Endpoints disponíveis

Exemplos de uso

curl (Linux/macOS):

# Listar incidentes das últimas 24h
curl -s -H "X-API-Key: cdb_v1_SUA_CHAVE" \
  "https://<api>/api/v1/incidents?days=1"

# Verificar instâncias ativas
curl -s -H "X-API-Key: cdb_v1_SUA_CHAVE" \
  "https://<api>/api/v1/instances"

PowerShell:

$headers = @{ "X-API-Key" = "cdb_v1_SUA_CHAVE" }
$resp = Invoke-RestMethod -Uri "https://<api>/api/v1/incidents?days=1" -Headers $headers

$ativos = ($resp.incidents | Where-Object { $_.status -eq "active" }).Count
Write-Host "Incidentes ativos: $ativos"

$resp.incidents | Where-Object { $_.status -eq "active" } | ForEach-Object {
  $rc = $_.root_cause
  Write-Warning "$($rc.label) | Queda: $($_.max_health_drop) pts | Conf: $($rc.confidence)"
}

Integração com Zabbix (External Check):

Crie o script /usr/lib/zabbix/externalscripts/check_codedb.py no servidor Zabbix, depois crie itens e triggers com base nos valores retornados:

#!/usr/bin/env python3
# check_codedb.py <metric>
# Métricas: active_incidents | incidents_today | max_health_drop | agent_offline_count
import sys, json, urllib.request

API_BASE = "https://<api>"
API_KEY  = "cdb_v1_SUA_CHAVE"

def api_get(path):
    req = urllib.request.Request(f"{API_BASE}{path}", headers={"X-API-Key": API_KEY})
    with urllib.request.urlopen(req, timeout=10) as r:
        return json.loads(r.read())

metric = sys.argv[1] if len(sys.argv) > 1 else "active_incidents"
data = api_get("/api/v1/incidents?days=1")
incidents = data.get("incidents", [])

if metric == "active_incidents":
    print(sum(1 for i in incidents if i["status"] == "active"))
elif metric == "incidents_today":
    print(len(incidents))
elif metric == "max_health_drop":
    drops = [i["max_health_drop"] for i in incidents if i["max_health_drop"]]
    print(max(drops) if drops else 0)

No Zabbix, crie um item do tipo External check com chave check_codedb.py[active_incidents] e uma trigger: last(...)>0 para alertar quando houver incidentes ativos.

Integração com Microsoft Teams:

Configure um Incoming Webhook no canal do Teams e use o script abaixo agendado via cron ou Task Scheduler (a cada 5 min):

#!/usr/bin/env python3
import json, urllib.request
from datetime import datetime, timezone

API_BASE      = "https://<api>"
API_KEY       = "cdb_v1_SUA_CHAVE"
TEAMS_WEBHOOK = "https://outlook.office.com/webhook/SEU_WEBHOOK"

def api_get(path):
    req = urllib.request.Request(f"{API_BASE}{path}", headers={"X-API-Key": API_KEY})
    with urllib.request.urlopen(req, timeout=10) as r:
        return json.loads(r.read())

data = api_get("/api/v1/incidents?days=1")
for inc in data["incidents"]:
    if inc["status"] != "active":
        continue
    rc = inc.get("root_cause") or {}
    card = {
        "@type": "MessageCard",
        "themeColor": "FF0000",
        "summary": f"codeDB: {rc.get('label', 'Incidente')}",
        "sections": [{
            "activityTitle": f"Incidente Detectado — {rc.get('label','')}",
            "activitySubtitle": f"Confiança: {rc.get('confidence','')} | Queda: -{inc['max_health_drop']} pts",
            "facts": [{"name": "Recomendação", "value": rc.get("recommendation", "")}]
        }]
    }
    req = urllib.request.Request(
        TEAMS_WEBHOOK, json.dumps(card).encode(), {"Content-Type": "application/json"}
    )
    urllib.request.urlopen(req, timeout=10)

Membros e Colaboração

O codeDB suporta múltiplos usuários por workspace (tenant). O owner pode convidar colegas para colaborar, atribuindo a cada um uma role com nível de acesso específico. Todos os membros compartilham os mesmos ambientes, instâncias e dados de monitoramento da organização.

Roles disponíveis

Convidar um membro

Fluxo de aceite detalhado

A página de aceite de convite (/invite/{token}) funciona em três cenários:

• Usuário já logado com o e-mail correto: botão "Aceitar convite" visível — um clique vincula ao workspace e redireciona ao dashboard.
• Usuário não logado: dois botões — "Entrar na minha conta" (vai para login com ?redirect=/invite/{token}) e "Criar conta nova" (vai para registro com e-mail pré-preenchido).
• Usuário logado com e-mail diferente: alerta informando que o convite é para outro e-mail — é necessário sair e entrar com o e-mail correto.

Usuário com múltiplos workspaces

Um mesmo e-mail pode pertencer a mais de um workspace (ex: funcionário que monitora infraestrutura de dois clientes diferentes). Neste caso, ao fazer login, o codeDB exibe um seletor de workspace. O usuário escolhe em qual workspace quer entrar e pode trocar a qualquer momento refazendo o login.

Gerenciar membros existentes

Na tela Membros, o owner pode:

• Alterar a role de qualquer membro (ícone de lápis)
• Remover um membro — o usuário perde o acesso imediatamente
• Cancelar um convite pendente — o link de convite é invalidado

O owner não pode remover a si mesmo nem alterar sua própria role. Convites são exibidos com o badge Aguardando aceite enquanto pendentes.

Limite de membros por plano

O número máximo de membros (incluindo convites pendentes) depende do plano contratado. Ao atingir o limite, novos convites são bloqueados com sugestão de upgrade. Administradores codeDB podem conceder limites customizados via painel administrativo.

Configurando Alertas

As regras de alerta são configuradas em Configurações → Regras de Alerta. Quando uma condição é atingida, um e-mail é enviado para os membros do ambiente.

Tipos de regras disponíveis

Supressão de alertas

Para evitar spam de e-mail em situações persistentes, o codeDB aplica supressão automática: após o primeiro disparo, novos e-mails são enviados somente após um número configurável de ciclos de coleta consecutivos sem melhora.

Planos e Assinatura

Trial gratuito

Todo novo cadastro recebe 30 dias de trial gratuito com acesso completo ao plano Professional — sem cartão de crédito, sem compromisso. Ao final do trial, escolha um plano para continuar.

Planos disponíveis

Todos os planos pagos oferecem desconto de ~20% na cobrança anual. O gerenciamento de pagamento, troca de plano e histórico de faturas está disponível em Faturamento no portal.

Cancelamento e dados

Você pode cancelar a assinatura a qualquer momento pelo portal. Após o cancelamento, os dados ficam retidos por 30 dias. Durante esse período é possível reativar a assinatura sem perda de histórico. Após 30 dias, os dados são removidos permanentemente.

Regras de Uso

O que o agente coleta

O agente coleta exclusivamente métricas de desempenho e estrutura do SQL Server via DMVs (Dynamic Management Views). Não são coletados dados de negócio armazenados nas tabelas do banco (registros de clientes, transações, etc.).

Dados coletados: uso de TempDB, sessões ativas (com texto da query em execução), estatísticas de I/O, memória, waits, SQL Agent Jobs, detalhes de conexão e estatísticas de queries (query plan hash + SQL text resumido).

Armazenamento e retenção

Os snapshots são armazenados em banco de dados PostgreSQL hospedado na nuvem e retidos pelo período definido no plano contratado (7, 30 ou 90 dias). Após esse período os dados são removidos automaticamente.

Privacidade e LGPD

Os dados de identificação pessoal coletados no cadastro (nome, e-mail, CPF/CNPJ, empresa) são usados exclusivamente para gestão da conta e faturamento. O codeDB não compartilha dados pessoais com terceiros, exceto processadores de pagamento (Stripe).

Para exercer seus direitos de titularidade (LGPD Art. 18): exportação de dados em Configurações → Exportar dados; exclusão de conta em Perfil → Excluir minha conta. Recomendamos ativar o MFA (Perfil → Segurança) para proteção adicional. Consulte a Política de Privacidade para detalhes completos.

Responsabilidades do usuário

• Manter o agente atualizado para a versão atual recomendada
• Guardar com segurança o token de agente (ele tem acesso de escrita aos snapshots)
• Não utilizar a plataforma para monitorar sistemas sem autorização do proprietário
• Não fazer engenharia reversa do agente ou da API
• Respeitar os limites de instâncias e ambientes do plano contratado

Disponibilidade e Cobertura de Monitoramento

O codeDB calcula a disponibilidade dos seus ambientes de forma independente da sua própria infraestrutura. Uma eventual indisponibilidade da plataforma codeDB — por exemplo, o banco de dados do SaaS offline — nunca reduz a disponibilidade do seu SQL Server.

As duas métricas

Modelo de estados (UP / DOWN / UNKNOWN)

A cada ciclo de coleta, o codeDB classifica o período entre snapshots em um de cinco estados:

Como a reinicialização é detectada

O agente envia em cada snapshot o valor de instance_start_time — o timestamp de quando o SQL Server foi iniciado. Quando o snapshot seguinte chega com um instance_start_time mais recente, o sistema confirma que houve reinicialização e registra o período como DOWN. Ausência de dados nunca é suficiente para decrementar o SLA.

Exemplo prático — 30 dias

Resultado: Disponibilidade = 99,97% · Cobertura = 98,61%. O codeDB foi incapaz de observar o ambiente em 1,39% do tempo — mas isso não penaliza o SLA do cliente.

Janelas de Manutenção

As Janelas de Manutenção permitem registrar antecipadamente períodos em que um ambiente ou instância ficará offline de forma planejada — patches, backups, restart agendado, upgrades de SO, entre outros.

O que acontece durante uma janela

Como criar uma janela

Boas práticas

• Crie a janela antes da manutenção para suprimir alertas automaticamente
• Adicione margem de 30 min antes e depois do horário previsto
• Use o campo Motivo para facilitar auditoria e contexto no relatório semanal
• Para remover uma janela histórica, os períodos voltam a ser calculados normalmente na próxima consulta

-- 1. Permissão para consultar as DMVs de monitoramento
USE master;
GRANT VIEW SERVER STATE TO [seu_login_aqui];

-- 2. Permissão para leitura do status dos SQL Agent Jobs
USE msdb;
ALTER ROLE SQLAgentOperatorRole ADD MEMBER [seu_login_aqui];

-- 3. (Opcional) Se usar banco DBAMonitor criado pelo instalador
USE DBAMonitor;
ALTER ROLE db_datareader ADD MEMBER [seu_login_aqui];
ALTER ROLE db_datawriter ADD MEMBER [seu_login_aqui];

# Instância 1 (principal — sem prefixo)
AGENT_TOKEN=token_do_ambiente_producao
DB_SERVER=SERVIDOR\SQL2019
DB_WINDOWS_AUTH=true

# Instância 2
INSTANCE_2_AGENT_TOKEN=token_do_ambiente_homologacao
INSTANCE_2_DB_SERVER=SERVIDOR\SQL2016
INSTANCE_2_DB_WINDOWS_AUTH=false
INSTANCE_2_DB_USER=monitor_user
INSTANCE_2_DB_PASSWORD=ENC:gAAAAA...

// Exemplo de resposta
{
  "incidents": [
    {
      "id": "a1b2c3d4-...",
      "instance_id": "e5f6g7h8-...",
      "started_at": "2026-06-09T22:34:00+00:00",
      "resolved_at": "2026-06-09T23:02:00+00:00",
      "duration_minutes": 28,
      "status": "resolved",          // "active" | "resolved"
      "max_health_drop": 18,
      "root_cause": {
        "type": "memory_pressure",
        "label": "Pressão de Memória",
        "confidence": "high",        // "high" | "medium" | "low"
        "recommendation": "Verificar MAX SERVER MEMORY..."
      }
    }
  ],
  "total": 1,
  "period_days": 7
}

// Exemplo de resposta
{
  "instances": [
    {
      "id": "e5f6g7h8-...",
      "name": "PROD-SQL-01",
      "server_host": "192.168.1.10",
      "is_active": true,
      "agent_last_seen": "2026-06-10T14:55:00+00:00"
    }
  ],
  "total": 1
}