Manuel:Comment déboguer

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:How to debug and the translation is 96% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Nederlands • ‎dansk • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어

Cette page donne une introduction de base au débogage du logiciel MediaWiki.

Une des premières choses que vous remarquerez est que "echo" ne fonctionne généralement pas ; Cela fait partie de la conception générale.

Erreurs PHP

Pour voir les erreurs PHP, ajoutez ceci au bas de LocalSettings.php  :

error_reporting( -1 );
ini_set( 'display_errors', 1 );

Ou mettez-le dans php.ini  :

error_reporting = E_ALL
display_errors = On

Ou déclarer dans .htaccess:

php_value error_reporting -1
php_flag display_errors On

Cela entraînera l'affichage des erreurs PHP sur la page. Cela pourrait aider les attaquants pour trouver un chemin dans votre serveur, alors désactivez-le à nouveau lorsque vous avez trouvé le problème.

Notez que des erreurs fatales PHP peuvent se produire avant que les lignes ci-dessus ne se soient exécutées, ou peuvent empêcher leur affichage. Les erreurs fatales de PHP sont généralement enregistrées dans le journal des erreurs d'Apache - vérifiez le paramètre error_log dans php.ini (ou utilisez phpinfo())

Il existe plusieurs options de configuration pour faciliter le débogage. Celles qui suivent sont toutesfalse par défaut. Activez-les en les mettant à true dans votre LocalSettings.php :

  • $wgShowExceptionDetails Activer plus de détails (comme une trace de pile) à afficher sur la page "Erreur fatale".
  • $wgDebugToolbar Affiche une barre d'outils sur la page avec le profilage, les messages de journal et plus encore.
  • $wgShowDebug Ajoute la partie "log messages" de wgDebugToolbar comme une liste brute à la page.
  • $wgDevelopmentWarnings MediaWiki lancera des avis pour certaines conditions d'erreur possible et pour les fonctions obsolètes.

Activation de display_startup_errors

Certains fournisseurs désactivent display_startup_errors, ce qui masque les erreurs même si vous relancez le niveau error_reporting. Activer le programme est trop tard ! Au lieu de cela, vous devrez créer un fichier wrapper autour de votre fichier. Dans le cas de MediaWiki vous pouvez simplement ajouter ceci au-dessus de mediawiki/index.php :

--- index.php
    error_reporting( -1 );
    ini_set( 'display_startup_errors', 1 );
    ini_set( 'display_errors', 1 );

Dans d'autres environnements :

--- myTestFile.php
    error_reporting( -1 );
    ini_set( 'display_startup_errors', 1 );
    ini_set( 'display_errors', 1 );
    require 'your_file.php';


Erreurs SQL

Pour afficher les erreurs SQL dans les messages d'erreur au lieu de "(SQL query hidden)", ajoutez ce qui suit à LocalSettings.php:

$wgDebugDumpSql = true;

Vous pouvez également activer backtrace sur erreur SQL en définissant $wgShowDBErrorBacktrace :

$wgShowSQLErrors = true;
$wgShowDBErrorBacktrace = true;


Débogage en profondeur

Débogueur

For the most common setup (using MediaWiki-Vagrant and PhpStorm) see Manual:How to debug/with MediaWiki-Vagrant and PHPStorm .

Zend

