Boas Práticas de Observabilidade

Sinais acionáveis, não ruído, significam que a equipe de plantão acorda para problemas que impactam o cliente - não para volume de logs ou cardinalidade de métricas ilimitada.

Como Usar Esta Lista

• Implemente antes de declarar pronto para produção.
• Revise o roteamento de alertas trimestralmente - exclua regras barulhentas.
• Emparelhe com runbooks que vinculam dashboards a etapas de remediação.

A - Logging

• Emita logs JSON em produção. Um objeto por linha com timestamp, nível, evento, serviço, ambiente.
• Associe request_id a cada requisição HTTP. Retorne X-Request-ID para clientes.
• Inclua trace_id/span_id nos logs quando o tracing estiver habilitado. Salte entre logs e traces com um clique.
• Nunca registre segredos, tokens ou números completos de cartão. Permita campos específicos; limpe no Sentry before_send.
• Registre o contexto de negócios como campos, não como f-strings interpoladas. Permite a filtragem pela plataforma de logs.

B - Métricas

• Exponha métricas RED por template de rota. Taxa, erros, histogramas de duração.
• Mantenha a cardinalidade dos rótulos baixa. Sem IDs de usuário ou URLs brutos como rótulos.
• Escolha buckets de histograma em torno dos limites do SLO. p95/p99 visíveis no Grafana.
• Proteja o endpoint /metrics. Rede interna ou autenticação - não a internet pública.
• Adicione contadores de negócios com moderação. Apenas rótulos de enumeração pequenos (country, plan).

C - Traces e Erros

• Amostre traces em produção (ex: 5-20%). Bias para erros se o tail sampling estiver disponível.
• Instrumente requisições HTTP e boto3 de saída. Spans ausentes escondem latência downstream.
• Defina release do Sentry para o SHA do git. Identifique regressões por deploy.
• Alerta sobre novos problemas no Sentry em produção, não sobre contagens de eventos duplicados. Reduza a fadiga.
• Propague o contexto de trace através de filas. Cabeçalhos SQS/Kafka carregam traceparent.

D - Saúde e Deployments

• Separe /health/live e /health/ready. Dependências verificadas apenas na readiness.
• Falha na readiness retorna 503. O load balancer remove o pod sem loop de reinicialização em um "blip" no banco de dados.
• Sonda de inicialização para imports lentos de Python. Modelos de ML carregam preguiçosamente ou a sonda de inicialização tolera o atraso.
• Teste de fumaça (smoke test) de saúde no CI/CD. Bloqueie a promoção quando falhar.
• Dashboard por serviço: RPS, 5xx, latência p95, saturação. Página inicial padrão para plantão.

E - Processo e SLOs

• Defina SLOs com orçamentos de erro. Exemplo: 99.9% de disponibilidade mensal.
• Acione alertas com base na taxa de consumo do orçamento, não em um único "blip". Alertas multi-janela reduzem falsos alertas.
• Execute testes de carga antes de lançamentos importantes. Valide p99 sob pico esperado.
• Documente a propriedade da observabilidade por serviço. Quem é acionado, quais dashboards, quais runbooks.
• Revise o custo de observabilidade mensalmente. Remova métricas de alta cardinalidade não utilizadas e amostragem de trace de 100%.

FAQs

Relacionados

• Noções Básicas de Observabilidade - introdução aos três pilares
• Logging Estruturado - padrões structlog
• Métricas - instrumentação Prometheus
• Saúde e Readiness - design de sondas
• Boas Práticas de Deployment - sinais de rollout em produção

Versões de Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 em manutenção), 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+.