Skip to content

📊 Telemetria e Observabilidade

Visão Geral

O Sloth Runner fornece recursos abrangentes de telemetria e observabilidade através de integração nativa com Prometheus e um dashboard estilo Grafana diretamente no terminal. Monitore sua frota de agentes, rastreie métricas de execução de tarefas, analise performance e obtenha insights profundos sobre sua automação de infraestrutura.

Observabilidade Enterprise

Servidor de métricas Prometheus embutido com auto-descoberta, dashboards em tempo real e configuração zero.

Recursos Principais

🎯 Integração Prometheus

  • Exportador Nativo: Servidor HTTP embutido expondo métricas compatíveis com Prometheus
  • Auto-Descoberta: Endpoint de métricas automaticamente configurado no startup do agente
  • Formato Padrão: Compatível com Prometheus, Grafana e todas as ferramentas de observabilidade
  • Configuração Zero: Telemetria habilitada por padrão com valores sensatos

📊 Dashboard no Terminal

  • Visualização Rica: Dashboard bonito no terminal com tabelas, gráficos e barras de progresso
  • Atualizações em Tempo Real: Modo watch com intervalos de refresh configuráveis
  • Métricas Abrangentes: Recursos do sistema, performance de tarefas, estatísticas gRPC e rastreamento de erros
  • Insights Coloridos: Indicadores visuais para performance e status de saúde

📈 Categorias de Métricas

Métricas de Tarefas

  • Total de tarefas executadas (por status: success, failed, skipped)
  • Tarefas executando atualmente
  • Histogramas de duração de tarefas (latências P50, P99)
  • Rastreamento de performance por tarefa e por grupo

Métricas do Sistema

  • Uptime do agente
  • Alocação de memória
  • Contador de goroutines
  • Versão do agente e informações de build

Métricas gRPC

  • Contagem de requisições por método
  • Histogramas de duração de requisições
  • Taxas de sucesso/erro

Rastreamento de Erros

  • Contagem de erros por tipo
  • Rastreamento de tarefas falhadas
  • Monitoramento de erros do sistema

Início Rápido

Habilitar Telemetria no Agente

Telemetria está habilitada por padrão. Simplesmente inicie seu agente:

./sloth-runner agent start --name meu-agente --master localhost:50053

Para configurar explicitamente a telemetria:

# Habilitar telemetria com porta customizada
./sloth-runner agent start \
  --name meu-agente \
  --master localhost:50053 \
  --telemetry \
  --metrics-port 9090

Para desabilitar telemetria:

./sloth-runner agent start \
  --name meu-agente \
  --master localhost:50053 \
  --telemetry=false

Acessar Métricas

Obter Endpoint Prometheus

./sloth-runner agent metrics prom meu-agente

Saída: 

✅ Metrics Endpoint:
  URL: http://192.168.1.100:9090/metrics

📝 Usage:
  # Visualizar métricas no navegador:
  open http://192.168.1.100:9090/metrics

  # Buscar métricas via curl:
  curl http://192.168.1.100:9090/metrics

Visualizar Snapshot

./sloth-runner agent metrics prom meu-agente --snapshot

Visualizar Dashboard

Visualização Única

./sloth-runner agent metrics grafana meu-agente

Modo Watch (Auto-Refresh)

# Refresh a cada 5 segundos (padrão)
./sloth-runner agent metrics grafana meu-agente --watch

# Intervalo de refresh customizado (2 segundos)
./sloth-runner agent metrics grafana meu-agente --watch --interval 2

Casos de Uso

Desenvolvimento

Monitore suas tarefas durante o desenvolvimento:

# Terminal 1: Watch dashboard
./sloth-runner agent metrics grafana dev-agent --watch --interval 1

# Terminal 2: Executar tarefas
./sloth-runner run -f deploy.sloth --values dev.yaml

Monitoramento em Produção

Integre com Prometheus e Grafana:

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'sloth-runner-producao'
    static_configs:
      - targets:
          - 'agent1:9090'
          - 'agent2:9090'
          - 'agent3:9090'
        labels:
          environment: production

Análise de Performance

Identifique tarefas lentas e gargalos:

# Visualizar métricas detalhadas de performance
./sloth-runner agent metrics grafana prod-agent

# Verificar latências P99 na seção Task Performance
# Tarefas com indicador 🔴 Slow precisam de otimização

Próximos Passos

Plataformas Suportadas

  • ✅ Linux (amd64, arm64)
  • ✅ macOS (Intel, Apple Silicon)
  • ✅ Windows (via WSL2)
  • ✅ Containers (Docker, Incus/LXC)
  • ✅ Kubernetes (via DaemonSet)

Impacto na Performance

A telemetria tem overhead mínimo de performance:

  • Memória: ~10-20MB adicional
  • CPU: <1% sob carga normal
  • Rede: Métricas servidas apenas sob demanda (modelo pull)
  • Armazenamento: Métricas armazenadas em memória, sem persistência

Considerações de Segurança

Exposição de Rede

O endpoint de métricas é exposto em todas as interfaces de rede por padrão. Em produção:

  • Use regras de firewall para restringir acesso
  • Considere bind apenas em localhost e use reverse proxy
  • Habilite autenticação via reverse proxy (Prometheus não suporta auth nativamente)

Próximas Leituras