Prometheus e instrumentação

Objetivos

• Expor endpoint de métricas em cada serviço do monorepo
• Configurar scrape do Prometheus para APIs e workers
• Instrumentar counters histograms e gauges relevantes

Pré-requisitos

• Aula logs-metricas-traces concluida.
• Prometheus rodando no ambiente local.
• Acesso ao endpoint de cada servico.

Conceito

Prometheus coleta metricas periodicamente via scrape HTTP. A qualidade do dashboard depende diretamente da instrumentacao no codigo.

Metricas devem responder perguntas operacionais: throughput, erro, latencia e backlog.

Estrutura de arquivos

• infra/monitoring/prometheus.yml
• services/customer-service/src/metrics
• services/order-service/app/metrics
• services/payment-service/internal/metrics
• services/analytics-service/src/metrics

Passo a passo com codigo

1. Exponha metrica no payment-service:

var processedEvents = promauto.NewCounterVec(
  prometheus.CounterOpts{
    Name: "payment_events_processed_total",
    Help: "Total de eventos processados pelo payment-service",
  },
  []string{"event_type", "status"},
)

2. Incremente no consumer:

processedEvents.WithLabelValues("order.created", "success").Inc()

3. Configure scrape no Prometheus:

scrape_configs:
  - job_name: payment-service
    static_configs:
      - targets: ["payment-service:8080"]
    metrics_path: /metrics

4. Crie metrica de lag:

consumerLag.WithLabelValues("order.created", "payment-consumers-v1").Set(float64(lag))

Como testar

1. Rode docker compose up -d.
2. Gere eventos de order.created.
3. Acesse http://localhost:9090 e consulte payment_events_processed_total.
4. Valide crescimento das series e labels esperadas.
5. Verifique cardinalidade para evitar explosao de series.

Dicas

• Evite labels com order_id e customer_id.
• Nomeie metricas com unidade (_seconds, _total).
• Defina buckets de histograma alinhados ao SLA.
• Versione mudancas de metricas no repositorio.

Erros comuns

• Criar métricas sem convenção de nome
• Usar labels dinâmicas demais
• Não proteger endpoint de métricas em produção
• Coletar métricas pesadas no caminho crítico

Resumo

Instrumentacao correta no Prometheus transforma comportamento dos servicos em sinais quantitativos acionaveis para operacao, capacidade e resposta a incidentes.