Observabilidade de workflows n8n: logs, métricas e alertas

Por que workflows sem observabilidade viram caixa preta

Observabilidade é a capacidade de entender o estado interno de um sistema a partir dos seus outputs. Para workflows n8n, isso significa: conseguir responder "o que está acontecendo agora?" e "o que aconteceu?" sem precisar entrar no servidor, olhar logs brutos ou pedir para alguém rodar o workflow manualmente para ver se funciona.

Sem observabilidade, você só descobre que um workflow parou de funcionar quando o cliente reclama. Ou quando o vendedor percebe que os leads não estão chegando no CRM. Ou quando alguém nota que o relatório semanal não chegou. Em todos esses casos, o dano já aconteceu.

O custo de um workflow crítico parado por 8 horas sem ninguém perceber pode ser alto: leads perdidos, atendimentos sem resposta, dados desincronizados. Observabilidade não é overhead — é proteção do investimento que você fez na automação.

O n8n tem observabilidade básica embutida (painel de execuções, logs por nó). O problema é que ela é reativa — você vai lá checar. O que precisamos é de observabilidade proativa: o sistema te avisa antes de você precisar checar.

Logging estruturado: o que registrar e como

Log estruturado significa logar em formato JSON, com campos consistentes, em vez de mensagens de texto livre. A diferença é que texto livre é pesquisável por humano, JSON é pesquisável por máquina — e você pode construir dashboards, alertas e consultas em cima dele.

Em cada workflow n8n crítico, adicione um nó de código no início e outro no final (e em pontos de erro). O nó inicial gera o log de entrada:

// Nó de código: Log de início
const logEntrada = {
  nivel: "info",
  workflow: $workflow.name,
  execucaoId: $execution.id,
  trigger: $input.first().json,
  timestamp: new Date().toISOString(),
  ambiente: process.env.NODE_ENV || "producao"
};

// Enviar para banco de logs ou Webhook do Datadog/Logtail
return [{ json: logEntrada }];

O nó de erro, no bloco catch, captura:

const logErro = {
  nivel: "error",
  workflow: $workflow.name,
  execucaoId: $execution.id,
  no: $node.name,          // em qual nó ocorreu o erro
  erro: $error.message,
  stack: $error.stack,
  payloadEntrada: $input.first().json, // dados que causaram o erro
  timestamp: new Date().toISOString()
};

O que NÃO logar: dados pessoais identificáveis (nome, CPF, e-mail, telefone) nos logs estruturados. Use IDs internos e mascare os campos sensíveis. Isso é tanto boa prática de LGPD quanto prevenção de logs como vetor de vazamento.

Onde armazenar os logs

• Opção gratuita: planilha Google Sheets via nó nativo do n8n. Simples, sem custo, mas difícil de consultar com volume alto.
• Opção intermediária: Logtail (Better Stack) — plano gratuito aceita 1 GB/mês, interface boa para busca e filtro.
• Opção avançada: Elasticsearch + Kibana ou Datadog Logs — custo mensal mas com poder de correlação e dashboard completo.

KPIs de observabilidade: 10 métricas essenciais

A tabela abaixo define as métricas mais importantes para monitorar workflows n8n em produção, com metas típicas e como calcular cada uma:

Integração com Grafana, Datadog e Sentry

Grafana (solução open-source, self-hosted)

A combinação Prometheus + Grafana é a mais comum para n8n self-hosted. Configure assim:

1. Habilite métricas Prometheus no n8n: N8N_METRICS=true
2. Suba o Prometheus via Docker e configure para scraping do endpoint http://n8n:5678/metrics a cada 15s
3. Adicione Prometheus como datasource no Grafana
4. Importe o dashboard oficial do n8n (ID 17594 no Grafana.com) como ponto de partida

Custo: apenas infraestrutura. Um servidor de 2GB RAM adicional cobre Prometheus + Grafana para a maioria dos casos.

Datadog (SaaS, mais fácil de configurar)

Datadog tem agent que coleta métricas do sistema automaticamente. Para métricas do n8n, você envia via DogStatsD (UDP) do nó de código do n8n. O plano básico custa ~US$ 15/mês para infraestrutura monitorada. A vantagem é o dashboard pronto e o sistema de alertas visual sem configuração de YAML.

Sentry (para rastreamento de erros)

