Depuración
Depurar es reducir la distancia entre lo que crees que hace el código y lo que hace. Las herramientas no piensan por ti: hacen visible ese hueco más rápido. Este capítulo las ordena por coste, de la más barata (leer el log) a la más cara (un depurador paso a paso).
En una línea
Sección titulada «En una línea»La herramienta correcta es la más barata que responda la pregunta que tienes.
El coste de mirar
Sección titulada «El coste de mirar»| Operación | Coste |
|---|---|
str(e) |
0.27 µs |
traceback.format_exc() |
205 µs |
python mediciones/07-06-10-servidor-seguridad-debug.py
Setecientas sesenta veces… y en la práctica más, porque format_exc recorre la pila y lee el código fuente para mostrar las líneas. Un except que registra la traza en cada error esperado convierte un servicio rápido en uno lento sin que nadie mire el log.
La regla: la traza se formatea para los errores inesperados, y los esperados se registran con su mensaje.
Las cinco herramientas
Sección titulada «Las cinco herramientas»| Herramienta | Cuándo | Coste |
|---|---|---|
print / log.info |
Sospecha concreta, local | Segundos |
breakpoint() |
Necesitas ver variables en un punto | Minutos |
Post-mortem (pdb.pm) |
Hay una traza de un fallo ya ocurrido | Minutos |
py-spy |
El proceso está en producción y no puedes pararlo | Segundos |
tracemalloc |
Es memoria, no lógica | Minutos |
breakpoint() y pdb
Sección titulada «breakpoint() y pdb»def calcular(x): breakpoint() # se detiene aquí return x * 2En la consola de pdb: p variable imprime, n avanza una línea, s entra en la función, c continúa, w muestra la pila, q sale. breakpoint() respeta PYTHONBREAKPOINT=0 desde 3.7, lo que permite desactivarlo sin tocar el código.
Post-mortem, sobre el último fallo:
import pdbtry: main()except Exception: pdb.post_mortem()Eso abre el depurador en el marco donde se lanzó la excepción, con las variables locales tal como estaban. Es la forma más rápida de entender un fallo que ya tienes delante.
py-spy: el que funciona en producción
Sección titulada «py-spy: el que funciona en producción»pdb necesita el proceso parado y una consola. py-spy lee la memoria del proceso desde fuera:
py-spy dump --pid 12345 # pilas de todos los hilospy-spy dump --pid 12345 --nonblocking # sin detener el proceso (puede dar una pila inconsistente)py-spy top --pid 12345 # qué funciones consumen CPUNo reinicia ni instrumenta el código. Por defecto, dump detiene el proceso unos instantes para leer una pila coherente (--nonblocking lo evita a costa de coherencia), y necesita permiso para leer la memoria de otro proceso: en Linux, ser root o tener ptrace permitido (kernel.yama.ptrace_scope, CAP_SYS_PTRACE en contenedores); en macOS, sudo. Es la herramienta para «el servicio está al 100 % de CPU y no sé por qué» y para «hay un bloqueo».
Desde Python 3.14 (PEP 768) el propio intérprete permite engancharse a un proceso en marcha: python -m pdb -p 12345 (el --help de 3.14.3 lo lista así: -m module | -p pid | pyfile) abre pdb sobre el proceso con ese PID, sin reiniciarlo. Requiere los mismos permisos y se puede desactivar con -X disable-remote-debug o PYTHON_DISABLE_REMOTE_DEBUG.
La trampa
Sección titulada «La trampa»El método
Sección titulada «El método»- Reproduce. Un caso que falla de forma consistente vale más que diez teorías.
- Reduce. Quita todo lo que no sea necesario para que falle. La mitad de las veces, el bug aparece al reducir.
- Formula una hipótesis concreta: «falla porque
xesNonecuando la lista está vacía». - Comprueba con la herramienta más barata que pueda refutarla.
- Arregla y añade un test que falle antes y pase después.
Cuándo no aplica
Sección titulada «Cuándo no aplica»- Si el error dice exactamente qué pasa. Lee el mensaje y la línea; la mitad de las «depuraciones» son no haber leído el traceback.
- Si el fallo es de configuración. Capítulo 02: se arregla leyendo el entorno, no con
pdb. - Si el fallo es intermitente y concurrente. Capítulo 07 de la Parte VI: no es depurable paso a paso, es de diseño.
Ejercicio
Sección titulada «Ejercicio»Un servicio en producción consume CPU al 100 % y las peticiones tardan. No puedes reiniciarlo ni añadir código. Describe los tres primeros pasos con las herramientas del capítulo.
Solución
-
py-spy top --pid: muestra en vivo qué funciones consumen CPU. Si aparece una función de tu código, ya está localizado; si aparecejson.dumpso una consulta, el problema es de volumen. -
py-spy dump --pid: si el top no basta, el dump da la pila completa de cada hilo. Ahí se ve si hay un bucle, una espera activa (unwhileconsleep(0)) o un hilo bloqueado. -
Métricas del servicio: latencia p99, número de peticiones por endpoint y tamaño de respuesta. El CPU al 100 % con latencia alta suele ser un endpoint que se llama mucho o devuelve demasiado.
Con eso, la decisión: si el culpable es una función tuya, se corrige en el siguiente despliegue; si es volumen, la solución es caché, paginación o un límite de tasa.
Lo que no se hace: matar el proceso para «ver si se arregla». Se pierde la evidencia y el problema vuelve.
Referencias
Sección titulada «Referencias»- Ramalho, L. Fluent Python, 2ª ed. Capítulo 18.
- CPython 3.13:
Lib/pdb.py,Lib/traceback.py. - Mediciones:
mediciones/07-06-10-servidor-seguridad-debug.py.
Capítulos relacionados
Sección titulada «Capítulos relacionados»- 05 · Errores: cómo se propaga lo que vas a depurar.
- 04 · Logging: la primera herramienta, la más barata.
- 06 · Rendimiento en servidor: qué medir antes de depurar.