Tema: debugging
-
Modos de falha do Jev 1.13: leitura literal, contagem, datas, indireção e degradação de contexto
Os nove modos de falha que a TypeSafe documenta para o jev-1.13 (revisados pelo fornecedor em 2026-09-17), o que cada um significa para um agente que delega decisões ao modelo e o contorno documentado para cada caso: condições exatas nas instruções, aritmética e lógica de datas em código, estado filtrado e nenhuma dependência de invariantes estruturais entre perguntas separadas.
-
O método USE para encontrar gargalos de desempenho
Para cada recurso (CPU, memória, discos, rede, locks), verifique utilização, saturação e erros: o método USE é um checklist que localiza gargalos rapidamente, sem começar por suposições sobre a camada da aplicação.
-
Como escrever um relatório de bug utilizável
Um relatório de bug é utilizável quando uma pessoa de fora consegue reproduzir o erro sem fazer perguntas: título preciso, ambiente com versões, passos numerados para reproduzir, resultado esperado e resultado real separados, a mensagem de erro literal e um exemplo o menor possível. Suposições sobre a causa ficam numa seção própria.
-
Diagnosticar «No space left on device» quando o df mostra espaço livre
Além do disco cheio, o ENOSPC tem três causas comuns: inodes esgotados, espaço retido por arquivos apagados que um processo ainda mantém abertos e a percentagem de blocos reservados em sistemas de arquivos ext. Verifique df -i, lsof +L1 e a reserva do ponto de montagem antes de apagar qualquer coisa.
-
Como encontrar um vazamento de memória com snapshots do tracemalloc
Inicie o rastreamento cedo com PYTHONTRACEMALLOC ou tracemalloc.start(nframe), tire um snapshot após o aquecimento e outro após N iterações, filtre o ruído de imports e leia compare_to(..., 'lineno') para achar linhas cujo tamanho cresce proporcionalmente a N; troque para o agrupamento 'traceback' para ver quem as chama.
-
MTU, fragmentação e descoberta do MTU do caminho
A Ethernet transporta pacotes IP de 1500 bytes, túneis e PPPoE transportam menos, e os roteadores IPv6 nunca fragmentam. A descoberta do MTU do caminho depende de mensagens ICMP Packet Too Big; quando elas são filtradas, pacotes grandes somem sem aviso enquanto os pequenos passam, o clássico black hole, contornado com MSS clamping ou sondagem na camada de empacotamento.
-
Depuração sistemática em seis passos
Reproduzir o erro, observar com precisão, formular uma hipótese com previsão, fazer um experimento por alteração, registrar as causas descartadas e corrigir a causa protegendo a correção com um teste de regressão.
-
Logs de execução reproduzíveis para agentes: registrar cada chamada ao modelo e às ferramentas
Só é possível depurar a execução de um agente se cada requisição ao modelo, resposta, chamada de ferramenta e resultado de ferramenta forem registrados em ordem, com identificadores e parâmetros. As convenções semânticas GenAI do OpenTelemetry definem os campos, e um log reproduzível permite recriar uma falha sem pagar por uma nova execução.
-
Recuperar commits e branches perdidos com o reflog
O reflog registra todos os movimentos de HEAD e de cada branch no repositório local. Assim, é possível desfazer um reset, rebase, amend ou exclusão de branch ruins: basta localizar a posição anterior e criar uma nova branch nela. Por padrão, as entradas expiram após 90 dias (30 para as inalcançáveis), e alterações não commitadas nunca estiveram nele.
-
Como encontrar com git bisect o commit que introduziu uma regressão
O git bisect faz uma busca binária no histórico entre um commit sabidamente bom e um sabidamente ruim; com um script de teste automatizado, localiza o commit responsável sem inspeção manual.
-
Reduzir a reprodução de um bug sem eliminar a condição que o causa
Minimizar um exemplo que falha, verificando que o caso reduzido ainda demonstra o defeito original e não um erro diferente, mais fácil de produzir.
-
Triagem do AddressSanitizer: corrija o primeiro acesso inválido antes de confiar no comportamento posterior
Transforme um relatório do AddressSanitizer em um caso de regressão mínimo sobre propriedade (ownership) ou limites, sem tratar uma execução limpa como prova.
-
Como transformar um relatório de bug em um teste de regressão
Antes de corrigir um bug, reproduza-o como um teste automatizado que falhe e que cite o relatório; o teste comprova a correção e impede que o defeito volte.
-
Bancos de dados de compilação: reproduza a unidade de tradução com falha antes de alterar cabeçalhos
Use o comando de compilação real e o diretório de trabalho para distinguir defeitos no código-fonte de erros de configuração do editor.
-
Armadilhas da busca binária: overflow no ponto médio e limites com erro de uma unidade
A busca binária é curta e notoriamente fácil de errar: o ponto médio (low + high) / 2 estoura inteiros de largura fixa, limites inclusivos e exclusivos são misturados e os duplicados levantam a dúvida de qual índice retornar. Use uma biblioteca ou a forma com predicado monótono e intervalos semiabertos, e teste os extremos.
-
Escolher a próxima verificação de depuração pelas hipóteses que ela consegue distinguir
Evita que uma investigação repita diagnósticos de pouca informação, escolhendo cada nova verificação em função das explicações concorrentes que o seu resultado consegue separar.
-
Como escrever um exemplo mínimo reproduzível
Um exemplo mínimo reproduzível reúne o mínimo de código, dados e ambiente que ainda mostra o problema; criá-lo costuma ser metade do diagnóstico e é o que mantenedores e outros agentes precisam para ajudar.
-
Diagnosticar esperas de lock e deadlocks no PostgreSQL com pg_locks, pg_blocking_pids e lock_timeout
Uma instrução travada costuma estar esperando por um lock mantido por outra transação: localize quem espera em pg_stat_activity (wait_event_type Lock), o bloqueador com pg_blocking_pids() e o estado e a última instrução dele, e então cancele, encerre ou aguarde. O log_lock_waits registra esperas maiores que deadlock_timeout, deadlocks são detectados e resolvidos abortando uma transação, e lock_timeout limita quanto tempo um DDL pode esperar.
-
Encontrar o commit causador com git bisect
O git bisect faz uma busca binária entre um commit bom e um commit ruim conhecidos; com um script de verificação, encontra o primeiro commit defeituoso sem testes manuais.
-
Primeira análise de um processo com comportamento anômalo usando strace e tcpdump
Anexe o strace a um processo travado para ver em qual chamada de sistema ele está esperando e quais arquivos ou sockets ele acessa; rode o tcpdump com um filtro restrito e um limite de pacotes para verificar se o par remoto chega a responder. Ambos exigem privilégios e deixam o sistema lento ou enchem o disco, por isso limite-os no tempo e no escopo.
Legível por máquina: JSON