Gestion du signalement des erreurs¶

Erreurs de serveur¶

Lorsque DEBUG vaut False, Django envoie un courriel aux utilisateurs énumérés dans le réglage ADMINS à chaque fois que le code génère une exception non interceptée produisant une erreur interne de serveur (strictement parlant, pour toute réponse ayant un code d’état HTTP de 500 ou plus). Les administrateurs sont ainsi notifiés immédiatement à la suite de toute erreur. Les personnes dans ADMINS obtiennent une description de l’erreur, une trace Python complète ainsi que des détails sur la requête HTTP qui a causé l’erreur.

Par défaut, Django envoie ses messages avec l’adresse d’origine root@localhost. Toutefois, certains fournisseurs de messagerie rejettent tous les messages provenant de cette adresse. Pour utiliser une adresse d’expéditeur différente, modifiez le réglage SERVER_EMAIL.

Pour activer ce comportement, placez les adresses électroniques des destinataires dans le réglage ADMINS.

Erreurs 404¶

Django peut aussi être configuré pour envoyer des courriels pour des erreurs de lien cassé (erreurs 404 « page non trouvée »). Django envoie des courriels lors d’erreurs 404 si :

• DEBUG vaut False;
• Votre réglage MIDDLEWARE contient django.middleware.common.BrokenLinkEmailsMiddleware.

Si ces conditions sont remplies, Django envoie un courriel aux utilisateurs mentionnés dans le réglage MANAGERS chaque fois que le code signale une erreur 404 et que la requête possède une URL référente (« referer »). Il ne prend pas la peine d’envoyer un courriel pour une erreur 404 sans URL référente, car il s’agit généralement de personnes ayant mal saisi une adresse ou de robots Web défectueux. Il ignore aussi les erreurs 404 lorsque l’URL référente est la même que l’URL demandée, car ce comportement est aussi typique des robots Web défectueux.

Il est possible d’indiquer à Django de ne pas signaler certaines erreurs 404 en ajustant le réglage IGNORABLE_404_URLS. Celui-ci est une liste d’expressions régulières compilées. Par exemple :

import re
IGNORABLE_404_URLS = [
    re.compile(r'\.(php|cgi)$'),
    re.compile(r'^/phpmyadmin/'),
]

Dans cet exemple, une erreur 404 vers toute URL se terminant par .php ou .cgi ne sera pas signalée. Ni aucune URL commençant par /phpmyadmin/.

L’exemple suivant montre comment exclure certaines URL conventionnellement demandées par les navigateurs et les robots :

import re
IGNORABLE_404_URLS = [
    re.compile(r'^/apple-touch-icon.*\.png$'),
    re.compile(r'^/favicon\.ico$'),
    re.compile(r'^/robots\.txt$'),
]

(Notez qu’il s’agit d’expressions régulières, d’où la présence de la barre oblique inverse devant les points pour les échapper.)

Si vous souhaitez personnaliser davantage le comportement de django.middleware.common.BrokenLinkEmailsMiddleware (par exemple pour ignorer les requêtes en provenance de robots Web), vous devez créer une sous-classe et surcharger ses méthodes.

Filtrage des informations sensibles¶

Les rapports d’erreur sont vraiment utiles pour déboguer les erreurs, il est donc généralement utile de récolter le maximum d’informations à leur sujet. Par défaut, Django récolte une trace complète de l’exception levée, les variables locales de chaque contexte de trace et les attributs de l’objet HttpRequest.

Il peut cependant arriver que certains types d’information soient trop sensibles et qu’il n’est pas adéquat d’en conserver la trace, par exemple un mot de passe ou un numéro de carte de crédit. En plus d’exclure les réglages apparaissant comme sensibles selon ce qui est expliqué dans la documentation de DEBUG, Django offre donc un ensemble de fonctions décoratrices pour vous aider à contrôler les informations qui ne devraient pas apparaître dans les rapports d’erreur dans un environnement de production (c’est-à-dire quand DEBUG est défini à False) : sensitive_variables() et sensitive_post_parameters().

sensitive_variables(*variables)¶

Si une fonction (une vue ou toute autre fonction de rappel) de votre code utilise des variables locales susceptibles de contenir des informations sensibles, vous pouvez empêcher les valeurs de ces variables d’apparaître dans les rapports d’erreur en utilisant le décorateur sensitive_variables:

from django.views.decorators.debug import sensitive_variables

@sensitive_variables('user', 'pw', 'cc')
def process_info(user):
    pw = user.pass_word
    cc = user.credit_card_number
    name = user.name
    ...

Dans l’exemple ci-dessus, les valeurs des variables user, pw et cc seront masquées et remplacées par des étoiles (**********) dans les rapports d’erreur, tandis que la valeur de la variable name sera visible.

Pour masquer systématiquement toutes les variables locales d’une fonction dans les journaux d’erreurs, n’indiquez aucun paramètre au décorateur sensitive_variables:

@sensitive_variables()
def my_function():
    ...

Utilisation de plusieurs décorateurs

Si la variable que vous voulez masquer est également un paramètre de fonction (par ex. user dans l’exemple suivant) et si la fonction décorée possède plusieurs décorateurs, prenez soin de placer @sensitive_variables au sommet de la chaîne des décorateurs. De cette façon, le paramètre de fonction sera aussi masqué tout en passant par les autres décorateurs :

@sensitive_variables('user', 'pw', 'cc')
@some_decorator
@another_decorator
def process_info(user):
    ...

sensitive_post_parameters(*parameters)¶

Si l’une de vos vues reçoit un objet HttpRequest avec des paramètres POST susceptibles de contenir des informations sensibles, vous pouvez empêcher les valeurs de ces paramètres d’apparaître dans les rapports d’erreur en utilisant le décorateur sensitive_post_parameters:

from django.views.decorators.debug import sensitive_post_parameters

@sensitive_post_parameters('pass_word', 'credit_card_number')
def record_user_profile(request):
    UserProfile.create(
        user=request.user,
        password=request.POST['pass_word'],
        credit_card=request.POST['credit_card_number'],
        name=request.POST['name'],
    )
    ...

Dans l’exemple ci-dessus, les valeurs des paramètres POST pass_word et credit_card_number seront masquées et remplacées par des étoiles (**********) dans la représentation de la requête dans le rapport d’erreur, tandis que la valeur du paramètre name sera visible.

Pour masquer systématiquement tous les paramètres POST d’une requête dans les rapports d’erreur, n’indiquez aucun paramètre au décorateur sensitive_post_parameters:

@sensitive_post_parameters()
def my_view(request):
    ...

Tous les paramètres POST sont systématiquement masqués dans les rapports d’erreur pour certaines vues django.contrib.auth.views ( login, password_reset_confirm, password_change et add_view, ainsi que user_change_password dans l’administration de auth) pour empêcher la divulgation d’informations sensibles comme les mots de passe.

Rapports d’erreur personnalisés¶

Tout ce que font sensitive_variables() et sensitive_post_parameters(), c’est respectivement annoter la fonction décorée avec les noms des varaibles sensibles et annoter l’objet HttpRequest avec les noms des paramètres POST sensibles, afin que ces informations sensibles puissent être plus tard filtrées des rapports lorsqu’une erreur se produit. Le vrai filtrage est effectué par le filtre de rapport d’erreur par défaut de Django, django.views.debug.SafeExceptionReporterFilter. Ce filtre utilise les annotations des décorateurs pour remplacer les valeurs correspondantes par des étoiles (**********) au moment de la production du rapport d’erreur. Si vous souhaitez surcharger ou personnaliser ce comportement par défaut pour tout votre site, vous devez définir votre propre classe de filtre et indiquer à Django de l’utiliser par le moyen du réglage DEFAULT_EXCEPTION_REPORTER_FILTER:

DEFAULT_EXCEPTION_REPORTER_FILTER = 'path.to.your.CustomExceptionReporterFilter'

Vous pouvez aussi contrôler d’une manière plus fine le filtre qu’une vue données doit utiliser en définissant l’attribut exception_reporter_filter de l’objet HttpRequest.

def my_view(request):
    if request.user.is_authenticated:
        request.exception_reporter_filter = CustomExceptionReporterFilter()
    ...

Votre classe de filtre personnalisée doit hériter de django.views.debug.SafeExceptionReporterFilter et peut surcharger les attributs et méthodes suivantes :

class SafeExceptionReporterFilter¶

cleansed_substitute¶

La valeur textuelle qui remplacera les données sensibles. Par défaut, il remplace les valeurs des variables sensibles par des étoiles (**********).

hidden_settings¶

Un objet d’expression régulière compilée utilisé pour découvrir les valeurs de réglages et de request.META considérées comme sensibles. Équivaut par défaut à

import re

re.compile(r'API|TOKEN|KEY|SECRET|PASS|SIGNATURE', flags=re.IGNORECASE)

is_active(request)¶

Renvoie True pour activer le filtrage dans get_post_parameters() et get_traceback_frame_variables(). Par défaut, le filtre est actif si DEBUG vaut False. Notez que les valeurs sensibles de request.META sont toujours filtrées en compagnie des valeurs sensibles de réglages, tel que décrit dans la documentation de DEBUG.

get_post_parameters(request)¶

Renvoie le dictionnaire filtré des paramètres POST. Les valeurs des données sensibles sont remplacées par cleansed_substitute.

get_traceback_frame_variables(request, tb_frame)¶

Renvoie le dictionnaire filtré des variables locales pour la trace d’erreur donnée. Les valeurs des données sensibles sont remplacées par cleansed_substitute.

Si vous avez besoin de personnaliser les rapports d’erreur au-delà du filtrage en place, vous pouvez indiquer une classe personnalisée de rapport d’erreur en définissant le réglage DEFAULT_EXCEPTION_REPORTER:

DEFAULT_EXCEPTION_REPORTER = 'path.to.your.CustomExceptionReporter'

Le rapporteur d’exception est responsable de compiler les données du rapport d’exception et de le mettre en forme adéquatement en texte ou HTML (le rapporteur d’exception utilise DEFAULT_EXCEPTION_REPORTER_FILTER lors de la préparation des données du rapport d’exception).

Votre classe de rapporteur personnalisée doit hériter de django.views.debug.ExceptionReporter.

class ExceptionReporter¶

html_template_path¶

New in Django 3.2.

Propriété qui renvoie un chemin pathlib.Path représentant le chemin de système de fichiers absolu vers un gabarit pour le rendu de la représentation HTML de l’exception. Par défaut, c’est le gabarit fourni par Django qui est utilisé.

text_template_path¶

New in Django 3.2.

Propriété qui renvoie un chemin pathlib.Path représentant le chemin de système de fichiers absolu vers un gabarit pour le rendu de la représentation en texte pur de l’exception. Par défaut, c’est le gabarit fourni par Django qui est utilisé.

get_traceback_data()¶

Renvoie un dictionnaire contenant les informations de trace d’erreur.

Il s’agit du point d’extension principal pour la personnalisation des rapports d’exception, par exemple

from django.views.debug import ExceptionReporter


class CustomExceptionReporter(ExceptionReporter):
    def get_traceback_data(self):
        data = super().get_traceback_data()
        # ... remove/add something here ...
        return data

get_traceback_html()¶

Renvoie une version HTML du rapport d’exception.

Utilisé pour la version HTML de la page d’erreur HTTP 500 de débogage.

get_traceback_text()¶

Renvoie une version en texte brut du rapport d’exception.

Utilisé pour la version texte brut de la page d’erreur HTTP 500 de débogage et pour les rapports envoyés par courriel.

Comme avec la classe de filtre, vous pouvez contrôler quelle classe de rapporteur d’exception utiliser dans une vue donnée en définissant l’attribut exception_reporter_class de HttpRequest:

def my_view(request):
    if request.user.is_authenticated:
        request.exception_reporter_class = CustomExceptionReporter()
    ...