Monitoramento e Execuções

Todo cron worker mantém 30 dias de histórico de execuções, integra com a topologia do projeto, emite traces OpenTelemetry e escreve entradas de audit log para cada mutação. Esta página explica como usar essas superfícies para monitorar e debugar.

A página de detalhe do worker

Abra um worker pela aba Cron Workers do projeto. A página de detalhe entrega tudo num lugar só:

Um badge de status — active, suspended ou deleted.
O próximo disparo agendado com contador ao vivo, calculado a partir da expressão cron e do timezone.
Um resumo da última execução com timestamp e desfecho.
A tabela de histórico de execuções (mais novo primeiro, paginada).
Botões de ação: Disparar agora, Pausar / Retomar, Editar destino, Excluir.

Enquanto uma execução está em andamento, a página faz polling do histórico em intervalos curtos e atualiza no lugar — você não precisa dar refresh.

Histórico de execuções

Cada linha da tabela é uma execução com estas colunas:

Coluna	O que mostra
Status	`running`, `success` ou `failed`.
Disparado por	`schedule` (a expressão cron disparou) ou `manual` (você clicou no botão).
Tentativa	Qual tentativa é esta (1 de N). Retentativas aparecem como tentativas separadas.
Programado para	O timestamp do slot do cron (só preenchido em execuções agendadas). Útil para detectar drift entre slot e início.
Iniciado	Quando a tentativa de fato rodou.
Finalizado	Quando a tentativa terminou (ou `—` se ainda em execução).
Duração	Tempo decorrido da tentativa.
Motivo da falha	Código estruturado (por exemplo, `timeout`, `http_5xx`, `ssrf_blocked`) — só em execuções falhas.

Clicar numa linha expande para mostrar a mensagem de erro completa (quando falha) e o payload resolvido que foi de fato enviado.

Drift entre programado e iniciado

Se o Iniciado for visivelmente depois do Programado para, o slot do cron ficou na fila por algum tempo antes de rodar. Causas comuns:

Uma transição curta de liderança no orchestrator (em geral sub-segundo, nunca mais que poucos segundos).
Uma execução anterior ainda em voo, com a concorrência limitada a 1.
O destino demorou para aceitar a conexão.

Drift de poucos segundos é normal. Drift acima de um minuto costuma indicar problema no destino — confira as execuções falhas em volta do mesmo horário.

Disparos manuais

O botão Disparar agora dispara o worker sob demanda, fora do schedule. Use para:

Testar um worker novo sem esperar pelo próximo slot.
Fazer backfill de uma execução perdida depois de corrigir um problema no destino.
Verificar conectividade depois de mudar uma variável de ambiente.

Disparos manuais passam pelo mesmo pipeline de retry, timeout e auditoria que execuções agendadas. Aparecem no histórico com Disparado por: manual e scheduled_for vazio.

O botão tem rate limit por worker para evitar enxurradas acidentais. Se você bater o limite, o dashboard mostra uma mensagem amigável e você pode tentar de novo em poucos segundos.

Pausar, retomar e excluir

Pausar interrompe os próximos disparos agendados. O worker mantém configuração e histórico; execuções já em voo terminam normalmente.
Retomar reinicia o schedule a partir do próximo slot. Sem catch-up — execuções perdidas durante a pausa não são repostas.
Excluir remove o worker permanentemente. O histórico de execuções também vai junto. Há um diálogo de confirmação.

Na topologia do projeto

Cron workers aparecem como nodes no mapa de topologia do projeto. Usam um ícone de relógio e borda tracejada para se distinguir dos serviços. Uma aresta cron_trigger conecta o worker ao seu destino.

As arestas de cron são desenhadas na cor secundária da marca, com linha tracejada e sem a animação usada para tráfego ao vivo — cron é agendado, não contínuo. Arestas de cron também são excluídas da agregação de taxa de requisições e taxa de erros na topologia, para que um worker barulhento não distorça suas métricas de tráfego entre serviços.

Clique em um node de cron no mapa para ir direto à página de detalhe.

Nos seus traces

Cada disparo abre um span OpenTelemetry e propaga um header W3C traceparent para o destino. Isso significa que um trigger que faz POST no seu serviço aparece em Traces como um único trace cobrindo:

O span cron.trigger.fire do cron worker.
O span da requisição HTTP no serviço receptor.
Tudo o que aquele serviço faz como consequência.

Se o seu job se ramifica (chamadas HTTP downstream, publicações em fila), tudo cai no mesmo trace, desde que você propague os headers no seu código.

Audit logging

