Guías Técnicas

Django Debug Toolbar: La herramienta esencial para debugging y optimización

  ¿Qué es Django Debug Toolbar?

Django Debug Toolbar es una herramienta de debugging configurable que muestra información detallada sobre el rendimiento de tu aplicación Django. Proporciona paneles con datos sobre SQL queries, templates, cache, signals y mucho más.

  ¿Por qué usar Django Debug Toolbar?

  • Optimización de queries: Identifica queries SQL lentas o duplicadas
  • Debugging visual: Información detallada sin modificar código
  • Análisis de rendimiento: Tiempo de carga de templates y vistas
  • Monitoreo de cache: Verifica hits y misses del sistema de cache
  • Debugging de templates: Muestra qué templates se están usando

Instalación paso a paso

Paso 1: Instalar el paquete

bash 
pip install django-debug-toolbar

Paso 2: Agregar a INSTALLED_APPS

python 
# settings.py
INSTALLED_APPS = [
  'django.contrib.admin',
  'django.contrib.auth',
  'django.contrib.contenttypes',
  'django.contrib.sessions',
  'django.contrib.messages',
  'django.contrib.staticfiles',
  
  # Tus apps
  'miapp',
  
  # Debug Toolbar (solo en desarrollo)
  'debug_toolbar',
]

Paso 3: Configurar middleware

