Gestion du signalement des erreurs

Lorsque vous faites fonctionner un site public, vous devriez toujours désactiver le réglage DEBUG. Cela va accélérer le serveur et évitera aussi que des utilisateurs mal intentionnés puissent voir des détails de l’application pouvant être révélés dans les pages d’erreur.

Cependant, lorsqu’un site fonctionne avec DEBUG réglé à False, vous ne verrez jamais les détails des erreurs générés par le site ; tout le monde voit les mêmes pages d’erreur publiques. Il est nécessaire de garder la trace des erreurs qui se produisent sur des sites en production, il est donc possible de configurer Django pour qu’il crée des rapports incluant les détails de ces erreurs.

Rapports par messagerie

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.

Note

Pour pouvoir envoyer des courriels, Django a besoin de connaître certains réglages indiquant comment se connecter à un serveur de messagerie. Au minimum, il faut indiquer EMAIL_HOST, et potentiellement EMAIL_HOST_USER et EMAIL_HOST_PASSWORD ; selon la configuration du serveur de messagerie, il peut toutefois être nécessaire de définir d’autres réglages. Consultez la documentation sur les réglages Django pour une liste complète des réglages liés à l’envoi de messages électroniques.

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.

Voir aussi

Les messages d’erreur de serveur sont envoyés par le moyen de l’infrastructure de journalisation, il est donc possible de personnaliser ce comportement en personnalisant la configuration de la journalisation.

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 :

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.

Note

BrokenLinkEmailsMiddleware doit apparaître avant tout autre intergiciel interceptant les erreurs 404, tel que LocaleMiddleware ou FlatpageFallbackMiddleware. Placez-le dans les premières lignes du réglage MIDDLEWARE.

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.

Voir aussi

Les erreurs 404 sont journalisées en utilisant l’infrastructure de journalisation. Par défaut, ces entrées de journal sont ignorées, mais vous pouvez les utiliser pour le signalement d’erreurs en écrivant un gestionnaire et en configurant la journalisation en conséquence.

Filtrage de rapports d’erreur

Avertissement

Le filtrage des données sensibles est un problème ardu, et il est quasiment impossible de garantir qu’aucune donnée sensible ne figurera dans un rapport d’erreur. Il faudrait donc limiter l’accès aux rapports d’erreurs aux membres de votre équipe dignes de confiance et éviter de transmettre ces rapports de manière non chiffrée par Internet (comme par exemple par messagerie électronique).

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

Avertissement

En raison de la machinerie nécessaire pour traverser la barrière synchrone/asynchrone, sync_to_async() et async_to_sync() ne sont pas compatibles avec sensitive_variables().

Si vous utilisez ces adaptateurs avec des variables sensibles, assurez-vous d’auditer les rapports d’exceptions et considérez l’écriture d’un filtre personnalisé si nécessaire.

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|HTTP_COOKIE", flags=re.IGNORECASE)
Changed in Django 4.2:

HTTP_COOKIE a été ajouté.

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

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

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

Voir aussi

Il est aussi imaginable de personnaliser les rapports d’erreurs en écrivant un middleware d’exception approprié. Dans ce cas, il est conseillé d’imiter la gestion d’erreur intégrée dans Django et de ne notifier les erreurs que dans le cas où DEBUG vaut False.

Back to Top