Depuración en Producción

Los errores en producción difieren de los fallos locales: la forma del tráfico, el volumen de datos y la configuración del entorno ocultan problemas que tu portátil nunca ve. Los logs estructurados, las trazas distribuidas y el perfilado seguro en vivo cierran esa brecha sin reinicios arriesgados.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

import logging
import structlog
 
structlog.configure(
    processors=[
        structlog.contextvars.merge_contextvars,
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer(),
    ],
    wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
)
log = structlog.get_logger()
 
def handle_request(request_id: str, trace_id: str, tenant: str) -> None:
    structlog.contextvars.bind_contextvars(
        request_id=request_id, trace_id=trace_id, tenant=tenant
    )
    log.info("order_created", order_id="ord_123")

# Muestra de pila en vivo (sin reinicio, necesita ptrace o CAP_SYS_PTRACE)
py-spy top --pid $(pgrep -f "gunicorn.*api:app")
py-spy dump --pid <pid> --lines 50

Cuándo recurrir a esto:

• Picos en la tasa de errores sin una correlación obvia con un despliegue
• La latencia aumenta pero la CPU parece inactiva (GIL o espera de I/O)
• El problema aparece solo para un inquilino o región
• La reproducción local falla después de igualar la versión de Python y las variables de entorno

Ejemplo de Trabajo

"""prod_debug_helpers.py - kit de herramientas mínimo para correlacionar evidencia de producción."""
from __future__ import annotations
 
import json
import os
import sys
import time
from contextlib import contextmanager
from dataclasses import dataclass, asdict
 
import structlog
 
structlog.configure(
    processors=[
        structlog.contextvars.merge_contextvars,
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer(),
    ],
)
log = structlog.get_logger()
 
 
@dataclass(frozen=True)
class DeployContext:
    git_sha: str
    python_version: str
    service: str
 
 
def deploy_context() -> DeployContext:
    return DeployContext(
        git_sha=os.getenv("GIT_SHA", "unknown"),
        python_version=sys.version.split()[0],
        service=os.getenv("SERVICE_NAME", "api"),
    )
 
 
@contextmanager
def request_scope(request_id: str, trace_id: str, **extra: str):
    structlog.contextvars.bind_contextvars(
        request_id=request_id,
        trace_id=trace_id,
        **extra,
        **asdict(deploy_context()),
    )
    start = time.perf_counter()
    try:
        yield
    finally:
        log.info("request_finished", duration_ms=(time.perf_counter() - start) * 1000)
 
 
def simulate_slow_path() -> None:
    with request_scope("req-9f2", "trace-abc", tenant="acme"):
        log.info("cache_miss", key="user:42")
        time.sleep(0.05)  # sustituye a la ida y vuelta de la base de datos
        log.warning("downstream_retry", attempt=2, service="billing")
 
 
if __name__ == "__main__":
    simulate_slow_path()
    print("Filtrar logs de producción: trace_id=trace-abc AND level>=warning")

Lo que esto demuestra:

• Los logs JSON llevan request_id, trace_id y metadatos de despliegue en cada línea
• Los gestores de contexto vinculan el ámbito una vez por solicitud en lugar de pasar kwargs por todas partes
• La duración y los reintentos descendentes aparecen en el mismo flujo de logs que los eventos de negocio
• El SHA de despliegue en los logs vincula rápidamente los incidentes con los artefactos de lanzamiento

Inmersión Profunda

Cómo Funciona

• Logging estructurado - Campos clave-valor indexados en Loki, CloudWatch o Datadog; buscar texto plano a escala falla.
• Propagación de trazas - OpenTelemetry inyecta trace_id en los logs cuando el SDK se configura con un puente de logging.
• py-spy - Muestrea pilas de CPython externamente; seguro en workers de Gunicorn/Uvicorn bajo carga.
• Reproducción de solo lectura - Copia cargas útiles anonimizadas de producción y estado de feature flags en staging antes de los cambios de código.
• Línea de tiempo de evidencia - Alinea logs, métricas y anotaciones de despliegue en una ventana UTC.

Lista de Señales de Producción

Notas de Python

# Habilita faulthandler al inicio para cuelgues nativos
import faulthandler
faulthandler.enable()
 
# Depuración temporal en un solo pod (nunca cometer)
import logging
logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)

Trampas

• Reiniciar pods antes de capturar logs - Pierdes el estado en memoria y la evidencia de la pila. Solución: Captura logs, py-spy dump y métricas de heap primero.
• IDs de correlación faltantes - Miles de errores idénticos no se pueden buscar. Solución: Requiere request_id/trace_id en el middleware antes de que se ejecuten los manejadores.
• Depurar con nivel DEBUG globalmente - El volumen de logs explota y se filtran PII. Solución: Sube el nivel en un pod o usa muestreo dinámico.
• Asumir que local == prod - Diferentes PYTHONHASHSEED, locale o pines de dependencias cambian el comportamiento. Solución: Coincide con el digest de la imagen y el entorno en un entorno de preparación.
• Bloquear el bucle de eventos en aplicaciones asíncronas - Las llamadas síncronas a ORM detienen todas las solicitudes; la CPU parece baja. Solución: Comprueba las líneas de tiempo de las trazas en busca de segmentos síncronos largos; mueve las I/O fuera del bucle.

Alternativas

Preguntas Frecuentes

Relacionado

• Playbooks de Respuesta a Incidentes - roles y severidad de los primeros 15 minutos
• Modos Comunes de Fallo en Producción - patrones de interrupción específicos de Python
• Runbooks de Rollback y Recuperación - estabiliza bajo presión
• Logging Estructurado - configuración de logs JSON
• Trazas Distribuidas - propagación de trazas

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 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+, y uv 0.6+.