Arquitetura de Sistemas · Insper · Capítulo 9

Hands-on 8 — Observabilidade

OpenTelemetry, um dashboard RED (taxa, erros e duração, rate, errors, duration), um trace atravessando o Kafka e um objetivo de nível de serviço (SLO, service level objective) que aciona na hora certa

A história até aqui

antes · lab 7o e-mail saiu da requisição: outbox, Kafka
→
capítulo 9 · lab 8OpenTelemetry, dashboard RED, SLO e alerta
→
depois · lab 9capítulo 10: um provedor lento, resiliência

A assincronia esconde falhas: o POST /orders responde em 1,8 ms (lab 7), mas um pedido cujo e-mail nunca chega não produz 5xx. Para onde foi esse pedido?

  • O k6 mede de fora; este lab adiciona a visão de dentro.

"O checkout está lento"

A venda relâmpago está no ar e o suporte está lotado. É com todos os fãs ou com alguns? Qual dos sete
serviços? O banco, o pool, o Kafka, o provedor de e-mail?

  • O k6 mede de fora; precisamos da visão de dentro.
  • Métricas: que algo está errado e quanto.
  • Traces: onde o tempo foi gasto, requisição por requisição.
  • Logs: por quê, quando você já sabe onde olhar.

Arquitetura

todo serviço Java + o agente
gateway
catalog ×3
order · notification
OTLP :4318 →
otel-lgtm (um contêiner)
OpenTelemetry Collector
Prometheusmétricas
Tempotraces
Lokilogs
→
Grafana :3000exemplar → trace → logs; regras de alerta
  • O agente envia OTLP (o OpenTelemetry Protocol); o Grafana liga os três sinais.

Backend de desenvolvimento em uma imagem; produção o troca por sistemas separados — os serviços continuam falando OTLP.

Passo 1 · O agente: um jar, nenhum código

sh scripts/get-otel-agent.sh      # downloads infra/otel/opentelemetry-javaagent.jar (v2.32.0)
x-otel: &otel
  JAVA_TOOL_OPTIONS: -javaagent:/otel/opentelemetry-javaagent.jar
  OTEL_JAVAAGENT_ENABLED: ${OTEL_ON:-true}
  OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-lgtm:4318

Cada serviço Java monta ./infra/otel:/otel:ro e adiciona <<: *otel e o seu OTEL_SERVICE_NAME. As imagens não mudam.

O que o agente entrega

  • Spans para servidor/cliente HTTP, JDBC, Kafka, Redis, @Scheduled.
  • Métricas com nomes padronizados: http_server_request_duration_seconds_bucket{service_name, http_route, http_response_status_code}.
  • Logs via OTLP, cada um com trace_id e span_id.
  • http_route é o template (/catalog/events/{id}), nunca a URL crua → cardinalidade limitada.

O salto que o agente não enxerga

Um pedido produz dois traces sem relação: POST /orders e, depois, relay → Kafka → notification.

orderthread HTTP
INSERT →
linha do outbox+ traceparent (migração V2)
SELECT →
relaythread do scheduler: makeCurrent()
→
Kafka → notificationo mesmo trace id
  • O outbox é uma linha do banco lida por outra thread: o contexto da requisição precisa viajar nela.
  • Resultado: um trace — 9 ms de requisição, o relay 22 ms depois, 67 ms no notification.

Passo 2 · RED e USE

Método Para Sinais
RED serviços movidos a requisições Rate, Errors, Duration
USE recursos Utilization, Saturation, Errors
  • O RED diz que os usuários estão sofrendo; o USE diz qual recurso acabou.
  • Dashboard como código: infra/grafana/dashboards/boxoffice-red.json + um arquivo de provedor.

Quatro formas de PromQL

sum by (service_name) (rate(…_count[$__rate_interval]))                     # Rate
rate(…_count{http_response_status_code=~"5.."}) / rate(…_count)             # Errors (ratio)
histogram_quantile(0.95, sum by (service_name, le) (rate(…_bucket[…])))      # Duration
db_client_connections_pending_requests                                      # Saturation

Nunca tire a média de percentis. Some as taxas dos buckets e depois calcule o quantil.

Passo 3 · Da promessa aos números

Termo catalog
SLI (indicador de nível de serviço) fração das requisições (sem /actuator) não respondidas com 5xx
SLO 99,5% em 28 dias
Orçamento de erros 0,5% → ≈ 202 min de queda total a cada 28 dias
Taxa de queima fração de erros / 0,005 (1 = exatamente no orçamento)

Múltiplas janelas, múltiplas taxas de queima

