Monitorando Agentes com Grafana: Minha Abordagem Testada e Aprovada

Na primeira vez que um dos meus agentes parou de funcionar silenciosamente, não percebi por três dias. Três dias de relatórios programados perdidos. Três dias de mensagens automatizadas não respondidas. Três dias de um trabalho de monitoramento que não estava monitorando nada.

Meu cliente percebeu antes de eu notar. Isso foi embaraçoso.

Então, configurei o Grafana para monitorar meus agentes da mesma forma que meus agentes monitoram tudo o mais. Agora sei dentro de minutos quando algo dá errado, e geralmente sei o porquê antes mesmo de abrir um terminal.

O que Monitorar (E o que Não Monitorar)

Quando configurei o monitoramento pela primeira vez, rastreei tudo. Tempos de resposta por solicitação, contagens de tokens por mensagem, pontuações de confiança do modelo, uso de memória por sessão, taxas de erro por tipo, histogramas de latência… 47 métricas em 12 painéis.

Olhei para aquele painel por uma semana. Então percebi que só estava observando 4 coisas:

Está funcionando? Verificação simples de up/down. Ponto verde = processo está ativo e respondendo. Isso captura falhas, travamentos e falhas de infraestrutura.

Está lento? Tempo médio de resposta nos últimos 5 minutos. Normalmente de 2 a 3 segundos. Quando ultrapassa 8 segundos, algo está errado — geralmente inchaço de contexto ou problemas no provedor de API.

Está falhando? Taxa de erro como uma porcentagem do total de solicitações. Abaixo de 2% é normal (timeouts ocasionais de API). Acima de 5% significa problemas sistemáticos.

Está caro? Custo de operação para o dia atual comparado à média diária. Um pico de 2x significa que algo está gerando solicitações inesperadamente longas ou frequentes.

Reduzi meu painel a essas quatro métricas. Uma linha, quatro grandes números com codificação de cores. Isso é o que olho 10 vezes por dia. Todo o resto está em uma página de “detalhes” que visito apenas quando estou depurando.

A Configuração

Coleta de dados: Escrevi um pequeno script que analisa os logs do OpenClaw e expõe métricas no formato do Prometheus. Ele roda como um processo auxiliar e coleta 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, rotulado por tipo)
– openclaw_response_seconds (histograma)
– openclaw_errors_total (contador, rotulado por tipo de erro)
– openclaw_tokens_used (contador, rotulado por direção: entrada/saída)
– openclaw_process_up (gauge, 1 ou 0)

Prometheus coleta essas métricas a cada 15 segundos. A retenção padrão é de 15 dias, o que é suficiente para as minhas necessidades. O Prometheus roda no mesmo servidor que o OpenClaw — utiliza cerca de 100MB de RAM para esta pequena carga de trabalho.

Grafana visualiza as métricas. Uso o plano gratuito do Grafana Cloud (10.000 métricas, que é bastante). Você também pode hospedar o Grafana no mesmo servidor — é leve.

Tempo total de configuração: cerca de 2 horas na primeira vez. A maior parte disso foi escrever o analisador de logs.

Os Alertas Que Funcionam

Tenho quatro alertas. Ajustei seus limites ao longo de três meses para minimizar falsos positivos:

Processo inativo por > 2 minutos. Aciona se a verificação de up/down falhar por dois minutos consecutivos. Dois minutos dão uma margem suficiente para reinicializações e breves falhas de rede. Isso envia uma notificação para o 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á sistematicamente errado. Isso publica no meu canal de alertas do Slack.

Taxa de erro > 10% por 3 minutos. Configurei isso mais alto do que você poderia esperar (10% em vez de 5%) porque picos breves de timeout da API são normais durante a manutenção do provedor. Três minutos de erros altos sustentados significa que não é uma falha passageira. Notificação no telefone.

Custo diário > 3x média móvel. Verificado a cada hora. Detecta loops infinitos e padrões de uso inesperados antes que se tornem caros. Alerta apenas no Slack — isso é informativo, não urgente.

Removi dois alertas que eram muito barulhentos: “qualquer solicitação única > 30 segundos” (acontecia com muita frequência durante tarefas complexas de agentes) e “uso de memória > 80%” (irrelevante — o Node.js gerencia sua própria coleta de lixo e picos breves são normais).

O Painel Que Capturou Problemas Reais

Fevereiro: Inchaço gradual de contexto. Os tempos de resposta aumentaram de 2,5s para 7s ao longo de duas semanas. A linha de tendência era óbvia no painel — solicitações individuais pareciam boas, mas a média diária estava subindo. Causa raiz: os contextos de conversação estavam crescendo porque a compactação não estava sendo acionada corretamente. Uma correção de configuração trouxe os tempos de resposta de volta ao normal em menos de uma hora.

Março: Aumento de custo devido a um loop. Um job cron tinha um mecanismo de retry que, devido a um bug, continuou tentando indefinidamente quando a API retornou um código de erro específico. O alerta diário de custo disparou a 2x da média. Eu o identifiquei em 2 horas. Sem o alerta, teria funcionado até que a chave da API atingisse seu limite de gastos.

Março: Falha silenciosa no cron. Meu job de relatório diário parou de rodar. Sem erro — simplesmente não executou. O dashboard mostrou que o pico de atividade esperado às 8 AM estava ausente. O agendador cron tinha travado após uma atualização. Reiniciá-lo resolveu o problema, e eu adicionei o alerta de processo-down para o agendador especificamente.

O Que Eu Diria Para Meu Eu Passado

Comece com as quatro métricas básicas. Adicione complexidade apenas quando tiver uma necessidade específica de depuração. A maioria dos dashboards de monitoramento falham porque são muito complexos — você cria 20 painéis, fica sobrecarregado com os dados, e para de olhar para o dashboard completamente.

O dashboard que você realmente usa supera o dashboard que rastreia tudo. Torne-o visualizável, faça os alertas acionáveis e revise os limites mensalmente. Essa é toda a estratégia.

🕒 Published: April 5, 2026