Práticas recomendadas de registro do OpenClaw: Mantenha Claro

Seis meses de logs do OpenClaw. Isso era o que eu tinha quando finalmente sentei para descobrir por que algumas sessões de depuração demoravam 5 minutos e outras demoravam 2 horas. A resposta era óbvia em retrospectiva: registro.

Não se tratava de ter logs — eu sempre tinha logs. O problema era que metade dos meus logs eram ruído inútil (“Processo iniciado… processo em execução… processo ainda em execução…”) e a outra metade estava faltando as informações que eu realmente precisava quando as coisas quebravam.

Aqui está o que eu mudei e como meu tempo de depuração caiu de uma média de 45 minutos para cerca de 12 minutos por incidente.

O Problema Com o Registro Padrão

O registro padrão é projetado por desenvolvedores que sabem o que tudo significa. Quando o desenvolvedor vê “Compactação de contexto acionada em 142K caracteres,” ele sabe exatamente o que isso significa e o que verificar a seguir. Quando eu vejo isso às 3 da manhã, eu penso “é normal? 142K é alto? Deveria compactar em 142K ou em 100K? Isso está relacionado ao erro que estou investigando?”

Os logs padrão presumem que você tem conhecimento perfeito do sistema. A depuração em produção acontece quando você tem conhecimento imperfeito e provavelmente está estressado.

O Que Eu Registro Agora

Eu restruturei meu registro 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 de API: Modelo usado, contagem de tokens de entrada, contagem 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 ferramenta: Nome da ferramenta, resumo da entrada, resumo da saída, duração, sucesso/falha. 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 da sessão: Início da sessão, eventos significativos (nova mensagem de 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 informa que algo quebrou, mas não o porquê.

O Que Eu Parei de Registrar: Batimentos cardíacos rotineiros (“ainda vivo” mensagens a cada 30 segundos), verificações de saúde bem-sucedidas, transições de estado interno que são normais e esperadas. Esses aumentaram o volume sem adicionar informações.

Níveis de Log Que Fazem Sentido

A maioria das estruturas de log oferece níveis DEBUG, INFO, WARN, ERROR. Eu os uso assim:

ERROR: Algo falhou e precisa de atenção humana. Eu leio todos os logs ERROR. Se estou recebendo mais de 5 entradas ERROR por dia em operação normal, meus limites estão errados.

WARN: Algo incomum aconteceu, mas o sistema lidou com isso. Limite de taxa atingido e recuado, compactação de contexto acionada, nova tentativa bem-sucedida após falha. Eu reviso entradas WARN diariamente para identificar padrões.

INFO: Operações normais que eu posso querer rastrear. Chamadas de API, execuções de ferramentas, eventos de sessão. Eu só leio estas quando estou depurando um problema específico.

DEBUG: Estado interno detalhado para 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 investigando um bug específico.

A chave: em produção, opero no nível INFO. Isso me dá detalhes suficientes para diagnosticar a maioria dos problemas sem o ruído do DEBUG. Eu mudo para DEBUG temporariamente ao investigar problemas específicos, e depois volto.

Registro Estruturado

Logs em texto simples são difíceis de pesquisar e impossíveis de agregar. Eu mudei para registro estruturado em JSON:

Em vez de: 2024-03-15 14:23:45 ERROR Chamada API falhou: timeout após 30s

Eu registro: um objeto JSON com timestamp, nível, tipo de evento, modelo, erro, duração, ID da sessão e ID da solicitação.

O formato JSON me permite:
– Pesquisar por qualquer campo (todos os erros para a sessão X, todos os timeouts para o modelo Y)
– Agregar métricas (tempo médio de resposta por modelo por hora)
– Construir dashboards (Grafana pode ler logs JSON diretamente)
– Correlacionar eventos (seguir uma solicitação desde a chegada até o processamento e a resposta)

A compensação: logs JSON são menos legíveis para humanos quando você está acompanhando o arquivo de log. Eu uso uma ferramenta de visualização de logs que formata JSON de forma agradável para monitoramento em tempo real.

Rotação e Retenção de Logs

Os logs de agentes de IA crescem rapidamente. Uma instância do OpenClaw moderadamente ativa gera de 50 a 200 MB de logs por dia no nível INFO. Sem rotação, seu disco enche em semanas.

Minha política de retenção:
– Últimos 7 dias: logs completos (nível INFO), descompactados para acesso rápido
– Dias 8-30: logs compactados (gzipped, aproximadamente 10x de redução de tamanho)
– Dias 31-90: apenas entradas de ERROR e WARN (extraídas dos logs completos antes da exclusão)
– Além de 90 dias: apenas métricas agregadas mensais (sem logs brutos)

Isso mantém meu armazenamento total de logs abaixo de 5GB, enquanto mantém um 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. Verifique as últimas 10 entradas de ERROR — geralmente revela a causa imediata
2. Pesquise pelo mesmo tipo de erro na semana passada — isso é um problema recorrente ou um caso isolado?
3. Observe a linha do tempo em torno do erro — o que aconteceu nos 60 segundos antes do erro?
4. Verifique eventos correlacionados — o erro coincidiu com uma implantação, uma alteração de configuração ou uma falha de serviço externo?

Essa abordagem sistemática, combinada com bons logs, resolve a maioria dos problemas em 10-15 minutos. Antes da estruturação dos logs, os mesmos problemas levavam de 30 a 60 minutos, pois os passos 3 e 4 exigiam arqueologia manual de arquivos de log.

🕒 Published: April 5, 2026