Severidade Taxa Longa Curta Orçamento gasto
page 14,4 1 h 5 min ≈ 2,1%
page / ticket 6 6 h 30 min ≈ 5,4%
ticket 1 3 dias 6 h ≈ 10,7%
  • Janela longa: o problema é significativo, não um soluço.
  • Janela curta: ainda está acontecendo → resolve logo depois da correção.
  • Como código: infra/grafana/alerting/slo-catalog.yaml (consultas A, B + matemática $A > 14.4 && $B > 14.4).

Dispare-o

Tráfego constante, uma hora saudável, depois docker compose stop db. Quando a regra de queima rápida aciona?

  • A fração de erros da última hora precisa chegar a 14,4 × 0,5% = 7,2%.
  • 0,072 × 60 min ≈ 4,3 min de queda, + for: 1m + avaliação ≈ 5–6 min.
  • Um soluço de 30 segundos nunca aciona; um vazamento lento de 4% é pego pela regra de 6 horas.
  • Execução de teste: Firing cerca de 440 s depois do stop — o teste de estresse do passo 2 ainda estava na janela de 1 hora.
  • start db: o page some cerca de 5 min depois, quando a queda sai da janela de 5 minutos.

Sem Docker: repita-o

10:12:31stop db
→
taxa de queima de 5 min: 200em um minuto
→
taxa de queima de 1 h > 14,4após 4,3 min
→
Pending → Firingfor: 1m → 5:30
→
start db → Normal5:00 depois
  • O simulador do passo de SLO: slo-catalog.yaml avaliado a cada 30 s, k6 a 50 req/s, um tick = 10 s.
  • Com o teste de estresse do passo 2 na janela → 7:30, "Burn rate 17.0 (1 h) and 200.0 (5 min)"; 10 min de histórico → 2:00.
  • 4% de erros nunca acionam; o ticket de 6 horas dispara após 3,1 h.

Passo 4 · Meça

# Experimento Registrar
A agente ligado vs desligado (OTEL_ON) p50 / p95 / p99, CPU, memória, inicialização
B amostragem 100% vs 10% (parentbased_traceidratio) p95, traces por minuto
C cardinalidade séries por serviço, o custo de um label user_id
D tempo de detecção parar db → Pending → Firing

k6 constant-arrival-rate em GET /catalog/events/{id} pela borda; docker stats durante a execução.

Armadilhas

  • O contexto quebra em saltos assíncronos: leve o traceparent em mensagens e linhas.
  • Labels ilimitados (ids, URLs, e-mails) explodem o número de séries.
  • Sem tráfego, sem SLI: combine alertas de SLO com uma sonda ou um alerta de "tráfego caiu".
  • Health checks no SLI escondem falhas reais.
  • Amostragem vale para traces, não para métricas: as taxas vêm das métricas.

Experimente no playground

  • observability-stack com o perfil chaos.
  • Desconecte as métricas de um serviço: a utilização dele vira "?".
  • O que reage primeiro a uma falha: erros, percentis ou health checks?
  • boxoffice-observability: o banco do catalog para por 100 s; só o Alerting encurta a queda.

Você não conserta o que não mede — e não mede o que não instrumentou.

O que quebra em seguida

lab 8 · o sistema se vêum trace por pedido · o alerta chama alguém ~440 s depois de parar o db, num teste
→
ver ≠ sobreviver10:02: o provedor de pagamento responde em 4 s em vez de 200 ms
→
lab 9 · capítulo 10timeout, retry, circuit breaker, bulkhead, um game day
  • O alerta dispara e o checkout morre mesmo assim: toda thread do order espera pelo provedor.

Pontos-chave

  1. Métricas dizem que, traces dizem onde, logs dizem por quê — ligados pelo trace_id.
  2. O agente Java instrumenta HTTP, JDBC, Kafka e logs sem código; o OTLP é o contrato.
  3. Saltos assíncronos (outbox, filas) precisam do traceparent levado com o dado.
  4. Dashboards e alertas são código no repositório.
  5. Alerte pela taxa de queima do SLO em duas janelas, não por limiares crus.
  6. Observabilidade tem custo — meça e amostre traces, não métricas.

Capítulo 9 da história da disciplina. Roteiro: (1) as perguntas que o k6 não responde; (2) otel-lgtm e o agente Java; (3) o outbox quebra o trace; (4) RED e USE como código; (5) SLO, orçamento de erros, taxa de queima; (6) disparar o alerta; (7) medir.

A história da disciplina (visão geral de 2027.1, "A história da disciplina"): o capítulo 9 abre com a assincronia escondendo falhas. O lab 7 mediu o outbox em 1,8 ms no p50 contra 2,7 s síncrono a 200 pedidos/s, numa execução de teste daquele lab.