Observabilidade: logs, métricas e tracing

1. Fundamentos da Observabilidade em Sistemas Distribuídos

Observabilidade não é sinônimo de monitoramento. Enquanto monitoramento responde a perguntas conhecidas (ex.: "o CPU está acima de 90%?"), observabilidade permite fazer perguntas novas sobre sistemas que nunca vimos antes. Em sistemas distribuídos modernos — microsserviços, alta concorrência, deploys contínuos — a complexidade torna impossível prever todos os modos de falha.

Os três pilares da observabilidade são:

  • Logs: registros discretos de eventos ocorridos no sistema
  • Métricas: dados numéricos agregados ao longo do tempo
  • Tracing: rastreamento do caminho de uma requisição através de múltiplos serviços

Cada pilar cobre uma dimensão diferente. Logs respondem "o que aconteceu?", métricas respondem "quantas vezes e com que frequência?", e tracing responde "por onde passou e quanto tempo levou?". A verdadeira observabilidade surge quando esses três dados podem ser correlacionados.

2. Logs: Estruturação, Coleta e Contexto

Logs não estruturados são difíceis de consultar e correlacionar. O padrão moderno é usar logs estruturados em JSON, que permitem consultas precisas e parsing automático.

# Log não estruturado (ruim)
2025-01-15 14:30:22 ERROR timeout connecting to database

# Log estruturado (bom)
{"timestamp":"2025-01-15T14:30:22Z","level":"ERROR","service":"payment-api","correlation_id":"abc123","message":"timeout connecting to database","db_host":"db-primary:5432","timeout_ms":5000}

Níveis de severidade (DEBUG, INFO, WARN, ERROR, FATAL) devem ser usados consistentemente. Evite logar em loops de alta frequência ou dados sensíveis (senhas, tokens).

O correlation ID é essencial para rastrear uma requisição entre serviços. Ele deve ser gerado na borda do sistema (gateway, load balancer) e propagado via headers HTTP.

# Propagação de correlation ID entre serviços
# Serviço A (gateway) gera e envia para Serviço B
GET /api/orders HTTP/1.1
X-Correlation-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Serviço B registra o correlation ID nos logs
{"correlation_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","service":"order-service","event":"order_created","order_id":12345}

3. Métricas: Indicadores-Chave e Agregação

Os quatro tipos principais de métricas são:

  • Contadores: valores que só aumentam (ex.: requisições totais, erros acumulados)
  • Gauges: valores que podem subir e descer (ex.: memória usada, conexões ativas)
  • Histogramas: distribuição de valores (ex.: latência em percentis P50, P95, P99)
  • Summaries: similar a histogramas, mas calculados no cliente

Para serviços de alto throughput, as métricas essenciais são:

# Métricas fundamentais (formato Prometheus)
# Taxa de erro
rate(http_requests_total{status=~"5.."}[5m])

# Latência no percentil 99
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

# Throughput
rate(http_requests_total[1m])

Prometheus usa modelo pull (scrape dos endpoints /metrics), enquanto sistemas como Graphite usam push. O modelo pull facilita descoberta de serviços e reduz risco de sobrecarga. Cuidado com alta cardinalidade — labels como user_id ou request_id criam séries temporais ilimitadas e podem derrubar o banco.

4. Tracing: Rastreamento de Requisições entre Serviços

Tracing representa uma requisição como uma árvore de spans. Cada span é uma unidade de trabalho (ex.: chamada a banco, cache, serviço externo). O conjunto de spans forma um trace, identificado por um Trace ID único.

# Estrutura de um trace com W3C Trace Context
# Header propagado entre serviços
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
# 00 = versão, trace-id, span-id, trace-flags

# Spans em um trace de pagamento
[Span A: process_payment] (duração: 250ms)
  ├── [Span B: validate_card] (duração: 80ms)
  ├── [Span C: charge_gateway] (duração: 150ms)
  └── [Span D: update_ledger] (duração: 20ms)

Sampling é necessário para controlar volume de dados:

  • Head-based: decide no início da requisição se o trace será amostrado (ex.: 1% de todas as requisições)
  • Tail-based: amostra traces completos após o término, baseado em regras (ex.: todos os traces com erro ou latência > 500ms)
  • Adaptive: ajusta dinamicamente a taxa de amostragem baseado no volume atual

O tracing revela latências ocultas que métricas agregadas escondem. Por exemplo, uma métrica de latência média de 200ms pode esconder que 5% das requisições levam 2 segundos devido a timeouts de banco.

5. Integração e Correlação entre os Três Pilares

A correlação prática exige que logs, métricas e tracing compartilhem identificadores comuns (correlation ID, trace ID, service name).

# Exemplo de query correlacionada no Grafana

# 1. No Loki (logs): encontrar correlation IDs com erro
{service="payment-api"} |= "ERROR" | json | correlation_id = "abc123"

# 2. No Prometheus (métricas): ver taxa de erro para aquele serviço
rate(http_requests_total{service="payment-api", status="500"}[5m])

# 3. No Tempo/Jaeger (traces): ver o trace completo da requisição com erro
{correlation_id="abc123"} -> trace_id -> visualizar árvore de spans

Dashboards unificados no Grafana podem combinar os três painéis:

# Layout de dashboard unificado
# Linha 1: Métricas (latência P95, taxa de erro, throughput)
# Linha 2: Logs em tempo real (filtrados pelo mesmo serviço)
# Linha 3: Lista de traces lentos ou com erro (link direto para Jaeger)

6. Ferramentas e Stack Tecnológica Recomendada

OpenTelemetry é o padrão aberto para instrumentação, suportando logs, métricas e tracing com um único SDK. Ele substitui o OpenTracing e OpenCensus.

Stack auto-gerenciada (CNCF):

Ferramenta Função
Prometheus Métricas (pull)
Grafana Dashboards
Loki Logs (agregação e consulta)
Tempo ou Jaeger Tracing

Alternativas SaaS:

  • Datadog: integração nativa, fácil setup, mas custo elevado com alto volume
  • New Relic: similar, com foco em APM
  • Honeycomb: foco em observabilidade de alta cardinalidade

Para times pequenos, SaaS reduz overhead operacional. Para grandes volumes com orçamento restrito, a stack auto-gerenciada é mais econômica.

7. Estratégias de Implementação e Boas Práticas

Instrumentação incremental: comece pelos endpoints críticos (login, checkout, pagamento) e fluxos de maior risco. Não tente instrumentar tudo de uma vez.

Gerenciamento de custos:

# Políticas recomendadas
- Métricas: retenção de 30 dias para alta resolução, 1 ano para agregados diários
- Logs: retenção de 7-14 dias para debug, 30 dias para erros
- Traces: sampling de 1-5% para tráfego normal, 100% para erros (tail-based)
- Compressão: logs e traces em formato parquet ou gzip

Cultura de observabilidade:

  • Alertas acionáveis: alarme só quando requer ação humana imediata (evite "alarm fatigue")
  • SLOs (Service Level Objectives): defina metas de latência e disponibilidade baseadas em métricas
  • Runbooks: documente procedimentos para cada alerta, vinculando logs, métricas e traces relevantes

A observabilidade não é uma ferramenta — é uma prática contínua de entender o comportamento do sistema através de dados correlacionados.

Referências