Métricas e Prometheus

Métricas são agregações numéricas do comportamento do sistema ao longo do tempo. Onde logs capturam eventos individuais e traces capturam jornadas de requisições, métricas capturam padrões agregados — a taxa de requisições por segundo, o percentil 99 de latência, o número de conexões abertas, o uso de CPU ao longo do tempo. Métricas são baratas de armazenar (séries temporais comprimidas), excelentes para alertas e dashboards, e rápidas de consultar em janelas de tempo. O Prometheus se tornou o padrão de fato para métricas em sistemas cloud-native, e seu modelo de dados e linguagem de query (PromQL) são fundamentos que todo engenheiro sênior deve dominar.

Os quatro tipos de métrica do Prometheus

Counter

Um counter só aumenta — nunca diminui (exceto ao resetar para zero quando o processo reinicia). Representa uma contagem cumulativa: total de requisições processadas, total de erros, total de bytes enviados. Sempre use rate() ou increase() sobre counters para obter taxas significativas — o valor absoluto de um counter isolado raramente é útil.

# Declaração — sufixo _total é convencional para counters
http_requests_total{method="POST", endpoint="/api/orders", status="200"} 1847

# PromQL — taxa de requisições nos últimos 5 minutos
rate(http_requests_total[5m])

# Taxa de erros (status 5xx)
rate(http_requests_total{status=~"5.."}[5m])
  /
rate(http_requests_total[5m])

Gauge

Um gauge pode aumentar ou diminuir — representa um valor instantâneo. Conexões abertas, uso de memória, tamanho de fila, temperatura. Use diretamente sem rate() — o valor atual já é o dado relevante.

# Exemplos de gauge
db_connections_open{pool="primary"}     42
queue_depth{queue="orders"}             156
memory_used_bytes{type="heap"}          1073741824
go_goroutines                           847

# PromQL — máximo de conexões abertas nas últimas 24h
max_over_time(db_connections_open[24h])

# Alerta: fila crescendo
db_connections_open > 80   # threshold simples

Histogram

Um histogram mede a distribuição de valores em buckets pré-definidos. É o tipo mais importante para latência — permite calcular percentis (P50, P95, P99) com PromQL. Gera três séries: _bucket (contagem por bucket), _sum (soma dos valores), _count (total de observações).

# Histogram com buckets para latência HTTP (em segundos)
http_request_duration_seconds_bucket{le="0.005"}  1200
http_request_duration_seconds_bucket{le="0.01"}   2100
http_request_duration_seconds_bucket{le="0.025"}  3800
http_request_duration_seconds_bucket{le="0.05"}   4200
http_request_duration_seconds_bucket{le="0.1"}    4350
http_request_duration_seconds_bucket{le="0.25"}   4390
http_request_duration_seconds_bucket{le="0.5"}    4398
http_request_duration_seconds_bucket{le="1"}      4399
http_request_duration_seconds_bucket{le="+Inf"}   4400
http_request_duration_seconds_sum    87.3
http_request_duration_seconds_count  4400

# PromQL — P99 de latência
histogram_quantile(0.99,
  rate(http_request_duration_seconds_bucket[5m])
)

# P99 por endpoint
histogram_quantile(0.99,
  sum by (endpoint, le) (
    rate(http_request_duration_seconds_bucket[5m])
  )
)

Summary

Summary também mede distribuições, mas calcula quantis no lado do cliente (na aplicação), não no servidor (Prometheus). Isso torna summaries não-agregáveis — você não pode combinar percentis de múltiplas instâncias. Use histograms na maioria dos casos; summary só faz sentido quando você precisa de percentis exatos e tem apenas uma instância.

RED Method — métricas para serviços

RED (Rate, Errors, Duration) é o framework de Tom Wilkie (Grafana Labs) para instrumentar serviços:

Rate: requisições por segundo. O sinal de volume — quantas coisas estão acontecendo. rate(http_requests_total[5m])

