Documentação codeDB

O que é o codeDB

O codeDB é uma plataforma SaaS de monitoramento de bancos de dados (SQL Server e PostgreSQL) que coleta métricas em tempo real por meio de um agente instalado na sua infraestrutura 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

Instalando no Windows (SQL Server ou PostgreSQL)

Instalando no Linux ou em container (PostgreSQL)

Nenhum dos dois exige driver de conexão: o agente já traz o necessário para PostgreSQL (psycopg) embutido no binário.

Permissões no banco

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. No PostgreSQL, o usuário de monitoração recebe o papel pg_monitor — nunca superusuário; veja C.1 — PostgreSQL.

Primeiros Passos

Formas de entrar no codeDB

Você pode criar sua conta e fazer login de três formas. Todas levam ao mesmo dashboard — a diferença é só como sua identidade é confirmada.

Entrando com Google ou Microsoft

Na tela de login (/auth/login) ou cadastro (/auth/register), clique em Continuar com Google ou Continuar com Microsoft. Você é redirecionado para autenticar direto com o provedor — o codeDB nunca vê sua senha.

• Primeiro acesso: se for a primeira vez que esse e-mail entra no codeDB, você completa um cadastro rápido (nome da empresa e CPF/CNPJ) e ganha os 30 dias de trial, igual ao cadastro tradicional.
• Conta já existente com o mesmo e-mail: o login social é vinculado automaticamente à sua conta (desde que o e-mail seja confirmado pelo provedor) — você continua acessando o mesmo workspace de sempre.
• Login Microsoft aceita apenas contas corporativas (Microsoft 365 / Azure AD) — contas pessoais (outlook.com, hotmail.com) não são aceitas.

Instalação do Agente

O agente existe em quatro formatos, dependendo do sistema operacional e do banco monitorado. SQL Server só é monitorado pelo agente Windows — os builds Linux e container não trazem driver ODBC, então recusam DB_ENGINE=sqlserver cedo, com mensagem clara. PostgreSQL pode ser monitorado por qualquer um dos quatro.

Qual formato usar

Os quatro formatos são baixados na mesma tela do portal — Configurações → Download do Agente — que mostra só as opções compatíveis com o engine do ambiente escolhido.

Onde cada formato guarda a configuração

As variáveis CODEDB_CONFIG_DIR e CODEDB_STATE_DIR trocam essas pastas por outras, se precisar de um layout diferente do padrão.

Windows — Passo 1: executar o instalador

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

Instalação MSP (um Agente para vários Ambientes)

Se você é uma empresa MSP e já criou um Agente na tela Agentes do portal, vinculando-o a um ou mais Ambientes, marque a opção "Esta é uma instalação MSP" na tela de pasta de instalação. A tela seguinte pede só o Token do Agente (enrollment) — gerado na tela Agentes, não o token de Ambiente — e, depois de validado, mostra a lista de Ambientes que essa instalação vai gerenciar antes de continuar.

Se o Agente ainda não tiver nenhum Ambiente vinculado, o instalador bloqueia e pede para associar um Ambiente ao Agente no portal antes de prosseguir. Deixe a opção desmarcada (padrão) se você não é MSP ou está instalando do jeito tradicional — o fluxo continua idêntico ao Passo 2 abaixo.

Windows — 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

Windows — 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.

Linux — pacote .deb (Debian, Ubuntu)

O caminho mais direto em distros da família Debian/Ubuntu com systemd:

curl -fsSLO <url do .deb — copiado de Configurações → Download do Agente>
sudo apt install ./codedb-agent_<versão>_amd64.deb
sudo nano /etc/codedb-agent/Config.env      # cole o token do ambiente e os dados de conexão
sudo systemctl start codedb-agent
journalctl -u codedb-agent -f               # acompanhar o log em tempo real

Linux — tarball universal

Para qualquer outra distro com glibc 2.31 ou superior (RHEL/Rocky 9+, por exemplo):

