Como criar um watchdog de automações que detecta falhas antes do cliente reclamar

watchdog de automações parece nome de peça chata de infraestrutura, daquelas que só aparecem quando tudo já pegou fogo. Mas é exatamente o tipo de automação que separa um sistema útil de uma coleção de scripts confiantes demais. O problema real não é a automação quebrar. Ela vai quebrar. O problema é quebrar em silêncio, sorrindo para o log, enquanto você acha que a máquina está trabalhando.

Hoje vamos construir mentalmente, e com exemplos práticos, um watchdog de automações: uma camada simples para vigiar rotinas automatizadas, medir sinais de vida, detectar atraso, capturar contexto e avisar antes que alguém descubra o problema por acidente. A categoria escolhida para este artigo foi Lab da Garra, e o tema é watchdog para rotinas automatizadas com heartbeat, logs e alerta de falha silenciosa.

1. O erro mais caro: confiar no sucesso anterior

Existe uma superstição muito comum em times pequenos: se uma automação rodou ontem, provavelmente vai rodar amanhã. Eu entendo. Já fiz isso. Já olhei para um cron verde, fechei o notebook e aceitei uma paz que não existia. No dia seguinte, descobri que o job tinha executado, sim, mas não tinha feito nada útil. Tecnicamente estava vivo. Operacionalmente estava morto.

Um watchdog resolve justamente essa ambiguidade. Ele não pergunta apenas se o processo iniciou. Ele pergunta se o processo produziu o resultado esperado dentro de uma janela aceitável. Essa diferença parece pequena, mas muda tudo. Um script que baixa relatórios pode terminar com código zero e ainda assim baixar um arquivo vazio. Um robô que publica posts pode receber 200 da API e ainda assim criar conteúdo sem imagem, sem categoria ou com status errado. Um pipeline de dados pode completar a execução e deixar metade das linhas para trás.

A primeira virada de chave é abandonar o culto ao exit code. Código de saída ajuda, mas não é prova de entrega. Entrega precisa de evidência: registro, contagem, timestamp, checksum, status final e algum tipo de reconciliação com o objetivo do job.

2. O que um watchdog precisa vigiar

Um watchdog de automações decente deve observar quatro sinais. O primeiro é o heartbeat: o job avisou que começou, avançou e terminou? O segundo é a latência: demorou mais do que deveria? O terceiro é o resultado: publicou, enviou, processou, sincronizou ou apenas fingiu? O quarto é o contexto: quando falhar, você terá informação suficiente para corrigir sem fazer arqueologia em terminal às duas da manhã?

Eu gosto de pensar nesses sinais como uma ficha médica mínima. Não precisa transformar cada script em uma plataforma enterprise com dashboard cafona. Mas precisa saber se ele está respirando, se a pressão caiu, se houve hemorragia e onde está o prontuário.

• Heartbeat: registros pequenos de início, etapa e fim.
• Prazo: janela máxima esperada para cada rotina.
• Resultado verificável: contagem, ID, URL, arquivo, status ou hash.
• Erro útil: mensagem, etapa, payload resumido e tentativa de contorno.

3. Comece com um contrato de execução

Antes de escrever alerta, escreva contrato. Toda automação deveria conseguir responder: qual é o nome do job, qual execução está em andamento, quando começou, qual etapa está rodando, qual resultado precisa existir e qual condição define sucesso. Sem isso, o monitoramento vira fofoca: muita mensagem, pouca verdade.

Um contrato simples em JSON já resolve boa parte do caos. Ele pode ser salvo em arquivo, enviado para uma API interna, gravado em SQLite ou empurrado para uma tabela do WordPress se você estiver usando o CMS como painel operacional. O meio importa menos do que a consistência.

{
  "job": "publicacao-diaria-automente",
  "run_id": "2026-05-29T21:00:00Z",
  "status": "running",
  "step": "upload-featured-image",
  "started_at": "2026-05-29T21:00:03Z",
  "deadline_seconds": 600,
  "expected_result": "post_status_publish",
  "last_signal_at": "2026-05-29T21:02:41Z"
}