Si vous utilisez l'interpréteur PHP Zend, vous pouvez déboguer votre code avec XDebug. MediaWiki-Vagrant a construit dans les paramètres pour cela. Si vous n'utilisez pas MediaWiki-Vagrant, mais que votre configuration est similaire, vous pouvez réutiliser ces valeurs. Dans certains cas (par exemple, à cause d'un pare-feu), vous devrez peut-être utiliser l'IDE sur la même machine que le serveur Web. Dans ce cas, vous pouvez simplement définir :

xdebug.remote_enable = 1
xdebug.remote_host = 'localhost'

Si vous utilisez cette configuration, vous risquez de rencontrer un problème si HHVM écoute également sur la machine. Les deux XDebug et HHVM utilisent le port 9000 par défaut. Toutefois, vous pouvez changer cela pour XDebug (et pour de nombreux clients). Pour le côté XDebug, utilisez :

xdebug.remote_port = 9001

N'oubliez pas que si vous le modifiez pour XDebug, vous devez également le modifier pour votre IDE.

Voir la documentation XDebug pour plus d'informations.

Pour déboguer un script de ligne de commande (par exemple PHPUnit ou un script de maintenance) sur MediaWiki-Vagrant, utilisez :

xdebug_on; php5 /vagrant/mediawiki/tests/phpunit/phpunit.php --wiki=wiki /vagrant/mediawiki/extensions/Extension/tests/phpunit/SomeTest.php; xdebug_off

Ajuster le script, les paramètres et l'hôte distant (ça devrait être l'adresse IP de l'ordinateur où votre IP est, 10.0.2.2 devrait fonctionner pour MediaWiki-Vagrant) est nécessaire.

HHVM

Si vous utilisez l'exécutable PHP HHVM, vous pouvez déboguer votre code avec le débogueur et le serveur de débogage CLI intégrés.(XDebug fonctionne également habituellement, mais est moins fiable que sur Zend.) Ce débogueur est vaguement similaire à GDB.

Pour que le débogueur cli s'attache aux requêtes Web, le paramètre hhvm.debug.enable_debugger doit être activé. Ceci est activé par défaut sur l'environnement de développement mediawiki-vagrant.

Avec ceci activé le processus est :

  $ hhvm -m debug --debug-host localhost --debug-port 8089
  localhost> machine list
  machine list
    1     vagrant's default sandbox at /vagrant/www/
    2     __builtin's default sandbox at /
  localhost> machine attach 2
  machine attach 2
  Attaching to __builtin's default sandbox at / and pre-loading, please wait...
  localhost> break MediaWiki::run()
  break MediaWiki::run()
  Breakpoint 1 set upon entering MediaWiki::run()
  localhost> continue
  continue

La machine attach 2 est nécessaire. Il peut ne pas toujours être la machine 2, mais elle sera toujours celle identifiée comme "__builtin's default sandbox at /". Cela n'est vrai que pour les configurations qui passent un DOCUMENT_ROOT sur fastcgi à hhvm (comme MediaWiki-Vagrant et wmf production), les configurations alternatives peuvent varier.

À ce stade, la prochaine requête Web qui entre dans MediaWiki::run() (tous) se brisera et vous mettra sur une invite de commande :

       Breakpoint 1 reached at MediaWiki::run() on line 450 of /vagrant/mediawiki/includes/MediaWiki.php
        449            try {
        450*                   $this->checkMaxLag();
        451                    try {
       localhost>

Le débogueur HHVM CLI dispose d'un excellent système d'aide, par exemple essayez help break pour plus de détails sur la syntaxe de choix des points de rupture.

Enregistrement

Pour plus de détails, vous devez faire un profil et consigner les erreurs.

Les instructions ci-dessous ne sont valables que pour la configuration par défaut. Si vous modifiez $wgMWLoggerDefaultSpi , par exemple, activez le rôle psr3 sur une case vagrant , ces paramètres seront probablement ignorés.

Configuration d'un fichier journal de débogage

Pour enregistrer les erreurs et les informations de débogage dans un journal, ajoutez $wgDebugLogFile au fichier LocalSettings.php. Modifiez la valeur vers un fichier texte où vous souhaitez enregistrer la sortie de trace de débogage.

Le logiciel MediaWiki doit avoir des permissions de votre système d'exploitation pour créer et écrire dans ce fichier, par exemple dans une installation par défaut Ubuntu, il s'exécute en tant qu'utilisateur et groupe www-data : www-data. Voici un exemple de réglage:

/**
 * The debug log file must never be publicly accessible because it
 * contains private data. But ensure that the directory is writeable by the
 * PHP script running within your Web server.
 * The filename is with the database name of the wiki.
 */
$wgDebugLogFile = "/var/log/mediawiki/debug-{$wgDBname}.log";

Ce fichier contiendra beaucoup d'informations de débogage à partir du noyau MediaWiki et des extensions. Certains sous-systèmes écrivent des journaux personnalisés, voir #Création d'un fichier journal personnalisé pour capturer leur sortie.

Le débogage Database transaction lifecycle peut être activé pour certaines bases de données avec $wgDebugDBTransactions .

Avertissement Avertissement : Le fichier journal de débogage peut contenir des informations privées telles que les informations de connexion, les cookies de session, et les valeurs des formulaires soumis. Si ces informations sont accessibles au public, les attaquants peuvent l'utiliser pour pirater et compromettre votre compte d'ordinateur et d'utilisateur. Si vous avez besoin de partager un journal de débogage à des fins de diagnostic, accéder au wiki sans être connecté, et retirer du journal de débogage des lignes COOKIE, et ne pas saisir toute tentative de connexion.

Création d'un fichier journal personnalisé

Pour créer un fichier journal personnalisé qui ne contient que vos instructions de débogage spécifiques, utilisez la fonction wfErrorLog() (L'utilisation de wfErrorLog a été déconseillée dans MediaWiki 1.25). Cette fonction prend deux arguments, la chaîne de texte à consigner et le chemin d'accès au fichier journal :

wfErrorLog( "An error occurred.\n", '/var/log/mediawiki/my-custom-debug.log' );

Création de groupes de journaux personnalisés

Si vous effectuez le débogage de plusieurs composants différents, il peut être utile de diriger certains groupes de journaux à écrire dans un fichier distinct. Voir $wgDebugLogGroups pour plus d'informations.

Pour configurer des groupes de journaux personnalisés, utilisez les éléments suivants pour LocalSettings.php :

/**
 * The debug log file should not be publicly accessible if it is used, as it
 * may contain private data. However, it must be in a directory to which PHP run
 * within your web server can write.
 *
 * Contrary to wgDebugLogFile, it is not necessary to include a wiki-id in these log file names
 * if you have multiple wikis. These log entries are prefixed with sufficient information to
 * identify the relevant wiki (web server hostname and wiki-id).
 */

// Groups from MediaWiki core
$wgDBerrorLog = '/var/log/mediawiki/dberror.log';
$wgRateLimitLog = '/var/log/mediawiki/ratelimit.log';
$wgDebugLogGroups = array(
	'resourceloader' => '/var/log/mediawiki/resourceloader.log',
	'exception' => '/var/log/mediawiki/exception.log',
	'error' => '/var/log/mediawiki/error.log',
	#'exception-json' => '/var/log/mediawiki/exception.json',

	// Extra log groups from your extension
	#'myextension' => '/var/log/mediawiki/myextension.log',
	#'somegroup' => '/var/log/mediawiki/somegroup.log',
);

Pour vous connecter à l'un de ces groupes, appelez wfDebugLog comme ceci :

if ( $module->hasFailed ) {
    wfDebugLog( 'myextension', "Something is not right, module {$module->name} failed." );
}
Si vous avez bien suivi les instructions ci-dessus mais que rien n'est écrit dans vos fichiers de journalisation, et si votre système utilise SELinux, jetez un coup d’œil à la section logging sur la page SELinux pour contourner ce problème de contexte SELinux.
L'écriture de fichiers journaux dans le répertoire /tmp peut ne pas générer de fichier journal, même si le répertoire /tmp est supposé être accessible par écrit à quiconque. Cela peut se produire si votre système utilise l'une des fonctionnalités systemd qui créent un répertoire virtuel /tmp pour ce processus. Si c'est le cas, configurez votre fichier journal à écrire dans un répertoire différent, comme /var/log/mediawiki

Enregistrement structuré

Version de MediaWiki : 1.25

La journalisation structurée vous permet d'inclure des champs dans vos enregistrements. Voir Structured logging pour plus d'informations.

Vous aurez besoin de configurer un meilleur enregistreur pour collecter les champs supplémentaires, par exemple Monolog.


Statistiques

L'enregistrement avancé côté client peut être effectué avec l'extension EventLogging, ce qui nécessite une configuration complexe et une inspection minutieuse des problèmes de confidentialité.

Le comptage simple de certains types d'événements est possible (depuis MediaWiki 1.25) en utilisant StatsD. StatsD propose des compteurs, des jauges, des compteurs et des mesures de temps.

Exemple d'utilisation :

$stats = $context->getStats();
$stats->increment( 'resourceloader.cache.hits' );
$stats->timing( 'resourceloader.cache.rtt', $rtt );

Les métriques peuvent être envoyées à un serveur StatsD, qui peut être spécifié via la variable de configuration wgStatsdServer. Vous pouvez travailler avec StatsD localement (sans avoir besoin d'un serveur Graphite) en démarrant un serveur StatsD et en le configurant avec le backend "backends/console", qui générera des métriques sur la console.

À partir de MediaWiki 1.25, wfIncrStats() est un raccourci pour la méthode increment() sur l'instance principale de RequestContext::getStats().

Envoyer des données de débogage à un commentaire HTML dans la sortie

Cela peut parfois être utile lorsqu'on soutient un utilisateur final non technique. Il est plus sûr que d'exposer le fichier journal de débogage sur le Web, car la sortie ne contient que des données privées pour l'utilisateur actuel. Mais il n'est pas idéal pour le développement car les données sont perdues sur les erreurs fatales et les redirections. L'utilisation sur les sites de production n'est pas recommandée. Les commentaires de débogage révèlent des informations dans des vues de page qui pourraient potentiellement exposer des risques de sécurité.

$wgDebugComments = true;

Travailler en direct avec des objets MediaWiki

eval.php est un script interactif pour évaluer et interagir avec les objets et fonctions MediaWiki dans un environnement entièrement initialisé.

 $ php maintenance/eval.php
 > print wfMessage("Recentchanges")->plain();
 Recent changes

La machine virtuelle portable MediaWiki-Vagrant intègre le shell PHP interactif hhvmsh (en utilisant le HHVM par défaut) ou phpsh (en utilisant Zend).

Mises à jour appelables

Le code incorporé dans la fonction DeferredUpdates::addCallableUpdate(), comme $rc->save() dans RecentChange.php, n'est pas exécuté pendant la requête Web, donc aucun message d'erreur ne sera affiché s'il échoue. Pour le débogage, il peut être utile de supprimer temporairement le code de la fonction afin qu'il soit exécuté en direct.

Débogage côté client

Wikipedia propose un riche ensemble d'outils pour le débogage côté client JavaScript. En plus des outils MediaWiki, d'autres techniques sont disponibles pour aider à diagnostiquer les interactions client.

Outils :

  • ResourceLoader propose un moyen d'assurer JavaScript qui est facilement visible par les outils côté client.
  • ResourceLoader fournit également un chemin sécuritaire pour se connecter à la console cliente. Au-delà de la fonction de journalisation JavaScript native, il fournit une vérification pour s'assurer qu'une console est disponible et que l'enregistrement ne génère pas sa propre erreur. ResourceLoader/Features#Debug_mode décrit également cette fonctionnalité.
  • Les outils de navigation peuvent fournir une fonctionnalité native pour déboguer le script côté client.
  • Les traceurs de réseau, comme Wireshark peuvent fournir un aperçu dans le script qui est fourni par une page.

Voir aussi