Signal Path: Da métrica ao post-mortem

Monitoring não é observabilidade

Monitoring responde perguntas que você já sabia que faria: o contêiner está no ar?, a CPU passou de 80%?, o endpoint responde? Observabilidade permite responder perguntas que você não antecipou: por que apenas algumas requests de /checkout levaram 8 segundos entre 14:02 e 14:07?

A matéria-prima são os dados que seu sistema emite — a telemetria — e os três sinais clássicos são métricas, logs e traces. Cada um responde uma pergunta diferente, e o valor real aparece quando você os conecta.

Os quatro Golden Signals

Latência (quanto demoram as requests), tráfego (quanto trabalho entra), erros (quantas falham) e saturação (quão perto do limite você está). Com esses quatro números você responde em dez segundos se um serviço está saudável.

Dois métodos derivados organizam o trabalho: RED (Rate, Errors, Duration) olha o serviço pela ótica do usuário; USE (Utilization, Saturation, Errors) olha o recurso — CPU, memória, disco, conexões de banco. Um bom dashboard usa os dois, nessa ordem: primeiro impacto, depois causa.

Percentis, não médias

Se 99 requests levam 100 ms e uma leva 10 s, a média mente e aquele usuário foi embora. Por isso medimos p50 (experiência típica), p95 (o usado em acordos) e p99 (a cauda longa, onde vivem timeouts e retries).

Três tipos de métrica dão conta de quase tudo

Um counter só sobe e conta eventos: requests, erros, mensagens processadas. Um gauge sobe e desce e mede um estado instantâneo: conexões abertas, itens na fila, memória. Um histogram distribui observações em buckets e é o que permite calcular percentis de latência no lado do servidor.

A instrumentação mínima de qualquer serviço HTTP são duas métricas: um counter de requests com labels route, method e status, e um histogram de duração com as mesmas labels.

Prometheus em Docker Compose

services:
  prometheus:
    image: prom/prometheus:latest
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.retention.time=15d
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports: ["9090:9090"]

O scrape config aponta para o seu serviço pelo nome da rede interna: no Compose (e num stack de Coolify ou Portainer) os contêineres se enxergam pelo nome do serviço, então targets: ['api:3000'] basta. Nunca exponha /metrics à internet sem proteção.

As três queries que você vai usar sempre

# tráfego (req/s)
sum(rate(http_requests_total[5m]))

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

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

A ordem importa mais que os painéis

Um dashboard operacional se lê de cima para baixo como uma triagem. Camada 1: impacto — disponibilidade, error rate, latência, error budget. Camada 2: RED — tráfego, erros e duração por rota. Camada 3: saturação — CPU, memória, réplicas, restarts, pool de conexões. Camadas 4 e 5 (a partir do módulo 6): logs e traces do período que você está olhando.

Grafana também entra no compose

  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
      - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
    ports: ["3001:3000"]

O volume de provisioning é o que separa um brinquedo de algo operável: datasources e dashboards definidos por arquivo, versionados no git, reproduzíveis em outro VPS. Um dashboard feito na mão na UI e não exportado se perde no dia em que o volume quebra.

Variáveis: um painel, muitos serviços

Em vez de clonar o dashboard por serviço, defina uma variável $service com a query label_values(http_requests_total, service) e use em todas as consultas. O mesmo painel serve para sua API, seu worker e o bot de WhatsApp.

Três siglas que não são sinônimos

O SLI é o que você mede (disponibilidade = 99,92%). O SLO é a meta interna que você define (99,9% em 30 dias). O SLA é um compromisso contratual com dinheiro ou créditos no meio. Quase nenhum serviço precisa de SLA; quase todos deveriam ter SLO.

O error budget

Se o SLO é 99,9%, você pode falhar 0,1%. Em 30 dias isso dá 43 minutos e 12 segundos de indisponibilidade. Esse orçamento é uma ferramenta de decisão: enquanto sobra budget, dá para deployar rápido e correr riscos; quando queimou, a prioridade vira estabilizar.

