“`html
Seis meses de jornais OpenClaw. Foi o que eu tinha quando finalmente sentei para entender por que algumas sessões de depuração levavam 5 minutos e outras 2 horas. A resposta era óbvia com o tempo: a logação.
Não saber se eu tinha logs — eu sempre tinha logs. O problema era que metade dos meus logs eram ruídos desnecessários (“Processo iniciado… processo em execução… processo ainda em execução…”) e a outra metade faltava as informações que eu realmente precisava quando as coisas quebravam.
Veja o que eu mudei e como meu tempo de depuração passou de uma média de 45 minutos para cerca de 12 minutos por incidente.
O Problema Com a Logação Padrão
A logação padrão é projetada por desenvolvedores que sabem o que tudo significa. Quando o desenvolvedor vê “Context compaction triggered at 142K chars,” ele sabe exatamente o que isso significa e o que verificar em seguida. Quando eu vejo isso às 3 da manhã, fico me perguntando “isso é normal? 142K é alto? Era para compactar a 142K ou a 100K? Isso está relacionado ao erro que estou analisando?”
Os logs padrão presumem que você tem um conhecimento perfeito do sistema. A depuração em produção ocorre quando você tem conhecimentos imperfeitos e provavelmente está estressado.
O Que Eu Loguei Agora
Reestruturei minha logação em torno de um princípio: cada entrada de log deve me ajudar a responder “o que aconteceu e por quê?” sem precisar olhar para outro sistema.
Chamadas API: Modelo usado, número de tokens de entrada, número de tokens de saída, tempo de resposta, status (sucesso/erro), mensagem de erro se houver. Uma linha por chamada. Isso me diz imediatamente se a API está lenta, falhando ou é cara.
Execuções de ferramentas: Nome da ferramenta, resumo das entradas, resumo das saídas, duração, sucesso/fracasso. Quando uma ferramenta falha, posso ver exatamente o que foi tentado e o que deu errado sem ter que vasculhar a saída bruta.
Atividade de sessão: Início da sessão, eventos significativos (mensagem de novo usuário, chamada de ferramenta, compactação de contexto), fim da sessão. Isso me dá uma linha do tempo do que aconteceu em cada sessão.
Erros: Mensagem de erro completa, rastreamento de pilha, contexto relevante (ID da sessão, solicitação do usuário, atividade recente). O contexto é crucial — um erro sem contexto diz que algo quebrou, mas não o porquê.
O que parei de logar: Batimentos cardíacos de rotina (“still alive” mensagens a cada 30 segundos), verificações de saúde bem-sucedidas, transições de estado internas que são normais e esperadas. Esses acrescentavam volume sem adicionar informações.
Níveis de Logação Que Fazem Sentido
A maioria dos frameworks de logação oferece níveis DEBUG, INFO, WARN, ERROR. Eu os uso assim:
ERROR: Algo falhou e requer atenção humana. Eu leio cada log ERROR. Se eu receber mais de 5 entradas ERROR por dia durante uma operação normal, meus limites estão ruins.
WARN: Algo incomum ocorreu, mas o sistema lidou com isso. Limite de taxa atingido e recuo, compactação de contexto acionada, nova tentativa bem-sucedida após falha. Eu reviso as entradas WARN diariamente para identificar padrões.
INFO: Operações normais que eu poderia querer rastrear. Chamadas de API, execuções de ferramentas, eventos de sessão. Eu só as leio ao depurar um problema específico.
DEBUG: Estado interno detalhado para uma depuração profunda. Entrada/saída de cada função, alocação de memória, status do pool de conexões. Desativado em produção, a menos que eu esteja analisando um bug específico.
A chave: em produção, eu opero no nível INFO. Isso me dá detalhes suficientes para diagnosticar a maioria dos problemas sem o ruído do DEBUG. Eu temporariamente mudo para DEBUG quando estou analisando problemas específicos e depois volto para INFO.
Logação Estruturada
Os logs em texto simples são difíceis de pesquisar e impossíveis de agregar. Eu mudei para uma logação estruturada em JSON:
Em vez de: 2024-03-15 14:23:45 ERROR API call failed: timeout after 30s
“““html
Eu registro: um objeto JSON com timestamp, nível, tipo de evento, modelo, erro, duração, ID de sessão e ID de solicitação.
O formato JSON me permite:
– Pesquisar por qualquer campo (todos os erros para a sessão X, todos os tempos de espera para o modelo Y)
– Agregar métricas (tempo médio de resposta por modelo por hora)
– Criar painéis de controle (Grafana pode ler os logs JSON diretamente)
– Correlacionar eventos (seguir uma solicitação desde sua chegada até sua resposta)
A desvantagem: os logs JSON são menos legíveis para humanos ao usar o arquivo de log. Eu uso uma ferramenta de visualização de logs que formata JSON de forma bonita para monitoramento em tempo real.
Rotação e Retenção de Logs
Os logs dos agentes de IA crescem rapidamente. Uma instância OpenClaw moderadamente ativa gera 50 a 200 MB de logs por dia em nível INFO. Sem rotação, seu disco se enche em algumas semanas.
Minha política de retenção:
– Últimos 7 dias: logs completos (nível INFO), não compactados para acesso rápido
– Dias 8-30: logs compactados (gzip, redução de tamanho de aproximadamente 10x)
– Dias 31-90: entradas ERROR e WARN somente (extraídas dos logs completos antes da exclusão)
– Após 90 dias: métricas agregadas mensais apenas (sem logs brutos)
Isso mantém meu armazenamento total de logs abaixo de 5 GB enquanto mantém histórico suficiente para análise de tendências e investigação de incidentes.
O Fluxo de Trabalho de Depuração
Quando algo quebra, sigo esta sequência:
1. Verificar as 10 últimas entradas ERROR — geralmente revela a causa imediata
2. Buscar o mesmo tipo de erro na semana anterior — é um problema recorrente ou um caso isolado?
3. Observar a linha do tempo em torno do erro — o que aconteceu nos 60 segundos antes do erro?
4. Verificar eventos correlacionados — o erro coincidiu com um deployment, uma mudança de configuração ou uma queda de serviço externo?
Essa abordagem sistemática, combinada com uma boa registragem, resolve a maioria dos problemas em 10 a 15 minutos. Antes da registragem estruturada, os mesmos problemas levavam de 30 a 60 minutos, pois as etapas 3 e 4 exigiam uma arqueologia manual dos arquivos de log.
“`
🕒 Published: