Métricas e logs

Observabilidade costuma exigir uma pilha de software paralela ao cluster: agente de métrica em cada nó, série temporal central, agregador de logs, dashboard, alertador, tracer. Cinco componentes, cada um com sua configuração, sua atualização, sua conta.

O HeroCtl resolve isso por dentro. Métricas, logs, alertas e tracing já vêm embutidos no plano de controle. Você só pluga ferramenta externa quando o time tem motivo concreto para isso.

Métricas

O endpoint padrão

Cada nó servidor expõe métricas em formato Prometheus em /v1/metrics:

curl -H "X-Heroctl-Token: $TOKEN" https://manage.exemplo.com/v1/metrics

Saída típica (recortada):

# HELP heroctl_node_cpu_usage_percent CPU em uso por nó
# TYPE heroctl_node_cpu_usage_percent gauge
heroctl_node_cpu_usage_percent{node="server-1"} 23.4
heroctl_node_cpu_usage_percent{node="server-2"} 18.1

# HELP heroctl_alloc_memory_bytes Memória usada por alocação
# TYPE heroctl_alloc_memory_bytes gauge
heroctl_alloc_memory_bytes{job="api",alloc="abc123"} 285212672

O que vem pronto

Em um cluster recém-instalado, isso já alimenta um painel completo sem nenhuma configuração extra.

Métricas customizadas da aplicação

Sua aplicação expõe /metrics em qualquer porta, em formato Prometheus. Declare no spec:

job: api-pagamentos
metrics:
  enabled: true
  path: /metrics
  port: 9090
  interval: 15s

O cluster faz o scrape, agrega, e disponibiliza no mesmo endpoint /v1/metrics. As métricas saem rotuladas com job, alloc, node, então a busca é direta:

rate(http_requests_total{job="api-pagamentos",status=~"5.."}[5m])

Cliente Prometheus existe oficialmente para Go, Python, Java, Node.js, Ruby, .NET, Rust e PHP. Em qualquer uma dessas linguagens, instrumentar uma aplicação leva quinze minutos.

Painel embutido

O painel admin (porta 8443) traz uma seção de gráficos pronta:

• Visão de cluster: CPU, RAM, rede agregadas
• Visão de job: réplicas, restarts, latência do roteador
• Visão de alocação: stream de logs, métricas individuais
• Visão de host: detalhe de cada nó, alocações nele

Para a maioria dos times, esse painel substitui um Grafana montado por fora. Quando você precisa de dashboards muito customizados ou de correlação com fontes externas, vale ligar um Grafana ao endpoint /v1/metrics como datasource Prometheus comum.

Logs

Modelo de coleta

Cada alocação tem stdout e stderr capturados pelo agente local, comprimidos, e enviados ao escritor central de logs do cluster. Não há agente de logs separado para instalar, configurar ou atualizar.

Tail em tempo real

# stream do job inteiro (todas as alocações)
heroctl logs -f --job api-pagamentos

# uma alocação específica
heroctl logs -f --alloc abc123

# só stderr
heroctl logs -f --job api-pagamentos --stream stderr

Filtragem

# entre dois timestamps
heroctl logs --job api-pagamentos \
  --since "2026-04-25 10:00" \
  --until "2026-04-25 11:00"

# busca textual
heroctl logs --job api-pagamentos --since 1h | grep "panic"

# saída estruturada para processar com jq
heroctl logs --job api-pagamentos --since 1h --format json

Retenção

Default: 30 dias por alocação ativa, 7 dias depois que a alocação termina. Configurável no spec do cluster:

logs:
  retention:
    active_days: 30
    terminated_days: 7
  storage:
    type: local
    path: /var/lib/heroctl/logs
    max_size_gb: 100

Para retenção mais longa, exporte para storage externo (próxima seção).

Export para fora

Quando você precisa de retenção em anos, ou de correlação com logs de sistemas que não rodam no cluster, há saídas prontas:

logs:
  export:
    - type: syslog
      destination: logs.empresa.com.br:514
      protocol: tcp
      tls: true

    - type: loki
      url: https://loki.empresa.com.br
      tenant: heroctl-prod

    - type: cloudwatch
      region: us-east-1
      log_group: /heroctl/prod
      credentials: ${secret.aws_logs}

    - type: elasticsearch
      url: https://elastic.empresa.com.br
      index: heroctl-%Y.%m.%d
      credentials: ${secret.es_creds}

Vários destinos podem rodar ao mesmo tempo. O cluster mantém a cópia local pelo período de retenção e replica para os destinos configurados.

Alertas

Um alerta é uma expressão sobre métricas que dispara um webhook quando verdadeira por tempo configurado:

alerts:
  - name: api-erro-alto
    expr: |
      rate(http_requests_total{job="api-pagamentos",status=~"5.."}[5m])
        / rate(http_requests_total{job="api-pagamentos"}[5m]) > 0.05
    for: 5m
    severity: critical
    annotations:
      summary: "Taxa de erro acima de 5% em api-pagamentos"
      runbook: https://wiki.empresa.com.br/runbook/api-pagamentos

    notify:
      - type: slack
        webhook: ${secret.slack_oncall}
      - type: pagerduty
        routing_key: ${secret.pagerduty_critical}

  - name: certificado-expirando
    expr: heroctl_ingress_cert_expiry_days < 14
    for: 1h
    severity: warning
    notify:
      - type: discord
        webhook: ${secret.discord_ops}

Canais suportados de fábrica: Slack, Discord, PagerDuty, Opsgenie, webhook genérico. Para quem quer integração custom (Telegram, e-mail, SMS), o webhook genérico cobre tudo.

Atenção: Comece com poucos alertas críticos. Vinte alertas barulhentos viram zero alertas — o time aprende a ignorar. Cinco alertas que sempre indicam problema real são úteis.

Tracing distribuído

Tracing está disponível como opt-in no spec do job:

job: api-pagamentos
tracing:
  enabled: true
  protocol: otlp
  sample_rate: 0.1   # 10% das requisições

A aplicação instrumentada com OpenTelemetry envia para o coletor embutido. O painel mostra traces correlacionados com logs e métricas da mesma alocação.

Para visualização avançada (timeline de spans, comparação entre traces, análise de cauda), exporte para Jaeger, Tempo ou um SaaS como Honeycomb:

tracing:
  export:
    - type: otlp
      endpoint: tempo.empresa.com.br:4317
      tls: true

Comparação de custo

Para um cluster típico — 4 nós, 30 jobs, 100 milhões de requests/mês — um stack de observabilidade SaaS comercial fica entre R$ 1.000 e R$ 2.000 por mês. Um stack auto-hospedado equivalente (Prometheus + Loki + Grafana + Alertmanager + Tempo) tem custo direto baixo, mas exige meio dia de operação por semana.

Recomendação prática: comece pelo stack interno. Quando a operação cresce além do que ele atende — geralmente além de 50 jobs ou retenção de log acima de 6 meses — exporte para Loki e Grafana auto-hospedados. SaaS comercial só vale quando o tempo do time é mais caro que a fatura.

Próximos passos

• Configurar alertas conectados ao Slack ou PagerDuty antes do primeiro deploy crítico.
• Revisar RBAC para limitar quem vê quais logs (logs podem conter dado sensível).