Errors: taxa de erros — proporção de requisições que falharam. O sinal de qualidade. rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

Duration: distribuição de latência, especialmente a cauda (P95, P99). O sinal de velocidade — quão rápido para o pior caso. histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

Esses três juntos cobrem a maioria das perguntas de "está funcionando bem?" para qualquer serviço orientado a requisições.

USE Method — métricas para recursos

USE (Utilization, Saturation, Errors) de Brendan Gregg complementa o RED para recursos do sistema:

Utilization: quanto do recurso está sendo usado (0-100%). CPU a 80%, disco a 70%, pool de conexões a 60%.

Saturation: quanto trabalho está esperando para ser atendido. Fila de I/O, tamanho da run queue de CPU, requisições esperando conexão no pool. Saturação é o sinal mais precoce de problema — você pode estar com CPU a 60% mas com run queue crescendo.

Errors: taxa de erros do recurso. Erros de I/O de disco, pacotes descartados pela NIC, conexões rejeitadas pelo pool.

Cardinality explosions — o problema mais comum

Cada combinação única de labels cria uma série temporal separada no Prometheus. Com poucos labels de baixa cardinalidade, isso é manejável. Com labels de alta cardinalidade, o Prometheus fica sem memória.

# Cardinalidade controlada — OK
http_requests_total{
  service="order-service",    # ~10 serviços
  endpoint="/api/orders",     # ~50 endpoints
  method="POST",              # ~5 métodos
  status="200"                # ~10 status codes
}
# Total: 10 × 50 × 5 × 10 = 25.000 séries — manejável

# Cardinalidade explosiva — NUNCA faça
http_requests_total{
  user_id="usr-12345678",     # 10M usuários únicos
  trace_id="4bf92f3577b...",  # 1 por requisição
  url="/api/orders?filter=..." # query params únicos
}
# Total: potencialmente bilhões de séries — Prometheus morre

Sinais de cardinalidade explosion: uso de memória do Prometheus crescendo sem parar, scrape duration aumentando, queries ficando lentas. Diagnóstico: prometheus_tsdb_head_series mostra o número de séries ativas — se estiver acima de 10M, investigar quais labels têm alta cardinalidade.

# PromQL para identificar métricas com mais séries
topk(10, count by (__name__)({__name__=~".+"}))

Exemplars — ligando métricas a traces

Exemplars são o elo entre métricas e traces. Um exemplar é um ponto de dado específico vinculado a uma métrica de histogram — normalmente o trace_id da requisição que caiu naquele bucket. No Grafana, você pode clicar em um pico de latência no dashboard e ir diretamente para um trace representativo daquele pico.

# Formato de exemplar no Prometheus (OpenMetrics)
http_request_duration_seconds_bucket{le="0.5"} 4398 # {trace_id="4bf92f357..."} 0.42 1715299200

# Instrumentação com exemplar (Go + OTel)
histogram.Record(ctx, latency,
    metric.WithAttributeSet(attrs),
)
// O OTel SDK extrai automaticamente o trace_id do contexto
// e o adiciona como exemplar ao histogram

Comparativo entre linguagens — instrumentação com Prometheus

// C# — métricas RED com prometheus-net e exemplars OTel

using Prometheus;

// Declaração de métricas (singleton — declare uma vez)
public static class Metrics {
    public static readonly Counter RequestsTotal = Prometheus.Metrics
        .CreateCounter(
            "http_requests_total",
            "Total de requisições HTTP",
            new CounterConfiguration {
                LabelNames = ["method", "endpoint", "status"],
            }
        );

    public static readonly Histogram RequestDuration = Prometheus.Metrics
        .CreateHistogram(
            "http_request_duration_seconds",
            "Duração das requisições HTTP",
            new HistogramConfiguration {
                LabelNames = ["method", "endpoint"],
                Buckets    = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
            }
        );

    public static readonly Gauge QueueDepth = Prometheus.Metrics
        .CreateGauge(
            "orders_queue_depth",
            "Profundidade da fila de pedidos"
        );
}

