Saltearse al contenido

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).

La herramienta correcta es la más barata que responda la pregunta que tienes.

Capturar y formatear un error
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.

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
def calcular(x):
breakpoint() # se detiene aquí
return x * 2

En 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 pdb
try:
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.

pdb necesita el proceso parado y una consola. py-spy lee la memoria del proceso desde fuera:

Ventana de terminal
py-spy dump --pid 12345 # pilas de todos los hilos
py-spy dump --pid 12345 --nonblocking # sin detener el proceso (puede dar una pila inconsistente)
py-spy top --pid 12345 # qué funciones consumen CPU

No 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.

  1. Reproduce. Un caso que falla de forma consistente vale más que diez teorías.
  2. Reduce. Quita todo lo que no sea necesario para que falle. La mitad de las veces, el bug aparece al reducir.
  3. Formula una hipótesis concreta: «falla porque x es None cuando la lista está vacía».
  4. Comprueba con la herramienta más barata que pueda refutarla.
  5. Arregla y añade un test que falle antes y pase después.
  • 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.

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
  1. py-spy top --pid: muestra en vivo qué funciones consumen CPU. Si aparece una función de tu código, ya está localizado; si aparece json.dumps o una consulta, el problema es de volumen.

  2. 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 (un while con sleep(0)) o un hilo bloqueado.

  3. 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.

  • 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.
  • 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.