Como debugar código com IA: logs mascarados, hipóteses e correção

Como debugar código com IA: logs mascarados, hipóteses e correção

Para debugar código com IA em produção, mascare os logs antes de enviá-los, peça hipóteses ranqueadas com o que cada uma prevê encontrar e deixe a validação com o desenvolvedor: reproduzir o erro, confirmar a causa e corrigir com teste. A IA é boa em ler muito texto rapidamente e propor explicações plausíveis. Ela não sabe o que realmente aconteceu no seu sistema, e por isso o ganho está em encurtar a busca, não em dispensar a prova.

Principais pontos

• Logs de produção têm dados pessoais e segredos. Mascare antes de enviar a qualquer modelo, e trate o mascaramento como etapa fixa do fluxo.
• Peça hipóteses, não veredictos. Cada hipótese deve vir com a evidência que a sustenta e o teste que a refutaria.
• A IA propõe, o desenvolvedor dispõe: nenhuma correção entra sem reprodução do erro e sem um teste que falhava antes e passa depois.
• Contexto bem recortado vale mais do que contexto enorme. Envie o trecho da janela de tempo do incidente, não o arquivo inteiro.
• Registre o que foi hipótese, o que foi comprovado e o que foi descartado. Isso vira memória da equipe para o próximo incidente.

Por que começar pelos logs, e não pelo código?

Em produção, o código raramente é o primeiro sinal. O primeiro sinal é um comportamento: pedidos que não fecham, mensagens que não chegam, uma tela que trava para um tipo de cliente. O registro desse comportamento está nos logs, nas métricas e nos traces. A documentação de observabilidade do OpenTelemetry descreve bem essa ideia: observabilidade é conseguir fazer perguntas sobre o sistema a partir dos sinais que ele emite, sem precisar alterar o código para cada pergunta nova.

É nesse ponto que a IA ajuda. Um incidente pode gerar milhares de linhas, e o desenvolvedor cansado tende a fixar na primeira anomalia que vê. Um modelo lê o conjunto inteiro sem cansaço e consegue apontar padrões: um erro que sempre precede outro, um campo que aparece vazio só em certas requisições, um intervalo de tempo que se repete. Esses padrões são pontos de partida para investigar, e nada além disso.

Se o sistema quase não emite sinais úteis, o primeiro passo não é a IA. É melhorar o log: identificador de requisição, nome da operação, resultado e duração. Sem isso, qualquer análise, humana ou automática, vira adivinhação.

O que mascarar antes de colar qualquer coisa?

Logs de produção costumam carregar mais do que se imagina: e-mails, telefones, CPF, endereços, tokens de API, cookies de sessão, trechos de mensagens de clientes e até corpo de requisições inteiro. Enviar isso a um serviço externo é uma decisão de tratamento de dados, e a ANPD é a referência oficial para entender as obrigações da LGPD nesse tema. Se o provedor processa fora do Brasil, vale ler também sobre transferência internacional de dados com IA.

Uma regra prática: mascare por substituição que preserva o formato e a relação entre os valores. Se o mesmo cliente aparece em cinco linhas, ele deve virar o mesmo marcador nas cinco, para o modelo ainda enxergar o padrão.

• Identificadores pessoais (nome, CPF, e-mail, telefone): troque por marcadores estáveis como USUARIO_A, EMAIL_A, TEL_A.
• Segredos (chaves, tokens, senhas, cookies, cabeçalhos de autorização): remova por completo, sem marcador reversível.
• Conteúdo livre digitado por pessoas (mensagens, observações, anexos): remova ou resuma, pois é onde mais vazam dados e também onde pode haver texto malicioso.
• Identificadores técnicos (ID de requisição, ID de pedido interno): mantenha, pois são o fio que liga os eventos.
• Nomes de hosts, bancos e caminhos internos: avalie caso a caso. Geralmente podem ser generalizados.

Automatize o mascaramento com um script versionado, revisado e testado, em vez de depender de cada pessoa lembrar. Depois, confira por amostragem se algo escapou. Um mascaramento que falha em silêncio é pior do que nenhum, porque dá falsa segurança.

