Sinais

A primeira pergunta durante um incidente nunca é "por quê?" — é "há algo errado, e onde devo olhar?". A segunda é "o que exatamente aconteceu com esta requisição?". A terceira é "qual linha de código está queimando o tempo?". Cada pergunta precisa de um tipo diferente de dado, com um custo diferente. Emitir todos os detalhes de todas as requisições responde a todas elas e leva você à falência; emitir só gráficos de CPU é barato e não responde a nenhuma. Esta página trata de escolher o sinal certo para cada pergunta.

Quatro sinais, um espectro

Pense nisso como um espectro que vai do agregado e barato ao detalhado e caro. Métricas comprimem um milhão de requisições em alguns números por intervalo — você pode guardá-las por meses, mas não consegue perguntar sobre uma requisição. Logs e traces guardam cada requisição — você pode perguntar qualquer coisa sobre ela, mas precisa amostrar, filtrar ou expirar esses dados.

flowchart LR
    M["Métricas<br/>agregadas · baratas · retenção longa"] --> T["Traces<br/>por requisição · amostrados"]
    T --> L["Logs<br/>por evento · verbosos"]
    L --> P["Profiles<br/>por caminho de código"]

Métricas

O modelo de dados

Uma métrica é uma série temporal: um nome, um conjunto de labels chave-valor (também chamados de atributos ou dimensões) e uma sequência de amostras (timestamp, valor).

http_server_request_duration_seconds_count{job="order", http_route="/orders", http_request_method="POST", http_response_status_code="201"}  48213

Cada combinação distinta de valores de labels é uma série temporal separada que o banco precisa indexar e manter em memória. Esse único fato explica a maior parte dos problemas operacionais com métricas (veja cardinalidade).

Os histogramas são os importantes. Cada bucket é um contador "quantas observações foram ≤ este limite": com limites 0,1, 0,25, 0,5, 1, 2,5 s, um checkout de 0,3 s incrementa os buckets 0.5, 1, 2.5 e +Inf. Como os buckets são contadores, os histogramas de 20 pods podem ser somados e um percentil estimado a partir do total. Formatos mais novos — os native histograms do Prometheus e os exponential histograms do OpenTelemetry — escolhem os limites dos buckets automaticamente, com erro relativo limitado, o que elimina o erro mais comum: buckets que não cobrem o limiar do seu SLO.

Pull vs push

Os dois funcionam; stacks modernas misturam ambos. Com OpenTelemetry, o padrão é push via OTLP para um Collector, que também pode fazer scrape de endpoints Prometheus existentes (OpenTelemetry).

RED, USE e os quatro golden signals

Você não precisa de centenas de métricas por serviço. Três checklists conhecidos dizem quais poucas importam:

Os golden signals são essencialmente RED + saturação. A saturação é o sutil: o quão cheio um recurso está, geralmente visível como espera — uma fila, um pool com pedidos pendentes, threads bloqueadas. Utilização perto de 100% não é um problema por si só; trabalho esperando na fila é.

RED em PromQL

PromQL é a linguagem de consulta do Prometheus (e do Mimir, do Thanos e da maioria dos backends compatíveis). Duas regras evitam a maioria das consultas erradas: aplique rate() a um counter antes de somá-lo (ele trata os resets do contador quando um pod reinicia), e mantenha o label le ao somar buckets de histograma.

# Rate: requests per second, per route, of the order service
sum by (http_route) (
  rate(http_server_request_duration_seconds_count{job="order"}[5m])
)

# Errors: fraction (0..1) of 5xx responses
sum(rate(http_server_request_duration_seconds_count{job="order", http_response_status_code=~"5.."}[5m]))
/
sum(rate(http_server_request_duration_seconds_count{job="order"}[5m]))

# Duration: p99 latency per route, aggregated across all pods
histogram_quantile(0.99,
  sum by (le, http_route) (
    rate(http_server_request_duration_seconds_bucket{job="order"}[5m])
  )
)

# SLI style: fraction of checkouts faster than 2 s (needs a bucket at le="2")
sum(rate(http_server_request_duration_seconds_bucket{job="order", http_route="/checkout", le="2"}[5m]))
/
sum(rate(http_server_request_duration_seconds_count{job="order", http_route="/checkout"}[5m]))

"title": "Rate (requests/s)",
    "expr": "sum by (service_name) (rate(http_server_request_duration_seconds_count{service_name=~\"$service\"}[$__rate_interval]))",
"title": "Errors (% of requests answered 5xx)",
    "expr": "100 * sum by (service_name) (rate(http_server_request_duration_seconds_count{service_name=~\"$service\", http_response_status_code=~\"5..\"}[$__rate_interval])) / sum by (service_name) (rate(http_server_request_duration_seconds_count{service_name=~\"$service\"}[$__rate_interval]))",
