Observabilidade em Python

Instrumente aplicações Python com logs estruturados, métricas e traces. Quando algo falhar em produção, você precisa responder "o quê, onde e por quê" sem implantar novo código.

Quando Usar Esta Habilidade

• Adicionar logging estruturado a aplicações
• Implementar coleta de métricas com Prometheus
• Configurar tracing distribuído entre serviços
• Propagar IDs de correlação através de cadeias de requisição
• Depurar problemas em produção
• Construir dashboards de observabilidade

Conceitos Principais

1. Logging Estruturado

Emita logs como JSON com campos consistentes para ambientes de produção. Logs legíveis por máquina permitem consultas e alertas poderosos. Para desenvolvimento local, considere formatos legíveis por humanos.

2. Os Quatro Sinais de Ouro

Monitore latência, tráfego, erros e saturação para cada limite de serviço.

3. IDs de Correlação

Passe um ID único por todos os logs e spans para uma única requisição, permitindo tracing de ponta a ponta.

4. Cardinalidade Limitada

Mantenha os valores dos rótulos de métricas limitados. Rótulos ilimitados (como IDs de usuário) explodem os custos de armazenamento.

Início Rápido

import structlog

structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer(),
    ],
)

logger = structlog.get_logger()
logger.info("Request processed", user_id="123", duration_ms=45)

Padrões Fundamentais

Padrão 1: Logging Estruturado com Structlog

Configure o structlog para saída JSON com campos consistentes.

import logging
import structlog

def configure_logging(log_level: str = "INFO") -> None:
    """Configure structured logging for the application."""
    structlog.configure(
        processors=[
            structlog.contextvars.merge_contextvars,
            structlog.processors.add_log_level,
            structlog.processors.TimeStamper(fmt="iso"),
            structlog.processors.StackInfoRenderer(),
            structlog.processors.format_exc_info,
            structlog.processors.JSONRenderer(),
        ],
        wrapper_class=structlog.make_filtering_bound_logger(
            getattr(logging, log_level.upper())
        ),
        context_class=dict,
        logger_factory=structlog.PrintLoggerFactory(),
        cache_logger_on_first_use=True,
    )

# Initialize at application startup
configure_logging("INFO")
logger = structlog.get_logger()

Padrão 2: Campos de Log Consistentes

Cada entrada de log deve incluir campos padrão para filtragem e correlação.

import structlog
from contextvars import ContextVar

# Store correlation ID in context
correlation_id: ContextVar[str] = ContextVar("correlation_id", default="")

logger = structlog.get_logger()

def process_request(request: Request) -> Response:
    """Process request with structured logging."""
    logger.info(
        "Request received",
        correlation_id=correlation_id.get(),
        method=request.method,
        path=request.path,
        user_id=request.user_id,
    )

    try:
        result = handle_request(request)
        logger.info(
            "Request completed",
            correlation_id=correlation_id.get(),
            status_code=200,
            duration_ms=elapsed,
        )
        return result
    except Exception as e:
        logger.error(
            "Request failed",
            correlation_id=correlation_id.get(),
            error_type=type(e).__name__,
            error_message=str(e),
        )
        raise

Padrão 3: Níveis Semânticos de Log

Use níveis de log consistentemente em toda a aplicação.

# DEBUG: Detailed internal information
logger.debug("Cache lookup", key=cache_key, hit=cache_hit)

# INFO: Normal operational events
logger.info("Order created", order_id=order.id, total=order.total)

# WARNING: Abnormal but handled situations
logger.warning(
    "Rate limit approaching",
    current_rate=950,
    limit=1000,
    reset_seconds=30,
)

# ERROR: Failures requiring investigation
logger.error(
    "Payment processing failed",
    order_id=order.id,
    error=str(e),
    payment_provider="stripe",
)

…