curl -fsSL <url do tarball — copiado de Configurações → Download do Agente> | tar xz
sudo ./codedb-agent/install.sh              # idempotente: rodar de novo atualiza

Os dois formatos criam o usuário de sistema codedb-agent, dono do binário, da configuração e do estado. Se a senha for colada em texto plano no Config.env, o próprio agente a cifra na primeira execução — não precisa cifrar à mão.

Container

docker run -d --name codedb-agent --restart unless-stopped \
  -e CODEDB_API_URL=https://api.codedb.com.br \
  -e AGENT_TOKEN_FILE=/run/secrets/agent_token \
  -e DB_ENGINE=postgres -e DB_SERVER=<host> -e DB_PORT=5432 -e DB_DATABASE=postgres \
  -e DB_USERNAME=codedb_monitor -e DB_PASSWORD_FILE=/run/secrets/db_password \
  -v codedb-agent-state:/var/lib/codedb-agent \
  -v /caminho/dos/secrets:/run/secrets:ro \
  <imagem indicada em Configurações → Download do Agente>

Segredos entram só por arquivo (sufixo _FILE na variável) — uma variável de ambiente comum apareceria em docker inspect de qualquer pessoa com acesso ao host. O container roda com usuário sem privilégio (uid 10001, não root) e não é o servidor do banco: CPU, memória e disco ficam indisponíveis, e a Visão Geral explica isso no lugar de mostrar zero. O volume guarda o spool de sondas e esperas — recriar o container não perde o que foi coletado enquanto a API estava fora do ar.

O container não se atualiza sozinho: quando sair uma versão nova, troque a tag da imagem e recrie o container.

O que o agente faz depois de instalado

A partir da versão 1.19.2 o agente executa dois trabalhos independentes, em ritmos diferentes:

A sonda roda em thread separada: ela não espera a coleta de métricas terminar, e uma coleta lenta não atrasa a medição de disponibilidade. Se a instância estiver fora do ar, a coleta de métricas falha e o agente registra isso explicitamente, em vez de simplesmente ficar em silêncio.

Armazenamento local das sondas

No Windows, as medições ficam em C:\Program Files\codeDB Agent\probe\; no Linux, em /var/lib/codedb-agent/probe/; no container, dentro do volume montado. Em todos os casos: uma subpasta por instância, em arquivos de texto (uma linha por sonda), com permissão restrita ao dono do processo (SYSTEM e Administradores no Windows; usuário codedb-agent no Linux) — a mesma proteção do Config.env.

Para desativar a sondagem, defina PROBE_ENABLED=false no Config.env. O intervalo é ajustável por PROBE_INTERVAL_SEC (padrão 15).

Adicionando mais instâncias SQL

Se o mesmo servidor hospedar mais de uma instância SQL Server nomeada (ex: SERVIDOR\DEV e SERVIDOR\PROD), abra o codeDB Agent Config novamente, clique em + Adicionar Instância e reutilize o token do mesmo ambiente — todas as instâncias do mesmo servidor entram no mesmo ambiente. Só use o token de um segundo ambiente se estiver monitorando um servidor diferente (ver seção abaixo).

Agent language / Idioma do Gerenciador de Instâncias

The codeDB Agent Config GUI auto-detects your Windows display language (Portuguese or English). To force a specific language regardless of the Windows locale, set the environment variable CODEDB_LANG=en (or CODEDB_LANG=pt-BR) before launching codeDB-Agent-Config.exe. The Windows service itself (codeDB-Agent.exe) has no UI — its logs stay in English regardless of locale.

Ambientes e servidores

Cada ambiente representa um servidor SQL Server ou, no PostgreSQL, um cluster (os databases dele aparecem como dimensão da métrica, não como ambientes separados). Todas as instâncias adicionadas a um ambiente precisam estar nesse mesmo servidor/cluster — o portal identifica automaticamente qual servidor está vinculado ao ambiente assim que a primeira instância envia dados, e passa a exibi-lo no card do ambiente. Para monitorar um segundo servidor, crie um segundo ambiente (isso consome um slot adicional de ambiente do seu plano).