SLO 99.9%   → 43m 12s / 30 dias
SLO 99.95%  → 21m 36s / 30 dias
SLO 99.99%  →  4m 19s / 30 dias

Burn rate: a velocidade de queima

O burn rate é quanto mais rápido do que o permitido você está gastando o orçamento: error_ratio / (1 − SLO). Um burn rate de 1× consome o budget exatamente em 30 dias. Um 14,4× consome em pouco mais de dois dias — isso justifica acordar alguém. Um 3× sustentado não é urgente hoje à noite, mas destrói o mês.

Recording rules: calcule uma vez

groups:
  - name: slo
    interval: 30s
    rules:
      - record: job:http_error_ratio:rate5m
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m]))
          / sum(rate(http_requests_total[5m]))
      - record: job:http_availability:ratio30d
        expr: 1 - (
          sum(rate(http_requests_total{status=~"5.."}[30d]))
          / sum(rate(http_requests_total[30d])))

O teste das três da manhã

Antes de criar um alerta, responda: se isso tocar às 3h, alguém precisa levantar e fazer algo agora? Se a resposta for não, não é um page: é um ticket, ou puro ruído. Fadiga de alerta é a forma mais rápida de um time parar de olhar o celular.

Alertas multi-janela de burn rate

A receita padrão do Google usa duas janelas por severidade, para detectar rápido sem disparar por um pico de trinta segundos: a janela longa confirma que o problema é real, a curta confirma que continua acontecendo.

groups:
  - name: slo-alerts
    rules:
      - alert: ErrorBudgetFastBurn
        expr: |
          job:http_error_ratio:rate1h > (14.4 * 0.001)
          and job:http_error_ratio:rate5m > (14.4 * 0.001)
        for: 2m
        labels: { severity: page }
        annotations:
          summary: "Queima rápida do error budget"
          runbook: "https://git.seu-dominio/runbooks/availability.md"

      - alert: ErrorBudgetSlowBurn
        expr: |
          job:http_error_ratio:rate6h > (6 * 0.001)
          and job:http_error_ratio:rate30m > (6 * 0.001)
        for: 15m
        labels: { severity: ticket }

O Alertmanager decide quem fica sabendo

O Prometheus detecta a condição; o Alertmanager faz o resto: agrupa alertas relacionados para não mandar vinte mensagens, deduplica, silencia durante manutenções e inibe alertas filhos quando o pai já disparou. A rota é definida por label: severity: page vai para o canal que acorda, severity: ticket para o que se lê em horário comercial.

Todo alerta precisa de um runbook

A anotação runbook não é decorativa: é o link que a pessoa de plantão abre meio dormindo. Se o alerta não tem runbook, ainda não está pronto.

Um log é um evento, não uma frase

Log em texto livre: Erro ao processar o pedido do usuário. Log estruturado:

{"ts":"2026-09-08T14:03:11Z","level":"error","service":"api",
 "route":"/orders/:id","status":500,"duration_ms":831,
 "trace_id":"b2fe643bc4d341a1f7076f265910e649","order_id":"o_8812",
 "msg":"payment gateway timeout"}

O segundo dá para filtrar, agrupar e contar. Os campos mínimos que não podem faltar: timestamp, level, service, route, status, duration_ms e trace_id. Esse último campo é o que vai conectar este log ao seu trace no módulo 8.

Loki não é Elasticsearch

O Loki não indexa o conteúdo do log: indexa só as labels do stream e guarda o resto comprimido. Por isso é barato de rodar num VPS, e por isso as labels precisam ser poucas e de baixa cardinalidade: service, env, level. Nada além disso.

Coleta no Docker

  loki:
    image: grafana/loki:latest
    command: -config.file=/etc/loki/local-config.yaml
    volumes: [ "loki-data:/loki" ]

  alloy:
    image: grafana/alloy:latest
    volumes:
      - ./alloy/config.alloy:/etc/alloy/config.alloy:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    command: run /etc/alloy/config.alloy