Há ainda um cuidado de segurança: logs contêm texto que vem de fora, e texto que vem de fora pode tentar instruir o modelo. A lista OWASP Top 10 para aplicações com LLM trata disso como risco real. Diga ao modelo explicitamente que o log é dado a ser analisado, nunca instrução a ser seguida, e não dê a ele ferramentas que executem ações.

Como pedir hipóteses em vez de uma resposta pronta?

O erro mais comum é colar o log e perguntar qual é o bug. O modelo responderá com confiança, mesmo sem evidência suficiente. Um pedido melhor força estrutura e honestidade sobre incerteza. Inclua sempre estes elementos:

• Sintoma observado: o que os usuários ou o monitoramento viram, e quando começou.
• Janela de tempo e escopo: só o trecho relevante, com poucas linhas antes do primeiro erro.
• O que mudou: deploys recentes, configurações, dependências, volume de uso.
• O que já foi descartado: evita que o modelo repita o óbvio.
• Formato da resposta: hipóteses ranqueadas, cada uma com a evidência no log que a sustenta, o que contradiria a hipótese e o teste mais barato para verificá-la.
• Limite explícito: pedir que o modelo diga quando não há evidência suficiente, em vez de preencher a lacuna.

Sobre o tamanho do contexto: mais texto não significa melhor análise. A Anthropic discute isso em seu material sobre engenharia de contexto para agentes, e a lógica vale aqui: o que entra na conversa deve ser o conjunto mínimo de informação de alto sinal. Se quiser entender o limite na prática, leia sobre janela de contexto em IA.

Trate a resposta como uma lista de suspeitos, não como sentença. Uma boa saída tem hipóteses que se contradizem entre si, e isso é útil: indica exatamente qual observação separa uma da outra.

Como validar e reproduzir antes de mexer no código?

Esta é a etapa que pertence ao desenvolvedor, e é a que impede que a IA transforme um palpite em uma correção errada que passa despercebida. Um fluxo simples:

• Passo um, escolha a hipótese mais barata de testar, não necessariamente a mais provável. Se uma consulta ao banco confirma ou descarta em minutos, comece por ela.
• Passo dois, confira a evidência você mesmo nos logs originais, sem mascaramento, dentro do seu ambiente. Não confie na citação que o modelo fez do trecho.
• Passo três, tente reproduzir em ambiente de teste ou homologação, com dados sintéticos que imitam a forma do caso real.
• Passo quatro, escreva um teste que falha pelo motivo suspeito. Se você não consegue fazê-lo falhar, a hipótese ainda não está confirmada.
• Passo cinco, só então altere o código, e rode o teste de novo para ver a mudança de falha para sucesso.
• Passo seis, observe em produção com o mesmo sinal que acusou o problema, por um período combinado, antes de declarar o incidente encerrado.

Se nenhuma hipótese se confirmar, volte ao modelo com o que foi descartado e com as novas observações. Cada rodada deve reduzir o espaço de busca, não reiniciá-lo.

Como fica na prática? Um cenário ilustrativo

Cenário ilustrativo: uma loja virtual percebe que alguns pedidos ficam presos no status de pagamento pendente, embora o pagamento tenha sido aprovado. O time extrai os logs da janela do incidente, aplica o script de mascaramento e pede hipóteses ao modelo, informando que houve um deploy no dia anterior.

O modelo devolve três hipóteses. A primeira: o recebimento de notificações do gateway de pagamento está falhando por validação de assinatura, e o log mostra rejeições concentradas após o deploy. A segunda: há processamento duplicado de notificações, com conflito no banco. A terceira: um tempo limite curto demais está derrubando a resposta ao gateway, que reenvia depois. Para cada uma, ele indica o que esperaria ver.

A desenvolvedora escolhe a verificação mais barata: contar, nos logs originais, as rejeições por assinatura. Elas existem, mas são poucas e não explicam o volume de pedidos presos. Ela passa à terceira hipótese, vê nos registros de duração que as respostas passaram do limite configurado depois que uma nova consulta foi adicionada ao tratamento da notificação. Reproduz em homologação com uma consulta lenta simulada, escreve um teste que falha por tempo excedido e move a consulta para processamento assíncrono. O teste passa, e ela acompanha em produção se o status deixa de ficar preso. A segunda hipótese vira anotação para investigar depois, porque a idempotência do recebimento merece revisão de qualquer forma.