Se você tentar adicionar uma instância de um servidor diferente ao mesmo ambiente, o codeDB recusa o cadastro e sugere criar um novo ambiente.

Usando o Dashboard

Idioma do portal

O portal está disponível em Português (Brasil) e English. Troque o idioma pelos botões PT/EN no rodapé do menu lateral, ou em Meu Perfil → Preferências. A preferência é salva na sua conta e aplicada automaticamente no próximo login.

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 — 10 abas

Clique em qualquer card para abrir o painel de instância com 10 abas, na ordem "o que está acontecendo agora → onde estão os dados → operação → inteligência derivada", atualizadas automaticamente a cada 60 segundos. A tabela abaixo descreve o SQL Server — para o que muda no PostgreSQL, veja a tabela seguinte.

O que muda no PostgreSQL

O mesmo painel de 10 abas existe para ambientes PostgreSQL — só o conteúdo de cada aba muda para refletir os conceitos do engine. Abas sem equivalente ainda ficam escondidas (não aparece aba vazia): é o caso hoje de 2 — Performance, cujo equivalente (cache hit, I/O por arquivo) já está coberto dentro da própria 1 — Visão Geral.

Query Intelligence

Disponível na aba 4 — 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.

No PostgreSQL

A mesma aba existe, alimentada por pg_stat_statements em vez das DMVs — sem a extensão instalada, a aba mostra o passo a passo para habilitar (apêndice C.1) em vez de ficar vazia. Como o Postgres não separa CPU de tempo total gasto por query (total_exec_time), o Impact Score redistribui o peso de CPU para tempo decorrido. No lugar de Missing Indexes, a sub-aba mostra varreduras sequenciais dominantes — tabelas onde o otimizador prefereSeq Scan a um índice, sem sugestão de DDL pronta (o Postgres não gera essa recomendação como o SQL Server gera).

Tabelas e Índices

Disponível na aba 5 — Tabelas e Índices (planos Professional e Business). Responde às perguntas que um DBA faz todo dia sem precisar rodar scripts: quais tabelas estão crescendo, quais índices estão fragmentados e quais índices existem mas ninguém usa.

Como é coletado: uma vez por dia, na madrugada do servidor SQL (janela 03:00–05:00 por padrão; ajustável com SCHEMA_INVENTORY_HOUR noConfig.env do agente). A fragmentação usa dm_db_index_physical_statsem modo LIMITED, apenas nos índices já selecionados e com mais de 1.000 páginas, com timeout por índice — por isso a coleta nunca roda em horário comercial. Requer agente1.20.0 ou superior; a coluna de crescimento fica vazia até existir histórico.

Os dados alimentam três insights automáticos — tabela em crescimento acelerado,índices grandes com fragmentação ≥ 80% e índices sem uso — e duas seções do relatório semanal.

No PostgreSQL

A mesma aba existe, com bloat no lugar de fragmentação — medido com pgstattuple quando a extensão está instalada, ou estimado (com um selo indicando isso) quando não está. O uso de índice vem de idx_scan em vez de seeks/scans/lookups, e a coluna de sequência (nextval) ocupa o lugar do IDENTITY do SQL Server. A coleta também roda uma vez por dia, agendável por ambiente (padrão: madrugada, com orçamento de tempo configurável) — nunca em horário comercial. Insights próprios do engine (autovacuum parado numa tabela, risco de XID wraparound) aparecem na aba 8 — Insights Inteligentes.

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 Gerencial no menu lateral. É o panorama da empresa inteira — todos os ambientes e instâncias (SQL Server e PostgreSQL) numa única tela, pensada para gestores e líderes de TI entenderem a situação em poucos segundos e, depois, aprofundarem onde for preciso. Um card "Gerencial do mês" na tela inicial leva até ela.