Repare que não há poesia nesse contrato. Bom. Infraestrutura não precisa de poesia; precisa de clareza. A poesia fica para o post, e olhe lá.

4. Defina sucesso como estado externo, não como sensação interna

O script sabe o que tentou fazer. O sistema externo sabe o que realmente aconteceu. Entre os dois existe um abismo onde bugs moram pagando aluguel barato. Por isso, o watchdog deve verificar o estado fora do processo sempre que possível.

Se a automação publicou no WordPress, consulte o post pelo ID e confirme status: publish. Se enviou email, confirme ID de mensagem ou log de envio. Se gerou um arquivo, confira tamanho, hash e data. Se sincronizou dados, compare contagens ou marcadores de versão. A verificação não precisa ser perfeita; precisa ser melhor do que acreditar na própria função.

post_id="1234"
status=$(curl -s "https://exemplo.com/wp-json/wp/v2/posts/$post_id?_fields=status" \
  | jq -r '.status')

if [ "$status" != "publish" ]; then
  echo "publicacao_nao_confirmada"
  exit 1
fi

Sim, o exemplo usa jq. Se você não tiver, use Python, PHP, Node ou qualquer ferramenta local confiável. O ponto é não transformar JSON em barbante com grep e fé. Fé é ótima para domingo. Para automação, prefiro parser.

5. Heartbeats: pouco barulho, muito sinal

O heartbeat ideal é pequeno. Ele não carrega o mundo nas costas; apenas diz que o job ainda existe e onde está. O erro comum é mandar logs inteiros para o canal de alerta. Isso parece transparência, mas vira ruído. Quando tudo apita, nada apita.

Use níveis. Heartbeat normal vai para armazenamento silencioso. Aviso vai para uma fila ou painel. Alerta vai para humano. Emergência acorda alguém, mas só se houver impacto real. Um job atrasado por trinta segundos talvez mereça observação. Um job de cobrança parado há duas horas merece prioridade. Um job experimental quebrado no domingo merece, no máximo, um suspiro.

async function heartbeat(client, run) {
  await client.upsert("automation_runs", {
    run_id: run.id,
    job: run.job,
    step: run.step,
    status: "running",
    last_signal_at: new Date().toISOString()
  });
}

O detalhe importante é o upsert. Heartbeat não deveria criar uma pilha infinita de registros inúteis. Para histórico, registre eventos separados. Para estado atual, mantenha uma linha por execução ou por job.

6. Timeout não é falha; é diagnóstico

Muita gente trata timeout como erro genérico. Péssima ideia. Timeout é uma pista. Ele diz que o sistema ficou preso em alguma fronteira: rede, API externa, lock de banco, arquivo grande, limite de rate, DNS, autenticação pendurada ou uma dependência que resolveu meditar sem avisar.

Um watchdog bom não apenas marca timeout. Ele informa a etapa parada, o último sinal, a duração esperada e a duração real. Com isso, você descobre padrões. Talvez a busca de imagem sempre demore mais às segundas. Talvez o endpoint de tags do WordPress esteja respondendo lentamente quando há muitas tags. Talvez seu script esteja baixando imagem em resolução absurda para depois reduzir. O computador não está sendo misterioso; a gente é que costuma perguntar mal.

Box perrengue: uma vez eu investiguei uma automação que “falhava aleatoriamente”. Não era aleatório. A imagem de capa vinha de uma URL enorme, o download passava do limite em conexões móveis, o upload era repetido três vezes e o script engolia a falha para tentar ser resiliente. Resultado: post publicado sem imagem e um log com cara de sucesso. Resiliência sem evidência é maquiagem em vazamento.

7. Logs estruturados: pare de escrever romance policial

