# Status, logs e health — trio de observabilidade

Cinco comandos cobrem a maioria dos cenários de diagnóstico no Runner. Esta página mostra o que cada um revela e como combiná-los em um workflow de troubleshooting.

# Pré-requisitos

• Runner instalado e apps registradas
• Para runner health: app com healthcheck configurado no .deploy.yml
• Para runner audit: eventos gerados (pelo menos um deploy executado)

# Os cinco comandos

# runner status

runner status <app>
runner status <app> -i <instancia>
runner status <app> --json

Mostra o estado consolidado da app: se o container existe e está rodando, a versão em produção, instância ativa e estatísticas do último deploy.

# Por slug projeto/sistema
runner status meu-projeto/front

# Por path absoluto
runner status /data/apps/meu-projeto/front

# Instância específica (para apps multi-environment)
runner status meu-projeto/front -i staging

# JSON para scripts e automação
runner status meu-projeto/front --json

O output JSON retorna um envelope com três seções:

• manifest — o .deploy.yml parsed
• config — valores resolvidos/merged
• runtime — estado live do container e instância

Use runner status como primeiro comando quando:

• Um endpoint retorna erro e você não sabe se o container está rodando
• O cron fez um deploy mas você quer confirmar a versão em produção
• A app está paused e você quer ver os contadores

# runner logs tail

runner logs tail <app>
runner logs tail <app> -l <linhas>

Tails os logs de deploy da app. Mostra output do processo de deploy em tempo real — build, pull de imagem, resultado do healthcheck.

# Últimas 50 linhas (default)
runner logs tail meu-projeto/front

# Mais linhas para histórico recente
runner logs tail meu-projeto/front -l 200

# JSON para processar programaticamente
runner logs tail meu-projeto/front --json

Use runner logs tail quando:

• O container iniciou mas o comportamento está errado
• Você quer ver o que aconteceu no deploy mais recente
• Quer monitorar um deploy em andamento

# runner logs history

runner logs history <app>
runner logs history <app> -l <entradas>

Mostra o histórico de deploys com timestamps, versões e resultado (sucesso/falha). Diferente do tail, que mostra o conteúdo do log, o history mostra o registro estruturado de cada deploy.

# Últimas 10 entradas (default)
runner logs history meu-projeto/front

# Mais entradas para investigar regressão
runner logs history meu-projeto/front -l 30

# JSON
runner logs history meu-projeto/front --json

Use runner logs history quando:

• Você precisa identificar quando uma regressão foi introduzida
• Quer comparar versões ao longo do tempo
• O problema ocorreu horas atrás e o tail não cobre

# runner health

runner health <app>
runner health <app> -i <instancia>

Executa a probe configurada no .deploy.yml uma única vez contra o container em produção. Retorna o resultado da probe — sucesso ou falha — com o tempo de resposta.

# Probe na instância production (default)
runner health meu-projeto/front

# Probe em instância específica
runner health meu-projeto/front -i staging

# JSON para automação
runner health meu-projeto/front --json

Use runner health quando:

• Você editou o .deploy.yml e quer validar o healthcheck antes do próximo deploy
• O deploy falhou com "healthcheck timeout" e você quer reproduzir o erro manualmente
• Quer confirmar que o endpoint de health está respondendo corretamente

# runner audit

runner audit
runner audit -p <projeto>
runner audit -e <tipo-de-evento>
runner audit -i <instancia>

Consulta o audit log estruturado em /opt/runner/logs/deploy-events.jsonl. Retorna eventos do runner: deploy_started, deploy_success, deploy_failure, rollback_started, rollback_success, canary_weight_changed, etc.

# Todos os eventos recentes
runner audit --json

# Filtrar por projeto
runner audit -p meu-projeto --json

# Filtrar por tipo de evento
runner audit -e deploy_failure --json

# Filtrar por instância
runner audit -i production --json

# Limitar resultados
runner audit --limit 20 --json

Use runner audit quando:

• Você precisa saber o que mudou e quando (audit trail)
• Um rollback automático ocorreu e você quer entender a causa
• Quer verificar se um deploy específico foi executado pelo cron

# runner debug last-error

runner debug last-error <app>

Imprime a última falha de deploy estruturada para a app: versão, timestamp e mensagem de erro completa. Útil quando o runner status mostra last_failed_commit mas não o motivo.

runner debug last-error meu-projeto/front
runner debug last-error meu-projeto/front --json

O runner também sugere runner debug last-error no output do fetch --deploy quando um deploy falha — procure por "Next steps:" no output.

# Workflow típico de troubleshooting

A sequência recomendada quando algo está errado:

# 1. O container ainda existe e está rodando?
runner status meu-app

# 2. A probe de health passa quando executada manualmente?
runner health meu-app

# 3. O que a app está dizendo nos logs?
runner logs tail meu-app -l 100

# 4. O que mudou recentemente no Runner?
runner audit -p meu-app --json

# 5. Qual foi o erro estruturado do último deploy?
runner debug last-error meu-app

Se o status mostrar paused, consulte pause e unpause antes de continuar.

Se o healthcheck falhou, consulte healthcheck para entender os modos e timing.

# Combinando com docker diretamente

Para diagnósticos mais profundos, combine os comandos do runner com docker:

# Ver logs do container (não do runner)
docker logs $(runner status meu-app --json | jq -r '.runtime.container_id') --tail 100

# Inspecionar health do Docker diretamente
docker inspect <container_id> --format='{{.State.Health.Status}}'

# Ver histórico de probes do Docker
docker inspect <container_id> --format='{{json .State.Health.Log}}' | jq '.[].Output'

# Links relacionados

• runner status — referência completa
• runner logs — referência completa (tail + history)
• runner health — referência completa
• runner audit — referência completa
• runner debug last-error — referência completa
• Healthcheck — modos, herança de Dockerfile, timing
• Healthcheck failed — recuperar após falha de probe (em breve)