"title": "Duration p95 (s)",
    "expr": "histogram_quantile(0.95, sum by (service_name, le) (rate(http_server_request_duration_seconds_bucket{service_name=~\"$service\"}[$__rate_interval])))",

Percentis, não médias — e nunca a média de percentis

Uma latência média esconde a cauda: se 99 checkouts levam 100 ms e um leva 10 s, a média é ~200 ms e parece ótima, mas um fã em cada cem espera dez segundos — e uma página que faz 20 chamadas encontra essa cauda na maioria dos carregamentos (veja Percentis).

Um erro mais sutil é calcular o p99 por pod e depois tirar a média entre os pods. Percentis não se compõem: o p99 da frota inteira não é a média dos p99 dos pods. A simulação abaixo tem quatro pods do order; um deles divide um nó com um vizinho barulhento (noisy neighbour) e está lento, e recebe 10% do tráfego.

Tirar a média dos percentis dos pods subestima a cauda que os usuários realmente sentem. Os histogramas evitam o problema porque seus buckets são contadores que podem ser somados antes de o percentil ser estimado — que é exatamente o que o sum by (le) faz na consulta acima.

Cardinalidade

Cardinalidade é o número de séries temporais distintas que uma métrica produz: o produto do número de valores de cada label. É o principal fator de memória, custo e velocidade de consulta de um backend de métricas — e o jeito mais comum de os times derrubarem, sem querer, o próprio monitoramento.

A tabela abaixo faz crescer o histograma de latência do checkout, label por label. Cada série de histograma são, na verdade, 17 séries (15 buckets, _sum, _count); a coluna de memória supõe, como ilustração, cerca de 4 KB por série ativa no banco de séries temporais.

Os cinco primeiros labels são limitados: o número de valores é pequeno e conhecido (as rotas são templates como /orders/{id}, não /orders/42). Juntos, produzem no máximo cerca de 200 mil séries (um limite superior: nem toda rota devolve todo status) — uma carga normal para um servidor Prometheus. O último label é ilimitado: cresce com o número de usuários e multiplica tudo o que veio antes. Nenhum sistema de métricas sobrevive a isso.

Logs

Um log é um registro com timestamp de um evento discreto. Logs são o sinal mais familiar e o mais fácil de abusar: escrevê-los é de graça e guardá-los é caro.

Logs estruturados

Escreva logs como registros estruturados (JSON, ou o modelo de dados de log do OpenTelemetry) com nomes de campo fixos, não como texto livre.

{
  "timestamp": "2027-03-13T10:04:12.481Z",
  "level": "WARN",
  "service.name": "payment",
  "message": "provider call slow",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "order_id": "ord_9912",
  "provider": "acme-pay",
  "duration_ms": 8120,
  "pool_wait_ms": 7900
}

Os campos trace_id e span_id são o que transforma uma linha de log em parte de uma investigação: de um span lento você salta exatamente para as linhas de log dele, e de uma linha de erro você salta para o trace completo. Com o agente Java do OpenTelemetry, eles são adicionados ao contexto de logging automaticamente (OpenTelemetry).

O que (não) registrar

• Registre eventos, não passos. Uma linha "checkout concluído" com dez campos vale mais que dez linhas "entrando no método X".
• Nunca registre segredos ou dados pessoais: senhas, tokens, números de cartão, e-mails completos. Mascare na origem e, como segunda barreira, remova no Collector.
• Registre a decisão, não só o resultado: "fallback para o provedor B porque o breaker está aberto" explica a próxima hora de gráficos.
• Erros uma vez só: registre uma exceção onde ela é tratada, não em cada camada que ela atravessa.

Consultando logs

Com o Loki (o "L" da stack Grafana LGTM), os labels selecionam os streams e o resto da linha é interpretado na hora da consulta, o que mantém a indexação barata:

{service_name="payment"} | json | level="WARN" | duration_ms > 5000

Traces

Um trace registra o caminho de uma requisição pelo sistema como uma árvore de spans. Um span é uma operação cronometrada — uma chamada HTTP recebida ou enviada, uma consulta ao banco, uma mensagem produzida ou consumida — com horário de início, duração, status e atributos.

Lendo um waterfall

O trace de um checkout lento durante a venda relâmpago, desenhado como o waterfall que o Tempo ou o Jaeger mostram:

trace 4bf92f35…   POST /checkout                       total 9.12 s
                                         0s        3s        6s        9s