python 
# settings.py
MIDDLEWARE = [
  'debug_toolbar.middleware.DebugToolbarMiddleware',  # Debe ir al principio
  'django.middleware.security.SecurityMiddleware',
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.middleware.common.CommonMiddleware',
  'django.middleware.csrf.CsrfViewMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  'django.contrib.messages.middleware.MessageMiddleware',
  'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

Paso 4: Configurar IPs internas

Asegúrate de agregar tu IP local al listado de IPs internas para poder acceder al toolbar.

python 
# settings.py
# IPs que pueden ver el debug toolbar
INTERNAL_IPS = [
  '127.0.0.1',
  'localhost',
]

# Para Docker o entornos virtuales
import socket
hostname, _, ips = socket.gethostbyname_ex(socket.gethostname())
INTERNAL_IPS += [ip[: ip.rfind(".")] + ".1" for ip in ips]

Paso 5: Incluir URLs

Asegúrate de agregar las URLs del toolbar a tu archivo urls.py.

python 
# urls.py (proyecto principal)
from django.contrib import admin
from django.urls import path, include
from django.conf import settings

urlpatterns = [
  path('admin/', admin.site.urls),
  path('', include('miapp.urls')),
]

# Solo en modo DEBUG
if settings.DEBUG:
  import debug_toolbar
  urlpatterns = [
      path('__debug__/', include(debug_toolbar.urls)),
  ] + urlpatterns

Configuración avanzada

Personalizar paneles mostrados:

python 
# settings.py
DEBUG_TOOLBAR_PANELS = [
  'debug_toolbar.panels.history.HistoryPanel',
  'debug_toolbar.panels.versions.VersionsPanel',
  'debug_toolbar.panels.timer.TimerPanel',
  'debug_toolbar.panels.settings.SettingsPanel',
  'debug_toolbar.panels.headers.HeadersPanel',
  'debug_toolbar.panels.request.RequestPanel',
  'debug_toolbar.panels.sql.SQLPanel',
  'debug_toolbar.panels.staticfiles.StaticFilesPanel',
  'debug_toolbar.panels.templates.TemplatesPanel',
  'debug_toolbar.panels.cache.CachePanel',
  'debug_toolbar.panels.signals.SignalsPanel',
  'debug_toolbar.panels.logging.LoggingPanel',
  'debug_toolbar.panels.redirects.RedirectsPanel',
  'debug_toolbar.panels.profiling.ProfilingPanel',
]

Configuraciones adicionales:

python 
# settings.py
DEBUG_TOOLBAR_CONFIG = {
  # Mostrar toolbar solo si hay queries SQL
  'SHOW_TOOLBAR_CALLBACK': lambda request: settings.DEBUG,
  
  # Insertar toolbar automáticamente
  'INSERT_BEFORE': '</body>',
  
  # Renderizar toolbar en respuestas AJAX
  'RENDER_PANELS': True,
  
  # Número máximo de queries SQL a mostrar
  'SQL_WARNING_THRESHOLD': 20,
  
  # Ocultar en URLs específicas
  'SKIP_TEMPLATE_PREFIXES': (
      'django/forms/widgets/',
      'admin/',
  ),
}

Ejemplo práctico de uso

Ahora que tienes Django Debug Toolbar instalado y configurado, veamos un ejemplo práctico de cómo usarlo para identificar y solucionar problemas en tu aplicación.

Modelos de ejemplo:

python 
# models.py
from django.db import models

class Categoria(models.Model):
  nombre = models.CharField(max_length=100)
  descripcion = models.TextField()
  
  def __str__(self):
      return self.nombre

class Producto(models.Model):
  nombre = models.CharField(max_length=200)
  precio = models.DecimalField(max_digits=10, decimal_places=2)
  categoria = models.ForeignKey(Categoria, on_delete=models.CASCADE)
  fecha_creacion = models.DateTimeField(auto_now_add=True)
  
  def __str__(self):
      return self.nombre

class Pedido(models.Model):
  productos = models.ManyToManyField(Producto)
  fecha_pedido = models.DateTimeField(auto_now_add=True)
  total = models.DecimalField(max_digits=10, decimal_places=2)

Vista con problema de N+1:

python 
# views.py (PROBLEMA - Muchas queries)
from django.shortcuts import render
from .models import Producto

def lista_productos_lenta(request):
  productos = Producto.objects.all()  # 1 query
  
  # En el template: producto.categoria.nombre genera 1 query por producto
  return render(request, 'productos.html', {
      'productos': productos
  })

Vista optimizada:

python 
# views.py (OPTIMIZADA - Menos queries)
def lista_productos_rapida(request):
  # Solo 2 queries en total
  productos = Producto.objects.select_related('categoria').all()
  
  return render(request, 'productos.html', {
      'productos': productos
  })

Template de ejemplo:

html 
<!-- productos.html -->
<!DOCTYPE html>
<html>
<head>
  <title>Lista de Productos</title>
</head>
<body>
  <h1>Productos</h1>
  <div class="productos">
      {% for producto in productos %}
          <div class="producto">
              <h3>{{ producto.nombre }}</h3>
              <p>Precio: ${{ producto.precio }}</p>
              <p>Categoría: {{ producto.categoria.nombre }}</p>
              <small>Creado: {{ producto.fecha_creacion }}</small>
          </div>
      {% endfor %}
  </div>
</body>
</html>
  Paneles más útiles

  • SQL Panel: Muestra todas las queries ejecutadas, tiempo y duplicados
  • Timer Panel: Tiempo total de carga de la página
  • Templates Panel: Qué templates se renderizaron y su contexto
  • Cache Panel: Hits, misses y operaciones de cache
  • Request Panel: Headers, GET/POST data, cookies
  • Settings Panel: Configuraciones de Django activas

Identificando problemas comunes

1. Queries duplicadas:

python 
# PROBLEMA: Query N+1
def pedidos_con_productos(request):
  pedidos = Pedido.objects.all()  # 1 query
  # En template: pedido.productos.all() = N queries más
  return render(request, 'pedidos.html', {'pedidos': pedidos})

# SOLUCIÓN: Prefetch related
def pedidos_optimizados(request):
  pedidos = Pedido.objects.prefetch_related('productos').all()
  return render(request, 'pedidos.html', {'pedidos': pedidos})

2. Queries innecesarias:

python 
# PROBLEMA: Cargar datos no usados
def productos_basicos(request):
  # Carga todos los campos innecesariamente
  productos = Producto.objects.all()
  return render(request, 'productos_nombres.html', {'productos': productos})

# SOLUCIÓN: Solo campos necesarios
def productos_nombres_solo(request):
  productos = Producto.objects.only('nombre', 'precio')
  return render(request, 'productos_nombres.html', {'productos': productos})

Configuración para producción

  ¡IMPORTANTE!

NUNCA uses Django Debug Toolbar en producción. Solo debe estar activo en desarrollo.

Configuración segura:

python 
# settings.py
import os

# Solo instalar en desarrollo
if os.environ.get('DJANGO_ENV') == 'development':
  INSTALLED_APPS += ['debug_toolbar']
  MIDDLEWARE = ['debug_toolbar.middleware.DebugToolbarMiddleware'] + MIDDLEWARE
  
  INTERNAL_IPS = ['127.0.0.1', 'localhost']
  
  # URLs solo en desarrollo
  # En urls.py principal:
  if os.environ.get('DJANGO_ENV') == 'development':
      import debug_toolbar
      urlpatterns = [
          path('__debug__/', include(debug_toolbar.urls)),
      ] + urlpatterns

Variables de entorno:

bash 
# .env (desarrollo)
DJANGO_ENV=development
DEBUG=True

# .env (producción)
DJANGO_ENV=production
DEBUG=False
  Cómo interpretar los datos

  • SQL Panel: Busca queries duplicadas o que tomen >100ms
  • Timer Panel: Páginas >2 segundos necesitan optimización
  • Templates Panel: Muchos templates pueden indicar complejidad excesiva
  • Cache Panel: Bajo hit ratio indica problemas de cache

  Consejos de optimización

  1. Usa select_related() para ForeignKey y OneToOne
  2. Usa prefetch_related() para ManyToMany y reverse ForeignKey
  3. Implementa cache para queries costosas
  4. Usa only() para campos específicos
  5. Agrega índices a campos consultados frecuentemente

  Troubleshooting común

No aparece el toolbar:

  • Verifica que tu IP esté en INTERNAL_IPS
  • Asegúrate que DEBUG=True
  • Revisa que el middleware esté al principio

Errores de importación:

  • Instala con: pip install django-debug-toolbar
  • Verifica la versión de Django compatible