Sobre o trace do Firebird

O que é, quanto custa coletar, quanto dado gera e como ler o relatório.

🔍O que é o Trace API

O Trace API, disponível desde o Firebird 2.5, é o mecanismo nativo de observação do servidor: uma sessão de trace assina eventos (conexões, transações, prepare e execução de statements, erros) e os recebe como texto, com o SQL completo, o plano de execução escolhido pelo otimizador e as estatísticas reais de cada execução — tempo, registros retornados e contadores de leitura/escrita por tabela.

Existem dois sabores: a sessão interativa (iniciada com fbtracemgr, morre quando você a encerra ou desconecta — é a que a página Gerar trace monta) e o audit trace (configurado no fbtrace.conf do servidor, permanente). Para diagnóstico pontual, use sempre a interativa: começa e termina sob seu controle, sem tocar na configuração do servidor.

⚖️Custo de coletar (impacto no servidor)

Trace não é de graça, mas o custo é menor do que parece — e controlável:

• Só o que passa pelos filtros gera trabalho. Uma sessão filtrada por um banco específico não custa quase nada para os demais. Por isso a primeira regra é sempre filtrar por banco.
• O caro é formatar e transmitir eventos, não observá-los: cada execução logada vira dezenas de linhas de texto (SQL + plano + contadores). Em bancos com milhares de statements por segundo, o overhead típico fica na casa de poucos por cento — mas o volume de log cresce rápido (veja abaixo).
• time_threshold é o principal botão de custo. Com 0 (o que o gerador usa), toda execução é logada — ideal para análise completa, pois sem as execuções rápidas os totais mentem. Para monitoramento contínuo de produção, suba para 100 ms ou mais e capture só as lentas.
• explain_plan e print_perf adicionam custo pequeno por statement, mas são exatamente os dados que tornam a análise útil — não desligue.

📦Volume de dados

• Cada execução logada gera de ~15 a 60 linhas de texto (SQL repetido no start/finish, plano, parâmetros, contadores). Um sistema de médio movimento (aplicações fazendo polling, dezenas de execuções por segundo) produz facilmente dezenas de MB por hora — logs de centenas de MB em um dia são normais.
• Texto de trace comprime ~10× (é extremamente repetitivo). Comprima antes de enviar para análise: gzip trace.log — o upload aceita .gz e .zip.
• max_sql_length controla o corte do SQL no log. Muito baixo trunca queries grandes (e quebra o agrupamento por query na análise); o gerador usa 65535, que praticamente elimina truncamento. Se o volume for problema em sessões longas, reduza para 4096 sabendo do trade-off.
• Os filtros include_filter/exclude_filter reduzem volume na origem — ex.: ignorar as queries de metadados (RDB$) que ferramentas gráficas disparam aos montes.

🔒Cuidado com dados sensíveis

O log de trace contém o SQL completo e os valores dos parâmetros — nomes, CNPJs, valores financeiros. Trate o arquivo como dado de produção: transporte com cuidado, apague quando terminar, e aqui no serviço prefira o modo volátil (nada fica armazenado) ou o link com expiração.

🧭Limitações que valem saber

• Não há filtro por usuário ou aplicação na captura (pedido em aberto no projeto Firebird). Capture o banco inteiro e segmente nas abas Usuários e Aplicações do relatório.
• O trace registra o que aconteceu durante a sessão — uma query problemática que não rodou no período não aparece. Para visão completa, capture uma janela representativa (ex.: o horário de pico).
• A resolução de tempo é de 1 ms: execuções rápidas aparecem como "0 ms". Por isso o relatório calcula vazões (fetch/s, reg/s) sobre o tempo somado do grupo, e as omite quando o total é 0.

📖Glossário das métricas do relatório

💚Apoie o projeto

O fbtrace é desenvolvido e mantido de forma independente. Se a ferramenta te ajudou a encontrar aquele índice que faltava, considere apoiar o desenvolvimento ❤.