gateway    SERVER POST /checkout          |██████████████████████████████|  9.12 s
 order     SERVER POST /orders            | █████████████████████████████|  9.08 s
  inventory CLIENT PUT /holds/{id}        | ▌                            |  0.09 s
   postgres CLIENT UPDATE seat_holds      | ▏                            |  0.02 s
  payment  SERVER POST /charges           |  ████████████████████████████|  8.95 s
   payment INTERNAL pool.acquire          |  ██████████████████████████  |  7.90 s
   payment CLIENT POST provider/charges   |                          ███▌|  1.02 s
  order    PRODUCER order-events publish  |                             ▏|  0.01 s

Leia de cima para baixo e procure o caminho crítico — a cadeia de spans que determina o tempo total. Aqui não é a chamada ao provedor (1 s, lenta mas não dramática): são 7,9 s esperando por uma conexão do pool do adaptador de pagamentos. O provedor ficou mais lento, cada chamada segurou sua conexão por mais tempo e, pela lei de Little (concorrência = vazão × tempo), o pool de 20 conexões saturou — então a maior parte do tempo foi gasta em fila dentro do BoxOffice. Sem o span pool.acquire, você culparia o provedor pelos nove segundos; com ele, você sabe que a correção é um pool com espera limitada mais um timeout (Padrões de resiliência).

Profiles

Um profile amostra, muitas vezes por segundo, o que cada thread de um processo está executando — a pilha de chamadas completa — e agrega as amostras. O profiling contínuo faz isso o tempo todo em produção com baixo overhead (as ferramentas costumam mirar em torno de 1–2% de CPU), então você pode comparar "10h00 de hoje" com "10h00 da semana passada".

A visualização usual é o flame graph⁵: cada caixa é uma função, sua largura é a fração das amostras em que ela estava na pilha, e as filhas ficam em cima de quem as chamou. Platôs largos no topo são onde a CPU realmente vai.

O profiling virou o quarto sinal do OpenTelemetry (ainda amadurecendo em 2026), e profilers baseados em eBPF (Parca, Pyroscope, profilers de nuvem) conseguem perfilar todos os processos de um nó sem alterar a aplicação. Traces dizem qual serviço e qual operação está lenta; profiles dizem qual função dentro dele.

Dashboards

Um dashboard é um conjunto de consultas salvas, organizadas para responder rapidamente a uma pergunta. A maioria dos dashboards falha porque tenta mostrar tudo; os úteis são projetados de cima para baixo, do que os usuários sentem ao que os recursos fazem.

flowchart TB
    L1["1 · Jornadas do usuário e SLOs<br/>busca, reserva de assento, checkout: SLI, budget restante"]
    L2["2 · Serviços — RED<br/>por serviço e rota: taxa, erros, p50/p99"]
    L3["3 · Dependências<br/>latência do provedor, BD, hit ratio do cache, lag do Kafka"]
    L4["4 · Recursos — USE<br/>CPU, memória, pools, filas por pod/nó"]
    L1 --> L2 --> L3 --> L4

• Um dashboard, um propósito. A visão de on-call "o checkout está saudável?" cabe numa tela; os mergulhos profundos ficam em outro lugar.
• Mesmo eixo de tempo, mesmas unidades: segundos para latência, razões (0–1) ou porcentagens para erros, nunca misturados num mesmo painel.
• Mostre percentis e o limiar do SLO como uma linha no painel de latência, para o olho comparar de uma vez.
• Anote deploys e feature flags: a maioria dos incidentes começa numa mudança.
• Dashboards como código (JSON do Grafana no Git, Jsonnet/Grafonnet, Terraform): revisados, versionados e reproduzíveis, em vez de clicados à mão e perdidos.

Trade-offs

Como se conecta

flowchart LR
    REQ["one checkout:<br/>gateway → order → payment"] --> MET["metrics: RED per route,<br/>USE per pool and topic"]
    REQ --> TR["trace: spans,<br/>critical path"]
    REQ --> LOG["structured log<br/>with trace_id"]
    MET --> HIST["histograms → p99<br/>→ Estimation: percentiles"]
    MET --> CARD["bounded labels<br/>(cardinality)"]
    CARD -->|"high-cardinality detail"| TR
    TR --> WAIT["pool.acquire wait<br/>→ Little's law"]
    WAIT --> RES["timeout + bulkhead<br/>→ Reliability patterns"]
    TR --> PROF["profiles: which function<br/>→ Performance"]
    MET --> SLI["SLI per journey<br/>→ Alerting, SLOs"]

Componentes da paleta: metrics · logs · tracing · app (RED por serviço) · sql (USE do pool de conexões) · kafka (consumer lag) · payment (RED do lado do cliente na chamada ao provedor). Cenários: observability-stack, event-fanout (consumer lag), cascading-failure (um provedor lento saturando um pool). Continua em: OpenTelemetry, Alertas, Estimativas — percentis, Estimativas — filas, Confiabilidade — padrões, Performance — gargalos (flame graphs), Hands-on 8 — dashboard RED.

Pontos-chave