// Middleware que instrumenta automaticamente todos os endpoints
app.UseHttpMetrics(options => {
    options.AddCustomLabel("endpoint",
        ctx => ctx.GetEndpoint()?.DisplayName ?? ctx.Request.Path);
});

// Instrumentação manual em handlers de negócio
public async Task<Order> PlaceOrderAsync(PlaceOrderCommand cmd) {
    using var timer = Metrics.RequestDuration
        .WithLabels("POST", "/api/orders")
        .NewTimer();  // para automaticamente ao sair do using

    try {
        var order = await _repo.CreateAsync(cmd);
        Metrics.RequestsTotal.WithLabels("POST", "/api/orders", "201").Inc();
        return order;
    } catch {
        Metrics.RequestsTotal.WithLabels("POST", "/api/orders", "500").Inc();
        throw;
    }
}

// Expõe /metrics para scraping do Prometheus
app.MapMetrics();  // rota padrão: /metrics

# Python — métricas RED com prometheus-client

from prometheus_client import (
    Counter, Histogram, Gauge,
    CollectorRegistry, make_asgi_app,
    CONTENT_TYPE_LATEST, generate_latest,
)
from fastapi import FastAPI, Request
from starlette.middleware.base import BaseHTTPMiddleware
import time

# Declaração de métricas
REQUEST_COUNT = Counter(
    "http_requests_total",
    "Total de requisições HTTP",
    ["method", "endpoint", "status"],
)

REQUEST_DURATION = Histogram(
    "http_request_duration_seconds",
    "Duração das requisições HTTP",
    ["method", "endpoint"],
    buckets=[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
)

QUEUE_DEPTH = Gauge(
    "orders_queue_depth",
    "Profundidade da fila de pedidos",
)

# Middleware de instrumentação automática
class PrometheusMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # Normaliza o path para evitar alta cardinalidade
        # /api/orders/123 → /api/orders/{id}
        path = self._normalize_path(request.url.path)

        start = time.perf_counter()
        response = await call_next(request)
        elapsed = time.perf_counter() - start

        REQUEST_COUNT.labels(
            method=request.method,
            endpoint=path,
            status=str(response.status_code),
        ).inc()

        REQUEST_DURATION.labels(
            method=request.method,
            endpoint=path,
        ).observe(elapsed)

        return response

    def _normalize_path(self, path: str) -> str:
        import re
        # Substitui IDs numéricos e UUIDs por placeholder
        path = re.sub(r"/[0-9a-f]{8}-[0-9a-f-]{27}", "/{id}", path)
        path = re.sub(r"/\d+", "/{id}", path)
        return path

app = FastAPI()
app.add_middleware(PrometheusMiddleware)

# Endpoint /metrics
@app.get("/metrics")
async def metrics():
    from fastapi.responses import PlainTextResponse
    return PlainTextResponse(
        generate_latest(),
        media_type=CONTENT_TYPE_LATEST,
    )

# Instrumentação de negócio
async def place_order(cmd: PlaceOrderCommand) -> Order:
    with REQUEST_DURATION.labels("POST", "/api/orders").time():
        order = await order_service.place(cmd)
    QUEUE_DEPTH.set(await queue.depth())
    return order

// Go — métricas RED com prometheus/client_golang

package metrics

import (
    "net/http"
    "regexp"
    "strconv"
    "time"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

var (
    RequestsTotal = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total de requisições HTTP",
        },
        []string{"method", "endpoint", "status"},
    )

    RequestDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Help:    "Duração das requisições HTTP",
            Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5},
        },
        []string{"method", "endpoint"},
    )

    QueueDepth = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "orders_queue_depth",
        Help: "Profundidade da fila de pedidos",
    })
)

// pathNormalizer substitui IDs dinâmicos por placeholder
var (
    uuidRe    = regexp.MustCompile(`/[0-9a-f]{8}-[0-9a-f-]{27}`)
    numericRe = regexp.MustCompile(`/\d+`)
)

