Na primeira vez que um dos meus agentes parou de funcionar silenciosamente, eu não percebi por três dias. Três dias de relatórios programados perdidos. Três dias de mensagens automatizadas sem resposta. Três dias de um trabalho de monitoramento que não estava monitorando nada.
Meu cliente percebeu antes de mim. Foi constrangedor.
Então, eu configurei o Grafana para monitorar meus agentes como meus agentes monitoram todo o resto. Agora, eu sei em minutos quando algo está errado, e geralmente sei por quê antes mesmo de abrir um terminal.
O que monitorar (e o que não monitorar)
Quando eu inicialmente configurei a monitoração, estava monitorando tudo. Os tempos de resposta por requisição, o número de tokens por mensagem, as pontuações de confiança dos modelos, o uso de memória por sessão, as taxas de erro por tipo, os histogramas de latência… 47 métricas em 12 painéis.
Olhei para esse painel por uma semana. Então percebi que estava olhando apenas para quatro coisas:
Está funcionando? Verificação simples de ligar/desligar. Ponto verde = o processo está vivo e respondendo. Isso permite detectar falhas, travamentos e quedas na infraestrutura.
Está lento? Tempo de resposta médio nos últimos 5 minutos. Normalmente, 2-3 segundos. Quando ultrapassa 8 segundos, algo está errado — geralmente uma sobrecarga de contexto ou problemas com o fornecedor da API.
Está falhando? Taxa de erro em percentual do total de requisições. Abaixo de 2%, é normal (timeouts de API ocasionais). Acima de 5%, isso significa problemas sistêmicos.
Está caro? Custo operacional do dia atual comparado à média diária. Um pico de 2x significa que algo está gerando requisições anormalmente longas ou frequentes.
Reduzi meu painel a essas quatro métricas. Uma linha, quatro grandes números com um código de cores. Isso é o que vejo 10 vezes por dia. Todo o resto está em uma página de “detalhes” que consulto apenas durante a depuração.
A configuração
Coleta de dados: Eu escrevi um pequeno script que analisa os logs do OpenClaw e expõe as métricas no formato Prometheus. Ele é executado como um processo em segundo plano e extrai o arquivo de log a cada 30 segundos. Cerca de 50 linhas de código. Nada de especial.
As métricas que ele expõe:
– openclaw_requests_total (contador, etiquetado por tipo)
– openclaw_response_seconds (histograma)
– openclaw_errors_total (contador, etiquetado por tipo de erro)
– openclaw_tokens_used (contador, etiquetado por direção: entrada/saída)
– openclaw_process_up (gauge, 1 ou 0)
Prometheus extrai essas métricas a cada 15 segundos. A retenção padrão é de 15 dias, o que é suficiente para minhas necessidades. O Prometheus roda no mesmo servidor que o OpenClaw — ele utiliza cerca de 100 MB de RAM para essa pequena carga de trabalho.
Grafana visualiza as métricas. Estou usando o nível gratuito do Grafana Cloud (10.000 métricas, o que é mais que suficiente). Você também pode auto-hospedar o Grafana no mesmo servidor — é leve.
Tempo total de configuração: cerca de 2 horas na primeira vez. A maior parte do tempo foi dedicada à escrita do analisador de logs.
Os alerts que funcionam
Eu tenho quatro alertas. Ajustei seus limites durante três meses para minimizar os falsos positivos:
Processo parado por > 2 minutos. Ativa-se se a verificação de ligar/desligar falhar por dois minutos consecutivos. Dois minutos dão margem suficiente para reinicializações e pequenas quedas de rede. Isso envia uma notificação push para meu telefone.
Tempo de resposta p95 > 15 segundos por 5 minutos. Uma única resposta lenta não importa. Cinco minutos de respostas consistentemente lentas significa que algo está errado de forma sistemática. Isso se publica no meu canal de alertas Slack.
Taxa de erro > 10 % durante 3 minutos. Eu defini isso mais alto do que você poderia esperar (10 % em vez de 5 %) porque explosões breves de tempo de espera da API são normais durante a manutenção do provedor. Três minutos de erros elevados sustentados significam que não é um simples incidente. Notificação no telefone.
Custo diário > 3x a média móvel. Verificado a cada hora. Captura loops indesejados e padrões de uso inesperados antes que se tornem caros. Alerta no Slack apenas — isso é informativo, não urgente.
Eu removi dois alertas que eram barulhentos demais: “toda solicitação única > 30 segundos” (isso acontecia com muita frequência durante tarefas complexas de agente) e “uso de memória > 80 %” (sem interesse — Node.js gerencia sua própria coleta de lixo e explosões breves são normais).
O painel que detectou problemas reais
Fevereiro: Inchaço gradual do contexto. Os tempos de resposta aumentaram de 2,5 s para 7 s em duas semanas. A curva de tendência era evidente no painel — as solicitações individuais pareciam corretas, mas a média diária aumentava. Causa raiz: os contextos de conversa cresciam porque a compactação não era acionada corretamente. Um ajuste de configuração normalizou os tempos de resposta em uma hora.
Março: Pico de custo devido a um loop. Um job cron tinha um mecanismo de re-tentativa que, devido a um bug, continuava tentando indefinidamente quando a API retornava um código de erro específico. O alerta de custo diário disparou a 2x a média. Eu o capturei em menos de 2 horas. Sem o alerta, isso teria continuado até que a chave da API atingisse seu limite de gastos.
Março: Falha silenciosa do cron. Meu job de relatório diário parou de ser executado. Sem erro — ele simplesmente não foi executado. O painel mostrou que o pico de atividade esperado às 8h estava ausente. O agendador cron havia travado após uma atualização. Reiniciá-lo resolveu o problema, e eu adicionei o alerta de processo parado especificamente para o agendador.
O que eu diria ao meu eu do passado
Comece com as quatro métricas básicas. Adicione complexidade somente quando você tiver uma necessidade específica de depuração. A maioria dos painéis de monitoramento falha porque são muito complexos — você constrói 20 painéis, fica sobrecarregado com os dados e para completamente de olhar para o painel.
O painel que você realmente usa é melhor do que o painel que acompanha tudo. Torne-o rápido de ler, faça com que os alertas sejam acionáveis e revise os limites todo mês. Essa é toda a estratégia.
🕒 Published: