🔧 Django Debug Toolbar – Guide Approfondi

Les Panneaux Essentiels

La barre d'outils est composée de "Panneaux". Voici les plus importants :

Quand l'utiliser ?

TOUJOURS en environnement de **développement** (DEBUG = True).

C'est le premier package que vous devriez installer après django lui-même.

NE JAMAIS l'utiliser en Production

La DjDT ne doit **JAMAIS** être activée en production (DEBUG = False).

• Faille de sécurité massive : Elle expose toute votre configuration, votre code source et vos requêtes SQL à n'importe quel visiteur.
• Consommation de ressources : Elle ajoute une surcharge significative à chaque requête pour collecter les informations de débogage.

La configuration correcte (expliquée dans l'onglet suivant) garantit qu'elle ne s'exécute que lorsque DEBUG est à True et pour des IPs spécifiques.

Alternatives & Compléments

1. Django-Silk

• Approche : Un outil de **profilage** pour les APIs (DRF). Il ne s'affiche pas sur la page, mais fournit une interface d'administration pour inspecter les requêtes API, leur temps de réponse, et les requêtes SQL associées.
• Complément : DjDT est pour les pages rendues par Django (HTML). Silk est pour les endpoints d'API (JSON).

2. Sentry (Monitoring de Production)

• Approche : Service de monitoring d'erreurs et de performance pour la **production**.
• Complément : DjDT vous aide à trouver les problèmes en *développement*. Sentry vous alerte des problèmes et des goulots d'étranglement qui surviennent en *production* (ex: "cette requête SQL est soudainement lente pour les utilisateurs réels").

3. Logging Django natif

• Approche : Configurer le module logging de Python pour écrire les requêtes SQL dans la console ou un fichier.

'loggers': {
    'django.db.backends': {
        'level': 'DEBUG',
        'handlers': ['console'],
    },
}

• Inconvénient : Extrêmement verbeux, difficile à lire, n'a pas le contexte de DjDT. Utile pour un script, pas pour un serveur web.

Le Piège n°1 : La barre ne s'affiche pas !

Vous avez tout installé, DEBUG=True, mais la barre n'apparaît pas. Pourquoi ?

Par sécurité, DjDT ne s'affiche que pour les adresses IP listées dans INTERNAL_IPS. Par défaut, cette liste est vide.

Solution : Ajouter 127.0.0.1

Ajoutez ceci à votre settings.py (ou settings/dev.py) :

# settings.py
INTERNAL_IPS = [
    "127.0.0.1",
]

127.0.0.1 est l'adresse de "localhost". Si vous développez localement, cela résoudra 99% des problèmes d'affichage.

Configuration pour Docker / VM / WSL2

Si votre serveur Django tourne dans un conteneur Docker (ou une VM, ou WSL2) et que vous y accédez depuis votre machine hôte, 127.0.0.1 ne fonctionnera pas.

Le serveur verra l'adresse IP de votre "vraie" machine (ex: 172.17.0.1). Le plus simple est d'utiliser une astuce qui détecte l'IP de la requête.

Configuration Dynamique (Recommandée pour Docker)

Utilisez ce snippet dans settings.py. Il autorise dynamiquement l'IP du client si DEBUG=True.

# settings.py

if DEBUG:
    import socket  # only if DEBUG
    
    # Récupère l'IP interne de la machine hôte Docker
    hostname, _, ips = socket.gethostbyname_ex(socket.gethostname())
    INTERNAL_IPS = [ip[: ip.rfind(".")] + ".1" for ip in ips] + [
        "127.0.0.1",
        "10.0.2.2", # Pour Vagrant/VM
    ]

Alternative : SHOW_TOOLBAR_CALLBACK

Si la détection d'IP est trop compliquée, vous pouvez forcer l'affichage (EN DEV UNIQUEMENT) en ajoutant ceci à settings.py :

# settings.py
DEBUG_TOOLBAR_CONFIG = {
    "SHOW_TOOLBAR_CALLBACK": lambda request: True,
}

Cela désactive la vérification d'IP et affiche la barre pour tout le monde (tant que DEBUG=True).

Vérification

Pour vérifier que tout fonctionne :

1. Lancez python manage.py runserver.
2. Ouvrez votre navigateur sur http://127.0.0.1:8000/.
3. Vous devriez voir un petit onglet "DjDT" sur le côté droit de votre page.
4. Si vous utilisez l'admin Django, allez sur /admin/, la barre doit aussi y apparaître.

La barre n'apparaît toujours pas ?

• Vérifiez que DEBUG = True.
• Vérifiez que vous avez bien ajouté "127.0.0.1" à INTERNAL_IPS.
• Vérifiez que votre HTML est bien présent dans votre template (la barre s'injecte avant ).
• Videz le cache de votre navigateur.

Cas Pratique : Le Problème N+1

[...Contenu détaillé : Qu'est-ce qu'un N+1 ? 1 requête pour la liste (N articles) + N requêtes pour les auteurs (1 par article)...]

[...Exemple de vue et template qui causent un N+1...]
# views.py
articles = Article.objects.all()

# template.html
{% for article in articles %}
     par 
{% endfor %}

[...Montrer une capture d'écran de la DjDT affichant 101 requêtes...]

Correction (ForeignKey) : select_related

[...Contenu détaillé : Utiliser `select_related` pour les relations ForeignKey (OneToOne, ForeignKey). Il fait un JOIN SQL...]

[...Exemple corrigé...]
# views.py
articles = Article.objects.select_related('author').all()

[...Montrer une capture de la DjDT avec 1 seule requête...]

Correction (M2M) : prefetch_related

[...Contenu détaillé : Utiliser `prefetch_related` pour les relations ManyToMany. Il fait 2 requêtes (pas de JOIN) mais est plus efficace...]

[...Exemple avec des Tags M2M...]
articles = Article.objects.prefetch_related('tags').all()

Analyser une requête avec EXPLAIN

[...Contenu détaillé : Cliquer sur le bouton "EXPLAIN" pour voir le plan d'exécution de la BDD et vérifier si les index sont utilisés...]

Contexte (Variables)

[...Contenu détaillé : Le "débogueur" n°1. Inspecter le contenu exact de ``, `AnonymousUser`, `` etc., tel que vu par le template...]

Context Processors

[...Contenu détaillé : Voir quelles variables globales sont ajoutées par les processors (ex: `request`, `perms`)...]

Panel Headers

[...Contenu détaillé : Inspecter les en-têtes de Requête et de Réponse. Utile pour vérifier les cookies, CSRF token, Content-Type...]

Lire le Panel

[...Contenu détaillé : Voir les `cache.get`, `cache.set`, les "hits" (succès) et "misses" (échecs), et le temps pris par chaque opération de cache...]

Lire le Panel

[...Contenu détaillé : Voir le signal émis, les arguments (`sender`, `instance`), et les "receivers" (fonctions) qui ont été appelés...]

Panneaux Tiers

[...Contenu détaillé : Ajouter des panneaux utiles comme `ddt-request-history` (historique des requêtes) ou `django-debug-toolbar-template-profiler` (profilage des templates)...]

DEBUG_TOOLBAR_CONFIG

[...Contenu détaillé : Autres options utiles comme `SHOW_TOOLBAR_CALLBACK` (déjà vu), `RESULTS_CACHE_SIZE`, `MAX_SQL_QUERIES`...]