Noções Básicas de Observabilidade

10 exemplos para você começar com Observabilidade - 7 básicos e 3 intermediários.

Pré-requisitos

uv venv && source .venv/bin/activate
uv pip install "structlog>=24.0" "prometheus-client>=0.21" "opentelemetry-sdk>=1.29"

• Python 3.14.0 com bibliotecas comuns de observabilidade instaladas.

Exemplos Básicos

1. Linha de Log Estruturada

Logs JSON são pesquisáveis em Loki, CloudWatch e ELK.

import json
import logging
 
logging.basicConfig(level=logging.INFO, format="%(message)s")
log = logging.getLogger("api")
 
log.info(json.dumps({"event": "order_created", "order_id": "ord_1", "ms": 42}))

• Um objeto JSON por linha (NDJSON) é o padrão de ingestão
• Inclua campos de domínio (order_id) e não apenas strings de mensagem
• O nível de log ainda importa para filtrar ruído

Relacionado: Logging Estruturado - configuração do structlog

2. ID de Correlação de Requisição

Vincule linhas de log a uma única requisição HTTP.

import uuid
from contextvars import ContextVar
 
request_id: ContextVar[str] = ContextVar("request_id", default="-")
 
def set_request_id() -> str:
    rid = str(uuid.uuid4())
    request_id.set(rid)
    return rid

• Passe X-Request-ID do gateway ou gere na borda
• ContextVar propaga o ID através de chamadas assíncronas do FastAPI na mesma tarefa
• Inclua request_id em cada registro de log nessa requisição

Relacionado: Rastreamento Distribuído - IDs de trace

3. Métrica de Contador

Conte eventos para dashboards de taxa e proporção de erros.

from prometheus_client import Counter
 
ORDERS_CREATED = Counter("orders_created_total", "Pedidos criados")
 
def create_order() -> None:
    ORDERS_CREATED.inc()

• Contador só aumenta - use para totais
• O sufixo _total no nome é convenção do Prometheus
• Exporte o endpoint /metrics para scraping

Relacionado: Métricas - histogramas e gauges

4. Histograma de Tempo / Latência

Meça quanto tempo as operações levam.

import time
 
start = time.perf_counter()
# ... trabalho ...
elapsed_ms = (time.perf_counter() - start) * 1000

• perf_counter é monotônico para durações
• Prefira métricas de histograma em vez de temporização manual em produção
• Registre limites de lentidão apenas quando excederem o SLO

Relacionado: Monitoramento de Desempenho (APM) - SLOs de latência

5. Endpoint de Saúde

Balanceadores de carga precisam de uma resposta OK barata.

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/health/live")
def live():
    return {"status": "ok"}

• Liveness: processo ativo
• Readiness: pode atender tráfego (adicione verificação de banco de dados em um caminho separado)
• Mantenha a liveness rápida - sem chamadas externas

Relacionado: Saúde e Prontidão - design de probes

6. Níveis de Log

Use níveis para separar sinal de ruído.

import logging
log = logging.getLogger("worker")
log.debug("detalhe para dev")
log.info("tarefa concluída")
log.warning("tentando novamente")
log.error("falhou permanentemente")

• INFO é o padrão em produção; DEBUG via flag de ambiente
• ERROR deve disparar alertas quando a taxa aumentar
• Não registre segredos em nenhum nível

Relacionado: Melhores Práticas de Observabilidade - regras de logging

7. Registro de Exceções

Capture stack traces com contexto.

import logging
log = logging.getLogger("api")
 
try:
    risky()
except Exception:
    log.exception("pagamento falhou", extra={"order_id": "1"})

• log.exception inclui o traceback automaticamente
• Adicione contexto de negócios no dicionário extra (o formatador JSON deve incluí-lo)
• Emparelhe com rastreamento de erros para agregação

Relacionado: Rastreamento de Erros - Sentry

Exemplos Intermediários

8. Esboço de Métricas RED

Taxa, Erros, Duração por endpoint.

# Taxa: contador requests_total
# Erros: contador requests_failed_total
# Duração: histograma request_duration_seconds

• Método RED para uma verificação rápida de sanidade para serviços orientados a requisições
• Método USE (Utilização, Saturação, Erros) para workers e pools de banco de dados
• Escolha o método que corresponda ao tipo de serviço

Relacionado: Métricas - buckets de histograma

9. Conceito de Span de Trace

Um ID de trace, múltiplos spans entre serviços.

[Span da API] -> [Span do DB] -> [Span de publicação SQS]

• Spans têm relacionamentos pai/filho
• OpenTelemetry padroniza cabeçalhos de propagação
• Amostre traces em produção para controlar custos

Relacionado: Rastreamento Distribuído - OpenTelemetry

10. Os Três Pilares Juntos

Fluxo de incidente: alerta de métrica → logs com request_id → cascata de trace.

# 1. Alerta: taxa_erro > 1%
# 2. Consulta de log: request_id="abc" E level=ERROR
# 3. UI de Trace: trace_id do campo de log

• Correlacione campos (trace_id, request_id) entre os pilares
• Dashboards vinculam à busca de logs e UI de trace
• Runbooks documentam esse fluxo para plantão

Relacionado: Melhores Práticas de Observabilidade - higiene de plantão

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.