Sentry captura exceções com stack trace, contexto e user journey. No n8n, você integra via HTTP Request nos nós de erro — ao capturar uma exceção, o código envia os detalhes para a API do Sentry. Isso gera um rastreador de bug centralizado com agrupamento automático de erros similares, facilitando priorizar o que corrigir primeiro.

Sentry tem plano gratuito com 5.000 erros/mês — suficiente para a maioria das PMEs.

Alertas proativos: ser avisado antes do cliente reclamar

Um alerta bem configurado tem três características: (1) dispara na condição certa — nem tarde demais, nem ruidoso demais; (2) chega para a pessoa certa, pelo canal certo; (3) inclui contexto suficiente para agir sem precisar investigar primeiro.

Alertas por nível de severidade

• Crítico (Slack + SMS): workflow de atendimento parou de processar há mais de 5 minutos; taxa de erro acima de 20% nos últimos 10 minutos; fila Redis acima de 500 itens
• Aviso (Slack): taxa de erro acima de 5% nos últimos 30 minutos; latência P95 aumentou 100% em relação à média do dia anterior; dead-letter rate acima de 1%
• Informativo (resumo diário): total de execuções do dia, taxa de sucesso, top 3 workflows por volume, top 3 erros mais comuns

Implementação no próprio n8n

Um workflow de monitoramento cron a cada 5 minutos pode fazer verificações básicas: conta execuções com erro nos últimos 5 minutos, verifica tamanho da fila Redis, checa se os workflows críticos tiveram pelo menos 1 execução na última hora. Se qualquer condição for violada, envia mensagem Slack com contexto.

Esse workflow de monitoramento deve ser o único que roda independente do Redis — em modo síncrono — para não ser afetado por problemas na fila que ele mesmo monitora.

Runbook de incidente: o que fazer quando algo quebra

Runbook é um guia passo a passo para responder a incidentes. O objetivo é que qualquer pessoa do time consiga executar — não só o engenheiro que construiu o sistema. Isso resolve o problema de dependência de pessoa-chave.

Estrutura do runbook para n8n

Passo 1 — Triagem (5 minutos): Qual workflow está afetado? Qual o impacto (atendimento, vendas, relatório)? Qual o erro no Slack de alerta? Quantas execuções afetadas?

Passo 2 — Verificação básica (10 minutos): O n8n está respondendo? (acesse o painel). O Redis está saudável? (redis-cli ping). As APIs externas estão no ar? (cheque o status page do OpenAI, Z-API, etc.). O banco de dados está acessível?

Passo 3 — Ação por tipo de problema:

• API externa fora do ar: verificar status page do fornecedor. Se confirmado, aguardar resolução. Notificar stakeholders. Reprocessar da DLQ quando a API voltar.
• Fila Redis travada: reiniciar o processo worker do n8n (docker restart n8n-worker). Se persistir, verificar memória disponível no servidor.
• Erro de credencial (401/403): verificar se token OAuth2 expirou. Re-autorizar no painel de credenciais do n8n. Verificar se API key foi rotacionada sem atualizar no n8n.
• Volume anormal de erros: pausar temporariamente o workflow afetado pelo painel. Investigar padrão nos logs. Corrigir e reativar.

Passo 4 — Pós-incidente: Registrar em documento: quando começou, como foi detectado, causa raiz, tempo de resolução, ação preventiva. Se o incidente levou mais de 1 hora para ser detectado, revisar os alertas.

O runbook deve estar no Notion ou Confluence, linkado diretamente da mensagem de alerta no Slack. "Veja runbook: [link]" economiza 15–20 minutos de busca no momento de pressão.

Conclusão: observabilidade é respeito pelo seu próprio sistema

Montar um workflow n8n e deixá-lo rodar sem monitoramento é como instalar um alarme de incêndio sem bateria. Você tem a sensação de segurança, mas na hora que importa, não funciona.

Os 10 KPIs da tabela, o logging estruturado e o runbook de incidente deste artigo formam o baseline mínimo de observabilidade para qualquer workflow crítico. A implementação de nível básico (alertas no Slack + log em planilha) leva meio dia. O nível avançado (Grafana + Datadog + Sentry) leva 2–3 dias.

Não espere o primeiro incidente em produção para implementar. Implemente antes — e quando o incidente acontecer (porque vai acontecer), você vai agradecer.