Como os dados são gerados: toda madrugada o codeDB consolida o dia anterior de cada instância (conexões e bloqueios por hora, esperas, latência de disco, volumes). O Gerencial lê só esses consolidados — abrir a tela não pesa no seu SQL Server nem no monitoramento, e o histórico continua disponível mesmo depois do prazo de retenção das métricas detalhadas do seu plano.

Filtros e períodos

O que a tela mostra

Cada bloco traz uma frase-resumo gerada automaticamente (ex.: "45% dos incidentes aconteceram de madrugada e a causa mais comum é gargalo de I/O"), para a leitura não depender de interpretar o gráfico.

Relatório PDF

O botão Relatório PDF gera um relatório executivo em A4, pronto para apresentar em reunião ou enviar ao cliente. Escolha os últimos 30, 60 ou 90 dias ou um mês fechado(comparado com o mês anterior). O relatório tem três partes:

Clientes MSP com marca própria recebem o relatório com o próprio logo. O owner também pode gerar uma versão anonimizada (instâncias viram "Servidor A, B…", sem nomes de bancos, tabelas ou queries) — útil para apresentar um caso sem expor o ambiente; toda geração anonimizada fica registrada na auditoria.

Exportar dados

Exportar HTML gera um arquivo interativo (gráficos com tooltip e chips de instância) que abre em qualquer navegador. Exportar Excel gera uma planilha com uma aba por painel, com números como número — pronta para filtros, gráficos próprios ou BI.

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 (semanal e mensal)

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).

Relatório mensal do Gerencial

Nos planos Professional e Business, todo dia 1º o codeDB gera automaticamente o Relatório PDF do Gerencial do mês anterior e envia ao owner um e-mail com o link. Os relatórios ficam na seção Relatórios mensais do Gerencial desta página, com os dados congelados — o relatório de setembro mostra sempre o que aconteceu em setembro. O owner ou um admin pode desligar o e-mail em Configurações; o relatório continua sendo gerado e fica disponível para download.

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.

Verificação de e-mail no cadastro

Ao criar conta com e-mail e senha, o codeDB envia um código de 6 dígitos para o e-mail informado, na própria tela de cadastro. O código expira em 20 minutos e permite até 5 tentativas antes de exigir um reenvio. Enquanto o e-mail não é confirmado, o login fica bloqueado — se você fechar a aba antes de confirmar, o próximo login pede o código de novo.

Contas criadas por convite de um membro do workspace ou por Google/Microsoft não passam por essa etapa — o e-mail já é considerado confiável nesses casos.

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 em um único valor, calculado a cada 5 minutos — mesma escala nos dois engines, mas cada um penaliza sinais diferentes (a lista de SQL Server vem primeiro; PostgreSQL logo abaixo).

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.

O que compõe o score no PostgreSQL

• Cache hit — ocupa o lugar do PLE (não é "PLE do Postgres": o mecanismo de cache é outro). Abaixo de 95% desconta 10 pts; abaixo de 90% desconta 20 pts.
• Query em execução há mais de 30/60 min — mesmos limiares e pesos do SQL Server.
• Bloqueios ativos — mesma regra do SQL Server, via pg_blocking_pids().
• Espaço em disco — idêntico ao SQL Server: só o volume mais crítico penaliza.
• Saturação de conexões — sem equivalente no SQL Server. 80% de max_connections desconta 10 pts; 95% desconta 20 pts — esgotar as conexões derruba a aplicação inteira.
• Idade de XID (risco de wraparound) — sem equivalente no SQL Server, e o fator de maior peso do perfil: 75% de autovacuum_freeze_max_age desconta 15 pts; 90% desconta 30 pts. Chegar ao wraparound põe o cluster em somente-leitura.
• Arquivamento de WAL falhando — ocupa o lugar do crescimento súbito de log: qualquer falha do archiver desconta 20 pts.
• Lag de replicação — acima de 1 GB desconta 10 pts.
• Autovacuum pendente — uma ou mais tabelas aguardando desconta 5 pts; 10 ou mais tabelas com linhas mortas acumuladas desconta 10 pts.
• Spill de arquivos temporários — mais de 100 MB no ciclo desconta 5 pts; mais de 1 GB desconta 15 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 — nos dois engines.

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.

