HQbird para desenvolvedores
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.
- 1Sessão de traceo fbtracemgr roda o tempo todo; um watchdog reinicia uma sessão perdida
- 2Arquivo do minutosaída do trace compactada uma vez por minuto
- 3Totais do minutopara cada consulta: execuções, tempo, fetches, reads, writes, marks
- 4Relatório da janelaem até 5 minutos após o fim da janela; até 20 consultas em cada ranking
- 5✓ HQ Monitorpágina Perf Report; link a partir do relatório de saúde
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ório | O que mostra |
|---|---|
| Top SQL by duration | As execuções mais lentas: tempo e número de registros. |
| Top SQL by fetches, reads, writes | Somas da janela: execuções, tempo, fetches, reads, writes, marks; fração da janela inteira; média e máximo por execução. |
| Processes e Addresses | Carga por programa e por endereço do cliente: conexões, tempo, número de planos e consultas diferentes. |
| Linha da consulta | SQL completo, PLAN, parâmetros e estatísticas por tabela: natural, index, update, insert, delete, backout, purge, expunge. |
| Dez rankings em abas | Duraçã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ção | Quando 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 hora | Quantas vezes e por quanto tempo a consulta rodou em cada hora da janela. |
| Databases | Totais 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
Linha na página Errors
- 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.
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.
| Parâmetro | Padrão | Significado |
|---|---|---|
| Busca de conflitos | a cada 15 minutos | O último minuto é ignorado: o trace ainda está gravando nele. |
| Profundidade da busca | 3 horas | Quanto histórico antes do conflito examinar na busca das consultas da outra transação. |
| Retenção do trace bruto | 6 horas | Os 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.
| Aba | O que oferece ao desenvolvedor |
|---|---|
| Tables | Tamanho dos dados, índices e BLOBs, número de registros, versões de registros e o máximo de versões de um registro. |
| Indexes | Profundidade, páginas, valores únicos, duplicatas. Profundidade 4 é uma linha amarela, 5 ou mais é vermelha. |
| Queries e Links | Quais consultas leem uma tabela ou índice. Dados dos relatórios de desempenho próximos no tempo ao snapshot. |
| Trends | Comparaçã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ção | JSON 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 -xe 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.
- 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>
| Caminho | O que oferece |
|---|---|
/v1/status | Snapshot do estado do servidor, inteiro ou por seção, por exemplo backups. |
/v1/databases | Lista 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}/run | Execuçã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.
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.
Comparar dois bancos
Diferenças de esquema e de dados, por exemplo entre desenvolvimento e o ambiente de teste.
Plano, confirmação, reversão
Uma migração com plano, uma única confirmação e plano de reversão.
← Voltar à visão geral do HQbird 2027 · Saúde do servidor em detalhes →