watchdog

Niveau intermédiaire

Activer le mode debug Drupal 10 et lire ce qu'il raconte

Drupal cache ses erreurs derrière un message générique. Les trois réglages à poser, où trouver le journal, et comment lire une erreur Drupal.

Drupal affiche « The website encountered an unexpected error. Please try again later. » Ce message ne dit rien, et c'est volontaire : en production, Drupal considère qu'une trace détaillée est une information à ne pas offrir au premier venu.

La trace existe pourtant, elle est complète, et elle est à trois réglages de vous.

Le premier réglage : montrer les erreurs

Dans sites/default/settings.php, ajoutez à la fin :

$config['system.logging']['error_level'] = 'verbose';

Quatre niveaux existent : hide, some, all et verbose. Seul verbose affiche la trace d'appel complète, la seule qui désigne le fichier fautif.

Le même réglage est accessible sans toucher au code, dans Configuration puis Développement puis Journalisation et erreurs. Passer par settings.php a un avantage décisif : cela fonctionne encore quand l'administration elle-même est inaccessible.

Le deuxième réglage : désactiver le cache

C'est la particularité de Drupal, et ce qui fait perdre le plus de temps à qui vient de WordPress. Drupal met en cache le rendu, le routeur et le conteneur de services. Une correction peut rester totalement invisible tant que le cache n'a pas été reconstruit.

Le fichier sites/development.services.yml :

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Puis, dans settings.php :

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['page'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

La règle à retenir. Sur Drupal, on ne conclut jamais qu'une correction n'a pas marché avant d'avoir reconstruit le cache. drush cr, ou le bouton Vider tous les caches dans Configuration puis Performances. Un site Drupal qui « ne prend pas en compte » une modification est presque toujours un cache, jamais une modification perdue.

Le troisième réglage : le journal

Voici ce que le laboratoire a relevé sur la panne ci-dessus, une fois error_level passé à verbose :

ID  Date           Type  Sévérité  Message
67  22/Aug 19:59   php   Erreur    Error: Call to undefined function
                                   creebs_lab_fonction_supprimee_par_une_maj()
                                   in lab_creebs_page_attachments()
                                   (line 5 of /opt/drupal/web/modules/custom/
                                   lab_creebs/lab_creebs.module)

Quatre informations en une entrée : la fonction absente, le hook qui l'appelait, le fichier et la ligne. Le dossier modules/custom/ suffit d'ailleurs à conclure : c'est un développement spécifique, pas un module tiers ni le cœur.

Drupal tient son propre journal, le watchdog, consultable dans Rapports puis Messages récents du journal, à l'adresse /admin/reports/dblog.

C'est plus riche qu'un fichier de log : chaque entrée porte son type, sa gravité, l'utilisateur concerné et l'adresse demandée. On peut filtrer par type, ce qui isole immédiatement le module coupable.

En ligne de commande :

drush watchdog:show --count=20
drush watchdog:show --severity=Error

Si le module dblog a été désactivé, ce qui arrive sur les sites à fort trafic parce qu'il écrit en base, les erreurs partent alors dans le journal PHP de l'hébergeur.

Lire une erreur Drupal

Une trace Drupal se lit dans cet ordre :

1. Le type d'exception. PluginNotFoundException désigne un module absent ou mal désinstallé. DatabaseExceptionWrapper désigne un schéma de base désynchronisé, typiquement une mise à jour interrompue. EntityStorageException désigne un problème de données.
2. Le chemin du fichier. Il vous dit tout de suite s'il s'agit du cœur (core/), d'un module contribué (modules/contrib/) ou d'un développement spécifique (modules/custom/).
3. La trace d'appel, à lire de bas en haut, pour comprendre qui a déclenché quoi.

Le réflexe qui économise une heure : si l'erreur est apparue après une mise à jour, vérifiez d'abord /update.php ou drush updb. Un schéma de base non mis à jour produit des erreurs qui semblent venir de partout.

Refermer

Repassez error_level à hide, retirez la ligne container_yamls, reconstruisez le cache.

Laisser un Drupal en mode verbeux en production, c'est afficher vos chemins de fichiers, vos versions de modules et parfois des fragments de requêtes SQL à quiconque provoque une erreur.

Si la trace désigne un module contribué que vous ne pouvez ni mettre à jour ni retirer, c'est le genre de situation où je passe une heure et où vous en passeriez cinq. Le diagnostic est gratuit.