Acesso automático via Microsoft Entra ID (SSO organizacional)

Alternativa ao convite individual: se sua empresa usa Microsoft 365 / Azure AD, o owner do workspace pode vincular o diretório da organização ao codeDB. A partir daí, qualquer colaborador com uma conta daquele diretório entra automaticamente no workspace ao clicar em Continuar com Microsoft — sem precisar de um convite individual por e-mail.

O owner pode desvincular o diretório a qualquer momento — membros que já entraram continuam com acesso normalmente, só param de entrar automaticamente novos colaboradores.

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 produto (equivalente ao plano Business) — 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 na cobrança anual. Quanto menor o intervalo de coleta, mais cedo os problemas aparecem no dashboard e nos alertas.

Recursos por plano

Monitoramento base — disponível em todos os planos:

Inteligência avançada — Professional e Business:

Enterprise — exclusivo Business:

Limites por plano:

Recursos fora do seu plano aparecem no portal com um cadeado — ao clicar, você vê qual plano os libera. O gerenciamento de pagamento, troca de plano e histórico de faturas está em Cobrança no portal.

O que o agente coleta por plano

Base (todos os planos): uso e contenção de TempDB, indicadores de performance (Page Life Expectancy, Buffer Cache Hit Ratio, uptime, pressão de memória), Top Waits acumulados, estado de SQL Agent Jobs e Backups, além de sessões e bloqueios ativos com o texto da query em execução. Todo o monitoramento base roda via DMVs, com custo desprezível.

Professional e Business: a coleta passa a incluir o Query Intelligence (8 regras que identificam queries pesadas e geram DDL de criação de índice automaticamente), a detecção de anomalias por baseline histórico (Z-score sobre as métricas coletadas) e os Insights Inteligentes (recomendações automáticas derivadas dos snapshots).

Business (Enterprise): adiciona o Root Cause Timeline (correlação de incidentes ao longo do tempo), o Cloud Intelligence (métricas nativas de Azure SQL Database e AWS RDS) e os canais de alerta via Slack e Webhook, com intervalo de coleta reduzido para 1 minuto.

O que acontece se eu mudar de plano?

Upgrade (plano maior): vale na hora. Novos recursos, abas e limites são liberados imediatamente.

Downgrade (plano menor): se o seu uso atual couber no novo plano, a mudança é aplicada na hora. Se você tiver mais ambientes, instâncias ou membros do que o novo plano permite, a troca não é aplicada de imediato: você ganha 30 dias para escolher o que manter. Um aviso aparece no topo do dashboard com o botão “Resolver conflito”.

Os itens que você não mantiver ficam suspensos — param de coletar dados novos, mas nada é excluído. Todo o histórico é preservado e pode ser reativado se você voltar a um plano superior em até 90 dias. Se você não resolver dentro dos 30 dias, mantemos automaticamente os itens mais antigos dentro do limite e suspendemos o excedente, avisando por e-mail.

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.

Subdomínio personalizado

Empresas no plano MSP podem ter um endereço próprio para acessar o codeDB — por exemplo suaempresa.codedb.com.br — exibindo sua logo e sua marca já na tela de entrada, antes do login.

Como ativar

Quanto tempo leva

A ativação não é instantânea: cada pedido passa por verificação e pela configuração do endereço na infraestrutura, o que costuma levar de alguns minutos a algumas horas. Não é preciso aguardar na tela — você recebe um e-mail quando o endereço estiver no ar.

O que significa cada status

Remover o subdomínio

Com o subdomínio ativo, use Remover subdomínio e confirme. O endereço deixa de funcionar e quem tentar acessar por ele não conseguirá entrar — oriente seus clientes a usarem app.codedb.com.br antes de remover. Para trocar de nome, remova o atual e solicite o novo.

