Para desenvolvedores de aplicações

Qual consulta otimizar primeiro? Qual código recebeu o erro? Quem segura o registro em um conflito? O agente reúne as respostas a partir do trace e das estatísticas no próprio servidor. O desenvolvedor as vê no navegador e não precisa entrar no servidor.

  • 1 min arquivos de trace
  • 3 janelas por dia relatório de desempenho
  • pelo plano agrupamento de consultas
  • 15 min busca de conflitos
  • REST Local API para scripts e CI

trace · process_traces · perf report

Relatório de desempenho

O agente mantém uma sessão de trace aberta o tempo todo. A cada minuto ele compacta a saída em um arquivo e calcula os totais de cada consulta. Ao fim de uma janela, o agente junta os minutos em um relatório: as consultas mais lentas e as mais pesadas em fetches, leituras e gravações. Cada consulta mostra o número de execuções.

  1. 1Sessão de traceo fbtracemgr roda o tempo todo; um watchdog reinicia uma sessão perdida
  2. 2Arquivo do minutosaída do trace compactada uma vez por minuto
  3. 3Totais do minutopara cada consulta: execuções, tempo, fetches, reads, writes, marks
  4. 4Relatório da janelaem até 5 minutos após o fim da janela; até 20 consultas em cada ranking
  5. 5✓ HQ Monitorpágina Perf Report; link a partir do relatório de saúde
Três janelas de relatório por dia: manhã 07:00–12:30, tarde 12:31–18:00, noite 18:01–06:59; o agente verifica a cada 5 min, então o relatório sai em até 5 min após o fim
Janelas padrão. Manhã, tarde e noite. As janelas e o número delas mudam nas configurações do agente. Um minuto sem dados é ignorado; o relatório é gerado mesmo assim.

Por que agrupar pelo plano

Se um programa coloca os valores direto no texto SQL, cada valor gera um novo texto. Em um caso real, o número de textos diferentes subiu de 204 para 83.825 por minuto. Milhares de consultas “diferentes” são, na verdade, uma só consulta com um só plano. Por isso, por padrão, o agente agrupa as consultas por uma chave: os 10 primeiros caracteres do SQL sem comentários, mais o plano de execução. Uma consulta sem plano fica com o texto completo. O modo muda nas configurações do agente, campo “Agrupamento da estatística por minuto”: pelo plano ou pelo texto SQL completo. Pelo texto, os arquivos e relatórios ficam bem maiores. Troque o modo no exemplo abaixo e compare os rankings.