O Alloy descobre os contêineres pelo socket do Docker, aplica labels a partir do nome e das etiquetas do contêiner, e empurra para o Loki. Alternativa mais simples se seu VPS já estiver organizado: o driver de logs do Docker apontando direto para o Loki.

LogQL em três movimentos

# todos os erros do serviço
{service="api", level="error"}

# só 5xx, parseando o JSON
{service="api"} | json | status >= 500

# taxa de erros por rota, últimos 5 minutos
sum by (route) (
  rate({service="api"} | json | status >= 500 [5m]))

Trace, span e contexto

Um trace é o percurso completo de uma request pelo seu sistema. Cada etapa mensurável é um span: a request HTTP de entrada, a query no Postgres, o GET na API de pagamentos, o job enfileirado. Os spans formam uma árvore, e ali se vê na hora onde o tempo foi:

POST /orders                    2.41s
├── auth.verify                  38ms
├── db.query orders_insert      142ms
├── http POST payments.api      2.14s   ←
└── queue.publish order.created  21ms

A conclusão não é "a app está lenta": é "o gateway de pagamentos está consumindo 89% do tempo". São duas conversas completamente diferentes.

OpenTelemetry: instrumentar uma vez

OTel é o padrão aberto que evita ficar preso a um fornecedor: você instrumenta com o SDK dele e depois decide para onde manda os dados — Tempo hoje, Datadog ou Grafana Cloud amanhã, sem tocar no código da app.

A auto-instrumentação cobre o óbvio (servidor HTTP, cliente HTTP, driver de banco, Redis) com pouquíssimo código. Os spans manuais você adiciona onde está sua lógica cara: o cálculo pesado, a chamada ao LLM, o render do PDF.

O Collector como amortecedor

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes: [ "./otel/config.yaml:/etc/otel/config.yaml:ro" ]
    ports: ["4318:4318"]   # OTLP/HTTP

  tempo:
    image: grafana/tempo:latest
    command: ["-config.file=/etc/tempo.yaml"]
    volumes:
      - ./tempo/tempo.yaml:/etc/tempo.yaml:ro
      - tempo-data:/var/tempo

A app fala OTLP com o Collector, e o Collector decide o que fazer: filtrar spans de health check, amostrar, adicionar atributos de ambiente e exportar para o Tempo. Trocar de backend depois é trocar um exporter, não redeployar a aplicação.

TraceQL para achar a agulha

{ resource.service.name = "api" && duration > 1s }
{ span.http.status_code >= 500 }
{ name = "http POST payments.api" && duration > 2s }

Uma chave comum: trace_id

Os três sinais que você montou até aqui vivem em bases diferentes. O que os conecta é um identificador que viaja com a request: o trace_id. Se seu histogram o anexa como exemplar, seu log o escreve como campo e seu trace o tem por definição, você percorre o caminho inteiro sem escrever uma query na mão.

Exemplars: da métrica ao trace

Um exemplar é um ponto concreto anexado a um bucket do histogram, com o trace_id de uma request real que caiu ali. No gráfico de latência aparece como um pontinho sobre a curva: você clica e abre o trace que produziu aquele valor.

# o Prometheus precisa do feature habilitado
command:
  - --enable-feature=exemplar-storage

# e o scrape em formato OpenMetrics
scrape_configs:
  - job_name: api
    static_configs: [{ targets: ["api:3000"] }]

Do lado da app, a biblioteca do Prometheus precisa registrar a observação com o exemplar do trace ativo. Em Node com prom-client passa-se como terceiro argumento do observe(); em Python, com exemplar=.

Derived fields: do log ao trace

Na configuração do datasource do Loki você define um campo derivado que detecta o trace_id no JSON e o transforma num botão que abre o Tempo:

derivedFields:
  - name: TraceID
    matcherRegex: '"trace_id":"(\w+)"'
    url: '${__value.raw}'
    datasourceUid: tempo

E no datasource do Tempo você ativa o caminho inverso (Trace to logs): de um span, pular para os logs daquele mesmo trace_id na janela de tempo do span. Ida e volta fechada.