Toda mutação em um cron worker é gravada nos seus Audit Logs com usuário, timestamp, IP, ação e o diff dos campos alterados. As ações são:

cron_worker.create
cron_worker.update
cron_worker.suspend
cron_worker.resume
cron_worker.delete
cron_worker.manual_trigger

Você pode filtrar o audit log por action_type para ver só atividade de cron worker, e por outcome (success / failed) para encontrar mutações que falharam.

Investigando falhas — checklist

Quando uma execução falha, siga este checklist:

Leia o failure_reason. Ele aponta para a camada da falha (rede, protocolo, destino, etc.) antes mesmo de você ler a mensagem.
Confira o trace — abra o trace pela linha da execução. O waterfall mostra se o serviço destino chegou a receber a requisição e como respondeu.
Confira os logs do destino. Abra o serviço destino no dashboard e veja os logs em volta do started_at da execução.
Confira a conectividade. Em destinos HTTP, dispare manualmente o worker — se passar, o schedule está bom e a falha original foi transitória.
Confira as credenciais. Um failure_reason: credential significa que as credenciais do serviço de catálogo não puderam ser resolvidas ou foram rejeitadas. Reinicie o serviço de catálogo e tente de novo.

Se a falha é repetível e você não consegue resolver, fale com o suporte mandando o run ID — o audit log e o trace referenciam ele, então o suporte encontra tudo em segundos.

Pela CLI

O mesmo histórico está disponível em guara crons runs <slug> — visão de tabela por padrão, cards com borda quando você passa --detail, tail ao vivo append-only com --watch. Use quando estiver investigando direto do shell, montando checks em CI, ou esperando uma execução cair depois de corrigir algo.

guara crons runs hourly                            # Tabela, últimas 20 execuções
guara crons runs hourly --status failed            # Filtra apenas as que falharam
guara crons runs hourly --detail                   # Cards com borda e contexto completo
guara crons runs hourly --watch --detail           # Cards ao vivo conforme as execuções terminam
guara crons runs hourly --watch --status failed    # Aguarda uma falha para reproduzir

Saída de exemplo (--detail):

┌─ 4f2ab91d-5c08-4e6c-9c8f-2b6d1c3a7e10 ──────  ✕ failed ─┐
│ Triggered by  schedule                                  │
│ Attempts      3                                         │
│ Started       2026-05-02T13:00:01.214Z                  │
│               Finished 2026-05-02T13:00:31.215Z         │
│ Duration      30001ms                                   │
│ Failure       timeout                                   │
│               The destination didn't respond within     │
│               the configured timeout.                   │
│ Error         upstream request timeout                  │
│ Payload       {                                         │
│                 "job": "rotate-uploads",                │
│                 "max_age_hours": 24                     │
│               }                                         │
└─────────────────────────────────────────────────────────┘

Motivos de falha

Toda execução falha carrega um failure_reason estruturado — a CLI imprime o código junto com uma explicação curta no modo --detail. Taxonomia completa:

Código	Explicação
`timeout`	O destino não respondeu dentro do timeout configurado.
`dns`	O hostname do destino não pôde ser resolvido (falha de DNS).
`connection`	O destino recusou a conexão ou estava inacessível.
`tls`	O destino apresentou um certificado TLS inválido ou não confiável.
`http_4xx`	O destino retornou 4xx (erro do cliente).
`http_5xx`	O destino retornou 5xx (erro do servidor).
`ssrf_blocked`	A URL do destino foi bloqueada pela proteção SSRF.
`blocked_hostname`	O hostname do destino está na lista de bloqueio da plataforma.
`blocked_ip`	O IP do destino está na lista de bloqueio da plataforma.
`destination_unresolvable`	A referência do destino não pôde ser resolvida no momento do disparo.
`credential`	A autenticação no destino falhou.
`protocol`	O destino falou um protocolo ou versão inesperada.
`unknown`	Falha não especificada (veja o campo `error` para detalhes).

De uma execução falha para o seu trace

Todo disparo de cron propaga um traceparent W3C, então uma execução falha tem um trace distribuído correspondente. Copie o trace ID do card da execução (ou do envelope JSON quando usar --json) e jogue no visualizador de traces:

# Encontre o último run falho de um worker
guara crons runs hourly --status failed --limit 1 --json \
  | jq -r '.data.items[0].id'

# Abra o trace correspondente (o trace_id sai na linha do run em --json)
guara services traces get <traceId>

O waterfall mostra se o serviço destino chegou a receber a requisição, o que cada span downstream fez e onde o tempo foi gasto de fato — quase sempre o caminho mais rápido entre “o cron falhou” e “essa query é o problema”.