Log bom não é aquele que conta uma história bonita. É aquele que permite filtro. A frase “deu erro ao publicar” pode até desabafar, mas não ajuda. Use campos. Job, run_id, etapa, status, duração, tentativa, código HTTP, recurso afetado e mensagem curta. Quando você precisar buscar padrões, esses campos pagam o próprio aluguel.

{
  "level": "error",
  "job": "daily_publish",
  "run_id": "2026-05-29T21:00:00Z",
  "step": "verify_post",
  "http_status": 200,
  "post_id": 4821,
  "expected": "publish",
  "actual": "draft",
  "duration_ms": 1840
}

Outra regra: log não deve vazar segredo. Parece óbvio até alguém imprimir header de autorização “só para debug”. Se você está monitorando automações, redija tokens, senhas, cookies e payloads sensíveis. Um watchdog que cria um vazamento novo para observar um problema antigo é uma solução com autoestima demais.

8. Alertas acionáveis vencem alertas dramáticos

Um alerta bom responde três perguntas: o que quebrou, qual é o impacto e qual é a próxima ação provável. “Erro no job” não responde nenhuma. “Publicação diária não confirmou status publish em 10 minutos; último passo foi upload de mídia; verificar credencial WordPress e resposta do endpoint /media” já coloca o humano na direção certa.

Eu gosto de alertas com formato fixo:

• Resumo: uma linha com o problema.
• Impacto: o que deixou de acontecer.
• Última etapa: onde parou.
• Evidência: ID, URL, código HTTP ou trecho sanitizado.
• Ação sugerida: o primeiro diagnóstico razoável.

Isso parece burocracia até a primeira falha real. Depois vira carinho operacional. Um alerta claro reduz ansiedade porque troca “tem algo errado” por “tem isto errado aqui”.

9. Retries com limite e memória

Retry é remédio. Em dose certa salva. Em dose errada intoxica. Um watchdog deve saber quando uma falha foi tentada de novo, quantas vezes, com qual intervalo e se o resultado mudou. Repetir uma chamada que falha por autenticação dez vezes só transforma um erro simples em spam contra a API.

Use backoff, classifique erros e registre tentativas. Falha 429 pede espera. Falha 500 pode aceitar retry. Falha 401 pede parar e avisar. Falha de validação pede corrigir dado, não insistir como se o servidor fosse mudar de opinião por cansaço.

def should_retry(status_code):
    if status_code in (408, 429, 500, 502, 503, 504):
        return True
    if status_code in (400, 401, 403, 404, 422):
        return False
    return False

O mais importante: retries precisam ser visíveis. Se uma rotina só funciona na terceira tentativa todos os dias, ela não está saudável. Ela está dando tempo para você perceber.

10. Um desenho mínimo de arquitetura

Você não precisa começar com Kubernetes, Prometheus, Grafana e uma pasta chamada plataforma como se isso automaticamente aumentasse a maturidade da operação. Um desenho mínimo pode ser suficiente: cada job grava estado, um verificador roda periodicamente, o verificador compara prazos e resultados, e só então envia alerta.

Em projetos pequenos, SQLite resolve. Em projetos WordPress, uma tabela customizada ou post type interno pode resolver. Em ambientes com mais volume, uma fila e um banco dedicado fazem sentido. A arquitetura certa é aquela que você consegue operar sem virar refém do próprio painel.

CREATE TABLE automation_runs (
  run_id TEXT PRIMARY KEY,
  job TEXT NOT NULL,
  status TEXT NOT NULL,
  step TEXT,
  expected_result TEXT,
  result_ref TEXT,
  started_at TEXT NOT NULL,
  last_signal_at TEXT NOT NULL,
  finished_at TEXT,
  error_summary TEXT
);

Com essa tabela simples, já dá para listar jobs travados, medir duração média e descobrir qual etapa mais quebra. Não é glamouroso. Funciona. Existe uma beleza discreta em coisas que funcionam sem pedir aplauso.

11. Como aplicar isso no WordPress sem criar um monstro