O papel da IA foi organizar o espaço de busca. A prova, a decisão e a correção foram humanas.

Como corrigir e fechar o incidente sem repetir o problema?

Depois da correção, três registros fazem a diferença. O primeiro é o teste de regressão, que protege contra o mesmo erro voltar. Se a IA ajudou a escrever esse teste, aplique os mesmos cuidados descritos em testes gerados por IA: como validar e confiar: o teste precisa falhar sem a correção e testar o comportamento, não a implementação.

O segundo é uma nota curta do incidente, com quatro campos: sintoma, causa confirmada, o que foi hipótese e descartado, e o que mudou. Separar fato de hipótese evita que, meses depois, alguém trate um palpite antigo como conhecimento estabelecido.

O terceiro é a melhoria do próprio sinal. Se faltou um identificador de requisição ou uma métrica de duração, acrescente agora. O próximo incidente será mais rápido de investigar com ou sem IA.

Quem coordena a equipe deve evitar transformar esse fluxo em vigilância individual. Meça se os incidentes estão sendo resolvidos com mais clareza e menos retrabalho, não quanto cada pessoa usou o assistente.

Quando não enviar logs a uma IA externa?

Nem todo log deve sair da empresa, mesmo mascarado. Um guia simples de decisão:

• Se o log contém conteúdo livre de clientes que você não consegue mascarar com confiança, não envie. Analise manualmente ou use um modelo rodando na sua infraestrutura.
• Se há sigilo contratual ou setor regulado envolvido, consulte o jurídico e o encarregado de dados antes de definir o fluxo.
• Se o incidente envolve credenciais comprometidas, trate como incidente de segurança primeiro e investigue em ambiente controlado.
• Se o problema é de estrutura simples, como um erro de configuração visível em poucas linhas, talvez nem precise de IA.

Para os casos sensíveis, um modelo local pode ser o caminho. Vale ler sobre como rodar um modelo local na empresa com Ollama, sabendo que modelos menores têm limites de raciocínio e exigem mais verificação.

O método que aplicamos em projetos de IA vale também para esse fluxo interno. Mapear: entender como o time investiga incidentes hoje e onde o tempo se perde. Limitar: definir quais dados podem sair, com qual mascaramento, e que a IA não executa ações em produção. Pilotar: testar em um tipo de incidente, com registro das hipóteses e um critério combinado de sucesso. Transferir: documentar o fluxo e o script de mascaramento para a equipe, e decidir se expande, ajusta ou para.

Perguntas frequentes

É seguro colar logs de produção no ChatGPT ou em outra IA? Só depois de mascarar dados pessoais e remover segredos, e dentro de uma política da empresa que defina qual ferramenta e qual plano podem ser usados. Sem mascaramento, você está tratando dados de clientes em um terceiro, o que exige base legal e cuidado com a LGPD. Na dúvida, use um modelo local ou consulte o encarregado de dados.

A IA consegue achar a causa raiz sozinha? Em casos simples, às vezes acerta de primeira, mas não há garantia, e ela não tem acesso ao que não está no log. Trate a resposta como hipótese e confirme com reprodução e teste. A causa raiz só está estabelecida quando você consegue provocar o erro e eliminá-lo com a correção.

Quanto de log devo enviar ao modelo? O mínimo que cobre a janela do incidente e o momento logo antes do primeiro sinal de erro, junto com o que mudou recentemente. Arquivos enormes diluem o sinal e aumentam o custo. Se a primeira rodada não bastar, amplie o recorte de forma deliberada.

Posso deixar a IA aplicar a correção diretamente em produção? Não é recomendável. Permita que ela sugira o código, mas a alteração deve passar por teste, revisão humana e o processo normal de deploy. Ferramentas com acesso a produção ampliam o risco, e qualquer permissão deve ser mínima, auditada e aprovada por uma pessoa.

Fontes

• OpenTelemetry: conceitos de observabilidade
• Anthropic: Effective context engineering for AI agents
• OWASP Top 10 for LLM Applications
• ANPD: Autoridade Nacional de Proteção de Dados