Os dados, logins e permissões são exatamente os mesmos em qualquer endereço — muda apenas a URL e a marca exibida. Domínio próprio da sua empresa (como monitor.suaempresa.com.br) ainda não é suportado.

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 (14, 45 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

Como a medição é feita (agent 1.19.2+)

A partir do agent 1.19.2, disponibilidade é medida, não estimada. O agente executa uma sonda a cada 15 segundos — um SELECT 1 em conexão dedicada, com timeout curto — e grava o resultado localmente. O envio acontece no ciclo normal de coleta (a cada 5 minutos por padrão), mas a medição não para durante o envio: se parasse, o monitoramento ficaria cego justamente quando a rede está ruim.

A sonda usa conexão dedicada de propósito. Uma conexão reaproveitada de pool poderia “passar” mesmo com o caminho de rede já indisponível, mascarando a falha.

O que acontece se o codeDB ficar inacessível

As medições continuam sendo gravadas em disco no servidor do agente e são enviadas quando a comunicação volta. Nenhuma aferição é perdida — a cobertura do período não fica com buraco só porque a plataforma esteve fora. O arquivo local só é apagado após confirmação de recebimento, e um identificador de lote impede que um reenvio conte o mesmo downtime duas vezes.

Classificação do erro — instância fora vs. rede instável

Quando a sonda falha, o codeDB não registra apenas “falhou”: ele classifica a causa e cruza com o horário de início da instância para distinguir dois cenários que exigem ações completamente diferentes.

Essa distinção importa: uma queda de conectividade sem reinicialização indica problema de infraestrutura de rede, não do banco de dados — e é diagnóstico que ferramentas que só olham “respondeu / não respondeu” não conseguem entregar.

Onde ver

O gráfico Disponibilidade medida fica no Dashboard Gerencial, com faixas de 24h (ponto por hora), 7, 30 e 90 dias (ponto por dia). Mostra a linha do ambiente e permite abrir uma linha por instância. Períodos sem medição aparecem como lacuna na linha, nunca como 100% — ausência de dado não é evidência de disponibilidade. Quedas sustentadas também viram incidentes com causa raiz na tela de Incidentes.

O percentual é truncado, nunca arredondado para cima: 99,98% aparece como 99,9%. Arredondar mostraria 100% num período que teve downtime real.

Modelo de estados (UP / DOWN / UNKNOWN)

Independente das sondas, o codeDB também classifica o intervalo entre snapshots de métricas em cinco estados. Esse modelo alimenta os cards de Disponibilidade e Cobertura, e é o que responde por instalações com agente anterior à 1.19.2, onde ainda não há sondagem:

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];

CREATE ROLE codedb_monitor LOGIN PASSWORD '<senha forte>';
GRANT pg_monitor TO codedb_monitor;
GRANT CONNECT ON DATABASE postgres TO codedb_monitor;
-- repita o GRANT CONNECT para cada database que deve aparecer no inventário

CLOUD_METRICS=aws            # off | aws | azure
# Só se o recurso não for descoberto pelo DB_SERVER (endpoint de cluster Aurora,
# endpoint fora do padrão). AWS: identificador da instância ou ARN; Azure: resource ID completo.
CLOUD_RESOURCE_ID=
# Por instância adicional: INSTANCE_N_CLOUD_METRICS e INSTANCE_N_CLOUD_RESOURCE_ID

CLOUD_AWS_ACCESS_KEY_ID=
CLOUD_AWS_SECRET_ACCESS_KEY=
CLOUD_AZURE_TENANT_ID=
CLOUD_AZURE_CLIENT_ID=
CLOUD_AZURE_CLIENT_SECRET=

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["cloudwatch:GetMetricData", "rds:DescribeDBInstances"],
    "Resource": "*"
  }]
}

az role assignment create --assignee <client-id-ou-identidade> \
  --role "Monitoring Reader" --scope <resource-id-do-banco>

# 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
}