func normalizePath(p string) string {
    p = uuidRe.ReplaceAllString(p, "/{id}")
    p = numericRe.ReplaceAllString(p, "/{id}")
    return p
}

// Middleware de instrumentação
func InstrumentHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        endpoint := normalizePath(r.URL.Path)
        rw := &responseWriter{ResponseWriter: w, status: 200}

        start := time.Now()
        next.ServeHTTP(rw, r)
        elapsed := time.Since(start).Seconds()

        status := strconv.Itoa(rw.status)
        RequestsTotal.WithLabelValues(r.Method, endpoint, status).Inc()
        RequestDuration.WithLabelValues(r.Method, endpoint).Observe(elapsed)
    })
}

// Handler /metrics com suporte a exemplars (OpenMetrics format)
func MetricsHandler() http.Handler {
    return promhttp.HandlerFor(
        prometheus.DefaultGatherer,
        promhttp.HandlerOpts{
            EnableOpenMetrics: true,  // habilita exemplars no formato OpenMetrics
        },
    )
}

type responseWriter struct {
    http.ResponseWriter
    status int
}

func (rw *responseWriter) WriteHeader(code int) {
    rw.status = code
    rw.ResponseWriter.WriteHeader(code)
}

Como praticar

1. Instrumente um serviço HTTP simples com as três métricas RED usando Prometheus. Exponha /metrics, configure um Prometheus local para fazer scrape, e crie um Grafana dashboard com os três painéis: rate (req/s), error rate (%), e heatmap de latência com P50/P95/P99. Use k6 para gerar carga e observe as métricas em tempo real.
   Critério: dashboard mostra as 3 métricas com dados reais; ao introduzir latência artificial no handler (sleep aleatório), o heatmap de latência muda visivelmente; ao introduzir erros (5xx em 10% dos requests), o error rate reflete corretamente.
2. Demonstre cardinalidade explosion: adicione user_id como label em uma métrica, gere 10.000 usuários únicos e monitore o crescimento de prometheus_tsdb_head_series. Compare o uso de memória antes e depois. Corrija removendo o label e movendo user_id para atributo de span OTel.
   Critério: com label user_id: prometheus_tsdb_head_series cresce proporcionalmente ao número de usuários únicos; sem label: métrica permanece constante; diferença de uso de memória documentada com números concretos.
3. Configure exemplars: instrumente um endpoint com OTel + Prometheus, habilite OpenMetrics no endpoint /metrics com EnableOpenMetrics: true, e configure o Grafana para mostrar exemplars no painel de latência. Em um pico de P99, clique no exemplar e navegue para o trace correspondente no Jaeger/Tempo.
   Critério: exemplars visíveis como pontos no gráfico de latência; clique em um ponto de latência alta navega diretamente para o trace; o trace mostra o span que causou a latência alta.
4. Implemente o USE method para um pool de conexões de banco: Utilization (connections_open / connections_max), Saturation (connections_waiting), Errors (connections_failed_total). Crie um alerta Alertmanager quando Saturation > 0 por mais de 30 segundos consecutivos.
   Critério: as 3 métricas são visíveis no Grafana com valores reais; ao saturar o pool (mais goroutines que conexões disponíveis), Saturation > 0 e o alerta dispara em até 35 segundos; alerta resolve automaticamente quando o pool volta à normalidade.
5. Escreva e valide queries PromQL: (a) taxa de erros 5xx por endpoint nas últimas 1h com topk(5, ...), (b) P99 de latência por serviço comparando com 1h atrás (offset 1h) para detectar degradação, (c) serviços com disponibilidade abaixo de 99.9% nos últimos 7 dias, (d) SLO burn rate de 1h e 6h para um SLO de 99.9%.
   Critério: as 4 queries retornam resultados corretos com dados reais; a query de burn rate identifica corretamente quando o budget está sendo consumido acima do esperado; cada query documentada com explicação da lógica PromQL.