O percurso completo

Alerta de burn rate
      ↓  (link do runbook)
Dashboard: p95 em 12s desde as 14:02
      ↓  (clique no exemplar)
Trace: POST /orders — 11.8s em payments.api
      ↓  (Trace to logs)
Log: "payment gateway timeout" order_id=o_8812
      ↓
Causa encontrada — 4 minutos desde o alerta

As quatro etapas e os três relógios

Um incidente é detectado, reconhecido, mitigado e resolvido — e cada trecho tem sua métrica. MTTD (detectar): do primeiro erro ao alerta. MTTA (reconhecer): do alerta até alguém assumir. MTTR (restaurar): do início ao serviço normal. Se você não mede os três separadamente, não sabe qual melhorar: um MTTD de 20 minutos não se resolve com mais gente de plantão, se resolve com alertas melhores.

Severidade: defina antes de precisar

SEV1  Serviço fora ou perda de dados.
      Todos os usuários. Acorda-se gente. Comunicação imediata.
SEV2  Degradação séria: SLO em risco, funcionalidade
      importante quebrada. Atende-se já, no horário ou fora.
SEV3  Impacto limitado ou com workaround.
      Ticket, resolve-se em horário comercial.

O critério é sempre impacto no usuário, nunca quanto código precisa ser tocado. Um typo no CSS do checkout que impede comprar é SEV1; um worker de relatórios parado pode ser SEV3.

Anatomia de um runbook que serve

Um runbook é para quem abre o celular às 3h, não para quem escreveu o sistema. Cinco seções:

1. Sintoma — qual alerta disparou e o que o usuário está vendo.
2. Verificação — as queries exatas, copiáveis, com links do dashboard.
3. Mitigação — comandos concretos, em ordem, do menos ao mais destrutivo.
4. Escalação — para quem ligar e a partir de qual minuto.
5. Pós-incidente — o que salvar antes que se perca: trace_ids, prints, janela de horário.

Post-mortem sem culpados, de verdade

"Blameless" não é gentileza: é a única coisa que faz as pessoas contarem o que realmente aconteceu. Se quem apertou o botão sabe que vai ser apontado, na próxima o timeline vai ter buracos justamente onde estava a informação útil. A pergunta certa nunca é quem errou, e sim o que fez aquela ação parecer razoável naquele momento.

As seis seções

1. Resumo         — 3 linhas: o que houve, quem foi afetado, quanto durou.
2. Impacto        — usuários, requests falhas, error budget consumido,
                    dinheiro se aplicável.
3. Timeline       — com horas exatas: primeiro erro, alerta, ack,
                    mitigação, resolução. Dali saem MTTD/MTTA/MTTR.
4. Causa          — a técnica e também a contribuinte (por que o
                    sistema permitiu que acontecesse).
5. O que funcionou— sim, esta seção entra. O alerta que disparou certo e
                    o runbook que serviu também são resultados.
6. Action items   — cada um com dono, data e ticket. Sem dono não é
                    action item, é comentário.

GameDay: quebrar de propósito, em horário comercial

Um GameDay é um incidente planejado: você escolhe um dia, avisa o time, injeta falhas reais e verifica se sua observabilidade as detecta. É a única forma honesta de saber se a stack serve — porque no dia do incidente real você não quer descobrir que o alerta nunca esteve bem configurado.

Hipótese:   "Se o provedor de pagamentos começar a devolver 500,
             o alerta fast burn dispara em menos de 5 minutos e
             o runbook nos leva à causa em menos de 10."
Injeção:    proxy que devolve 500 em 30% das chamadas
Observação: disparou? em quanto tempo? o runbook bastou?
Aprendizado: o que faltou — um span, um painel, um passo do runbook

Três falhas para começar

Dependência externa lenta ou quebrada, saturação de recursos (CPU no limite ou pool de conexões esgotado), e perda de um contêiner (matar e ver se o sistema se recupera sozinho). Com essas três você já encontra pelo menos um buraco na sua instrumentação.