📈 Observabilidade na prática

Métricas com Prometheus, mais logs, traces e error tracking — usando o stack real deste ambiente.

1. O que é observabilidade

Observabilidade é a capacidade de entender o que acontece dentro de um sistema olhando só o que ele emite para fora. Não é só "está no ar?" — é conseguir responder perguntas que você não previu: por que ficou lento às 14h? qual rota dá erro? qual fila encheu?

Monitoramento responde "está quebrado?". Observabilidade responde "por quê?".

2. Os pilares

  • métricas números agregados ao longo do tempo (req/s, latência, CPU, tamanho de fila). Baratas, ótimas para gráficos e alertas. É aqui que entra o Prometheus.
  • logs eventos textuais com contexto ("pedido 123 falhou: timeout"). Detalhados, para investigar um caso.
  • traces o caminho de uma requisição atravessando vários serviços, com o tempo em cada passo (OpenTelemetry, Jaeger).
  • error tracking agrupa exceções por "tipo de problema", com stack trace e frequência. Aqui usamos o GlitchTip (compatível com Sentry).

Os pilares se complementam: a métrica mostra que a taxa de erro subiu, o error tracking mostra qual exceção, o trace mostra onde no fluxo, o log dá o detalhe.

3. Métricas & Prometheus

O Prometheus é um banco de séries temporais com modelo pull: em vez de a aplicação empurrar, o Prometheus raspa (scrape) um endpoint HTTP /metrics de cada alvo, em intervalos regulares. O formato é texto: 

# HELP http_requests_total Total de requisições HTTP
# TYPE http_requests_total counter
http_requests_total{method="GET",status="200"} 1027
http_requests_total{method="GET",status="500"} 3

Cada linha é uma série temporal: nome + labels + valor. Nome+labels identificam a série; a cada scrape guarda-se (timestamp, valor).

Labels são poderosos mas perigosos: cada combinação vira uma série. Nunca use alta cardinalidade (UUID, ID de usuário) como label.

4. Tipos de métrica

  • counter só sobe (zera ao reiniciar). Ex.: total de mensagens. Olha-se a taxa com rate().
  • gauge sobe e desce. Ex.: backlog, conexões, memória.
  • histogram distribui em faixas (buckets). Permite percentis (p95/p99) com histogram_quantile().
  • summary como o histogram, mas calcula quantis no cliente — menos flexível para agregar.

5. O que medir

Meça o que indica saúde. Dois roteiros:

  • RED para serviços: Rate, Errors, Duration.
  • USE para recursos: Utilization, Saturation, Errors.

Os "quatro sinais de ouro" do Google SRE: latência, tráfego, erros e saturação. Comece por esses.

6. PromQL na prática

Conceitos: instant vector (valor agora — pulsar_rate_in) e range vector (intervalo — pulsar_rate_in[5m], usado por rate()).

⚡ PromQL ao vivo — consulta o Prometheus deste ambiente
clique em Rodar para consultar
Tente: sum(pulsar_topics_count) · up{job="pulsar"} · sum(rate(pulsar_in_messages_total[5m])) by (namespace)

Consultas do dia a dia:

# taxa de requisições por segundo (counter -> rate)
rate(http_requests_total[5m])

# proporção de ERRO (0..1)
sum(rate(http_requests_total{status=~"5.."}[5m]))
  / sum(rate(http_requests_total[5m]))

# p95 de latência (histogram)
histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))

# --- com as métricas reais do Pulsar (nosso stack) ---
sum(pulsar_topics_count)
sum(rate(pulsar_in_messages_total[5m])) by (namespace)

rate() sempre sobre counters, nunca sobre gauges. Para gauges, agregue direto (sum, avg, max).

7. Expor & coletar

A aplicação expõe um /metrics; o Prometheus declara um scrape_config:

scrape_configs:
  - job_name: pulsar
    metrics_path: /metrics/      # a barra final importa: /metrics responde 301
    static_configs:
      - targets: ['pulsar-broker.pulsar.svc.cluster.local:8080']

No nosso ambiente, o Prometheus já vem configurado para raspar o broker Pulsar.

8. Alertas

Uma alerting rule é uma consulta PromQL que, verdadeira por um tempo, dispara um alerta (Alertmanager → e-mail/Slack):

- alert: TaxaDeErroAlta
  expr: |
    sum(rate(http_requests_total{status=~"5.."}[5m]))
      / sum(rate(http_requests_total[5m])) > 0.05
  for: 10m
  annotations: { summary: "Mais de 5% de erro por 10 minutos" }

Alerte sobre sintomas que o usuário sente (erro, lentidão), não sobre causas (CPU alta).

9. Error tracking (GlitchTip)

Métricas dizem "a taxa de erro subiu"; o error tracking diz qual erro. O GlitchTip é open-source e compatível com o Sentry: aponta-se o SDK do Sentry para a DSN do GlitchTip e pronto. No nosso stack, o test-mensageria reporta erros assim: 

# config/packages/sentry.yaml (Symfony)
sentry:
    dsn: '%env(SENTRY_DSN)%'   # aponta para o GlitchTip
    messenger: { enabled: true }

GlitchTip deste ambiente: https://glitchtip-pre-stage.thiagocavalcante.dev.br

10. O stack deste ambiente

Tudo o que este tutorial descreve está rodando aqui, conectado:

Próximos passos: adicionar traces (OpenTelemetry) e um Grafana para dashboards sobre o Prometheus.