Consultas em um minuto

    Ranking por fetches

      Tabela do relatórioO que mostra
      Top SQL by durationAs execuções mais lentas: tempo e número de registros.
      Top SQL by fetches, reads, writesSomas da janela: execuções, tempo, fetches, reads, writes, marks; fração da janela inteira; média e máximo por execução.
      Processes e AddressesCarga por programa e por endereço do cliente: conexões, tempo, número de planos e consultas diferentes.
      Linha da consultaSQL completo, PLAN, parâmetros e estatísticas por tabela: natural, index, update, insert, delete, backout, purge, expunge.
      Dez rankings em abasDuração, frequência, tempo total, fetches, reads, writes, planos, tags, procedures e triggers. Cada métrica mostra a dispersão dos valores.
      Exemplo de execuçãoQuando rodou, qual cliente e de qual endereço, em qual banco de dados. Se a execução terminou com erro, isso fica visível; a consulta tem um contador de execuções com falha.
      Execuções por horaQuantas vezes e por quanto tempo a consulta rodou em cada hora da janela.
      DatabasesTotais por banco de dados do servidor e os principais bancos de dados de cada consulta.

      Comparação, histórico e relatório sob demanda

      O relatório da janela responde à pergunta “o que foi pesado hoje”. Três novas funções respondem às perguntas “o que mudou” e “o que houve nesta hora”.

      • Comparação de duas janelasDois relatórios lado a lado: quais consultas ficaram mais lentas, quais apareceram e quais sumiram.
      • Histórico da consulta em 30 diasComo o tempo e o número de execuções de uma consulta mudaram de janela em janela.
      • Filtro por banco de dadosRelatório de um só banco de dados. A página do banco de dados tem um link para a página do relatório.
      • Para os traces do minutoDa consulta no relatório para os traces do minuto em que ela rodou.
      • Relatório sob demandaO botão Build report… gera um relatório de qualquer intervalo de até 24 horas. Filtros: banco de dados, duração mínima, programa. O agente gera um relatório desse tipo por vez e guarda os 20 últimos.
      • Busca e downloadCampo de busca pelo texto da consulta. O arquivo de origem do relatório pode ser baixado.
      • Relatório incompleto é marcadoSe parte dos arquivos de trace ainda não chegou, o relatório fica marcado como incompleto. O relatório guarda só o topo de cada ranking, por isso a página escreve “fora do ranking”, e não “não rodou”.
      • Procedures e triggersEsses rankings são preenchidos quando a gravação do fim de procedures e triggers está ligada nas configurações do trace. Por padrão ela fica desligada.
      • A partir do relatório de saúdeO botão Perf report abre a janela certa. As linhas da consulta ficam marcadas, e a primeira já vem aberta.
      • Consulta e tabelaA aba Queries das estatísticas gstat liga as consultas às tabelas e índices que elas leem.
      • Um minuto no gráfico do bancoUm clique em um minuto mostra as consultas pesadas do trace e todas as conexões desse minuto.
      • Copiar SQLCom ou sem parâmetros, direto para a sua ferramenta. No modo demo os botões ficam ocultos.

      trace · Errors

      Erros SQL com dados do cliente

      Um usuário diz “o programa deu erro”. A página Errors mostra cada erro do Firebird a partir do trace: hora, conexão, banco de dados, texto e cliente. Com o nome do programa, o endereço e a função do Firebird, é fácil achar o erro no seu código.

      Bloco de erro no trace

      2026-10-17T12:00:05.0000 (4521:0x7f..) ERROR AT JStatement::execute /db/shop.fdb (ATT_370201, SHOP_APP:NONE, UTF8, TCPv4:10.0.0.5/50123) C:\Shop\shop.exe:7712 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM"

      Linha na página Errors

      tstmpattIDdb · errTxt 12:00370201/db/shop.fdb ×3 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM" C:\Shop\shop.exe:7712 · 10.0.0.5/50123 · JStatement::execute

      • Erros iguais — uma linhaUma linha por minuto, banco e tipo de erro, com a contagem ×N. A dica mostra a primeira e a última hora e o número de conexões.
      • FiltrosInclude e Exclude por texto, banco, programa, endereço e função. Um clique em um programa ou endereço deixa só os erros dele.
      • Export CSVTodas as linhas com os filtros aplicados, em UTF-8 com BOM: o Excel abre o arquivo já em colunas.
      • Se não há programaMuitos drivers JDBC e .NET não enviam o nome do programa. Então a linha do cliente fica mais curta.

      trace_monitor_conflicts · find_deadlocks

      Conflitos e deadlocks

      O erro “update conflicts with concurrent update” sozinho diz pouco. É preciso saber o que a outra transação fez. Para isso, o agente mantém uma segunda sessão de trace, configurada para alterações de dados e erros. A cada 15 minutos ele procura conflitos e monta um relatório.

      A transação 1001 alterou um registro; a 1002 tenta alterar o mesmo registro e recebe erro; o relatório acha as consultas da 1001 pelo número dela

      Como ler o relatório

      À esquerda fica a lista de minutos com conflitos. Cada grupo é uma transação que causou conflitos: o número da transação e a hora do erro.

      A coluna da esquerda mostra os erros: conexão, programa, códigos do Firebird e a consulta que falhou. A coluna da direita mostra as consultas bem-sucedidas da transação concorrente: hora, conexão, número da transação, programa. Cada consulta tem SQL, parâmetros, estatísticas e tabelas.

      O endereço da página guarda a data e o minuto. Você pode enviar o link a um colega.

      Página Conflicts. Minutos à esquerda, o grupo da transação à direita: processo e códigos de erro.
      ParâmetroPadrãoSignificado
      Busca de conflitosa cada 15 minutosO último minuto é ignorado: o trace ainda está gravando nele.
      Profundidade da busca3 horasQuanto histórico antes do conflito examinar na busca das consultas da outra transação.
      Retenção do trace bruto6 horasOs arquivos brutos da sessão de conflitos não se acumulam no servidor. Os relatórios são guardados e enviados ao HQ Monitor.

      gstat · índices · metadados

      Como o banco de dados muda

      Uma vez por dia o agente coleta as estatísticas completas do gstat. O HQ Monitor analisa o arquivo: tamanho de tabelas e índices, versões de registros, BLOBs, profundidade dos índices. A aba “Análise e recomendações” diz o que está errado e o que fazer.

      Análise e recomendações. Problema, número de casos, objetos com link, recomendação e ação.
      Tendências. Comparação dos últimos snapshots: o que cresceu e quando um objeto vai crescer 25%.
      AbaO que oferece ao desenvolvedor
      TablesTamanho dos dados, índices e BLOBs, número de registros, versões de registros e o máximo de versões de um registro.
      IndexesProfundidade, páginas, valores únicos, duplicatas. Profundidade 4 é uma linha amarela, 5 ou mais é vermelha.
      Queries e LinksQuais consultas leem uma tabela ou índice. Dados dos relatórios de desempenho próximos no tempo ao snapshot.
      TrendsComparação de 5, 10, 20 ou 30 snapshots; limite de mudança de 10%, 2% ou 0,5%. Previsão “+25%” com três snapshots ou mais.
      ExportaçãoJSON com as medições e Excel com a análise completa.
      • Estatísticas de índicesDesligadas por padrão; você as liga nas configurações do agente. Depois, a cada 6 horas, o agente conta os índices inativos e os índices com seletividade ruim. Um índice não construído após um restore é serious no relatório de saúde.
      • Previsão de crescimentoO chip “+25%” na tabela de bancos mostra a tabela ou o índice que cresce mais rápido e abre a previsão.
      • Exportação do esquemaO agente exporta os metadados do banco com isql -x e guarda os arquivos por data.
      • Rastreamento de metadadosDesligado por padrão; você o liga nas configurações do agente. A cada 6 horas o agente compara a nova exportação do esquema com a anterior e registra quando o esquema mudou.

      LWM · MON$ · clientes

      Conexões: transações longas e versões dos clientes

      Uma transação esquecida deixa o banco inteiro lento: as versões de registros se acumulam e a coleta de lixo para.

      A cada minuto o agente grava os contadores de transações e os dados das conexões. No gráfico do banco, Next − OAT cresce se uma transação fica aberta por muito tempo. A tabela de conexões desse minuto, ordenada por Act.Tran, mostra o programa, o endereço e o processo que segura a transação. Mais sobre os contadores na página sobre a saúde do servidor.

      Uma vez por dia o agente lê quais bibliotecas cliente se conectam ao banco e quantas conexões cada uma tem. A linha “Not detected. Old version?” em geral indica uma biblioteca cliente antiga.

      Versões dos clientes. A string de versão enviada pelo cliente e o número de conexões. As conexões do próprio agente aparecem em uma linha separada.
      • Métricas MON$Uma vez por hora: memória por programa, as 5 conexões com mais memória e as 5 com maior carga.
      • Clientes antigos sem alarmes falsosO achado “clientes antigos” conta só as bibliotecas fbclient. Drivers que funcionam sem o fbclient não entram nele.
      • Transações longas no relatórioO relatório de saúde marca as transações longas e o crescimento de Next − OAT. O achado diz o usuário, o programa e o endereço e traz um comando pronto para desconectar.

      Local API · Prometheus · HQbird MCP

      Seus scripts, CI e assistente de IA

      Tudo o que você vê no HQ Monitor está disponível nas suas próprias ferramentas. A Local API do agente escuta só no loopback, e cada requisição leva um token Bearer. Jobs pesados rodam de forma assíncrona: a resposta traz um número de operação, e o status é lido por ele. O agente grava no log de auditoria cada requisição que altera o servidor e cada recusa 401 ou 403. Requisições de leitura não vão para o log.

      # porta da Local API = 10000 + porta do Firebird: aqui o Firebird usa 3055, então 13055
      # estado do servidor: o mesmo snapshot do relatório de saúde
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status
      # último relatório de desempenho e último relatório de conflitos
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest
      # executar um backup antes de uma migração no CI e aguardar o resultado
      curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \
           http://127.0.0.1:13055/v1/jobs/vbackup/run
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
      CaminhoO que oferece
      /v1/statusSnapshot do estado do servidor, inteiro ou por seção, por exemplo backups.
      /v1/databasesLista dos bancos ativos.
      /v1/artifacts/…Dados do agente: LWM (Light-weight Monitoring) por minuto, gstat, estatísticas de índices, métricas, a última exportação do esquema, relatórios de trace.
      /v1/jobs/{job}/runExecução de um job: backup, restore, sweep, verificação do banco, recálculo de índices, script SQL. Uma repetição com a mesma chave não executa o job duas vezes.

      As métricas para o Prometheus não passam pela Local API. Elas têm endereço próprio: por padrão 127.0.0.1, porta 25000 + porta do Firebird. Elas têm token Bearer próprio. A exportação vem desligada por padrão e é ligada nas configurações do agente. Métricas: LWM, CPU e memória, discos, limites do SO, arquivos temp.

      Assistente de IA na IDE

      O HQbird MCP conecta o Firebird e os dados do agente ao Claude Code, Cursor, Codex e outros clientes MCP. O assistente vê os relatórios do agente e trabalha com o banco sob controle humano: uma pessoa confirma as ações perigosas.

      Consulta

      Plano e índice

      Plano da consulta e sugestão de índice, com nova verificação do plano após criar o índice. Verificação de compilação da consulta antes da execução.

      Esquema

      Comparar dois bancos

      Diferenças de esquema e de dados, por exemplo entre desenvolvimento e o ambiente de teste.

      Migração

      Plano, confirmação, reversão

      Uma migração com plano, uma única confirmação e plano de reversão.

      Mais: HQbird MCP

      ← Voltar à visão geral do HQbird 2027 · Saúde do servidor em detalhes →