Se sua automação conversa com WordPress, trate a REST API como fonte de verificação. Publicou post? Busque o post pelo ID. Subiu imagem? Busque a mídia e confirme ID, URL e alt text. Criou tag? Confirme que recebeu um inteiro, não uma mensagem de erro embrulhada em JSON. O WordPress é flexível, o que é um elogio e uma ameaça dependendo do dia.

Também vale criar links internos de apoio. Se o artigo pertence à categoria operacional, ligue para a página da categoria, como Produtividade Aumentada, Log de Erros ou Fortaleza Digital. Isso ajuda o leitor a continuar a jornada e ajuda o site a formar clusters semânticos decentes.

Mas não transforme o WordPress no lugar onde segredos moram. App passwords, tokens e chaves de API devem ficar no ambiente de execução ou em um cofre. O CMS pode registrar metadados operacionais, não credenciais cruas. O banco de produção não é gaveta de bagunça.

12. Checklist prático para implementar hoje

Se eu fosse implementar esse watchdog em uma tarde, faria assim: primeiro, escolheria três automações críticas. Não todas. Todas é palavra que costuma atrasar projetos bons. Depois, adicionaria um run_id único e registros de início, etapa e fim. Em seguida, criaria uma verificação externa do resultado. Só então colocaria alertas.

• Escolha jobs com impacto real.
• Defina a condição objetiva de sucesso.
• Grave heartbeat com run_id e etapa.
• Registre duração e tentativas.
• Verifique resultado consultando o sistema externo.
• Crie alerta com impacto e próxima ação.
• Revise semanalmente os falsos positivos.

Esse último item é subestimado. Watchdog que alerta errado perde credibilidade. Quando o humano aprende que pode ignorar, acabou. A ferramenta vira decoração barulhenta.

13. Métricas que realmente importam

Não comece medindo vinte coisas. Meça poucas e boas: taxa de sucesso, duração média, duração p95, falhas por etapa, retries por execução e tempo até detecção. O tempo até detecção é a métrica que mais dói, porque mostra por quanto tempo você ficou no escuro.

Depois, meça tempo até correção. Se detectar rápido mas corrigir devagar, talvez falte contexto no alerta. Se corrigir rápido mas detectar tarde, falta vigilância. Se tudo demora, falta simplicidade. Nenhum painel resolve arquitetura confusa sozinho, por mais bonito que seja o tema escuro.

14. Onde a IA entra sem virar enfeite

IA pode ajudar muito na análise de logs, agrupamento de falhas parecidas, sugestão de causa provável e geração de resumos para humanos. Mas eu colocaria IA depois do básico estruturado. Jogar log caótico em modelo de linguagem pode funcionar uma vez, mas vira loteria. Dados limpos primeiro, inteligência depois.

Um bom uso é pedir para a IA resumir os eventos de uma execução com base em campos estruturados: etapas, timestamps, códigos HTTP, mensagens sanitizadas e resultado esperado. Outro uso é agrupar falhas recorrentes e sugerir documentação. A IA deve reduzir o trabalho de leitura, não substituir a verificação objetiva.

15. Conclusão: automação adulta precisa prestar contas

Automação boa não é a que nunca falha. Essa não existe. Automação boa é a que falha de forma visível, explica o que aconteceu e dá caminho para correção. Um watchdog de automações é exatamente essa camada de maturidade: pequena o suficiente para nascer rápido, importante o suficiente para evitar prejuízo e humilde o suficiente para admitir que scripts mentem sem querer.

Se você tem uma rotina automática rodando hoje sem heartbeat, sem verificação externa e sem alerta acionável, ela não está automatizada. Está apenas sem supervisão. E sistemas sem supervisão têm um talento especial para escolher o pior horário possível para revelar personalidade.

CTA: qual automação você quer ver destrinchada no próximo artigo da AutoMente? Uma rotina de publicação, triagem de emails, backup inteligente, monitoramento de vendas, integração com WordPress ou algum processo mais vergonhosamente específico? Manda a ideia. As melhores automações nascem justamente onde a bagunça está mais cara.