Handleiding:Hoe te debuggen

This page is a translated version of the page Manual:How to debug and the translation is 100% complete.

Op deze pagina wordt een introductie gegeven voor het debuggen van de MediaWiki software.

Een van de eerste dingen die opvalt is dat "echo" in het algemeen niet werkt; dit is deel van het algemene ontwerp.

Er zijn meerdere configuratie-opties voor het ondersteunen van het debuggen. De volgende staan standaard op false, dus uit. Het inschakelen is vanzelfsprekend het op true zetten in uw bestand LocalSettings.php :

  • $wgShowExceptionDetails Meer details tonen (zoals een 'stack trace') op de pagina met de "Fatal error".
  • $wgDebugToolbar Toont een werkbalk op de pagina met o.a. profilering en logberichten.
  • $wgShowDebug Voegt het deel "logberichten" van de wgDebugToolbar aan de pagina toe als een ruwe lijst.
  • $wgDevelopmentWarnings MediaWiki zal meldingen geven voor mogelijke foutcondities en voor ontraden functies.

Voorbeeldregel die moet worden toegevoegd aan uw LocalSettings.php :

$wgShowExceptionDetails = true;

PHP fouten

Om PHP fouten te zien, voeg dit aan de 2e regel toe (net onder <?php) van LocalSettings.php :

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

Of plaats deze regels in php.ini :

error_reporting = E_ALL
display_errors = On

Of in .htaccess:

php_value error_reporting -1
php_flag display_errors On

Hierdoor worden PHP-fouten nu op de pagina getoond. Dit kan het voor kwaadwillenden gemakkelijker maken om uw server te kraken, laat dit dus alleen even zo staan tijdens uw test.

Het kan zijn dat een fatale PHP-fout optreedt in een regel die nog niet uitgevoerd is of voorkomt dat die worden getoond. Fatale PHP-fouten worden normaal gesproken gelogd in de error-log van Apache. Controleer de instelling error_log in php.ini (of gebruik phpinfo()).

Zet display_startup_errors aan

Enkele providers zetten display_startup_errors uit, dat verbergt de fouten ook als u het level error_reporting gebruikt. Het aanzetten in het programma werkt niet! Maak daarvan in plaats een wrapper bestand om uw bestand. In het geval van MediaWiki kunt u dit toevoegen bovenaan in mediawiki/index.php:

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

In andere omgevingen:

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

SQL fouten

Om SQL-queries te loggen, in plaats van alleen de queries die foutlopen: zet $wgDebugDumpSql in LocalSettings.php:

$wgDebugDumpSql = true;
MediaWiki-versies:
1.16 – 1.31

Voor versie 1.32 van de MediaWiki moest men de $wgShowSQLErrors en $wgShowDBErrorBacktrace zetten om de details van de database-fouten te zien in de HTML-uitvoer:

$wgShowSQLErrors = true;
$wgShowDBErrorBacktrace = true;

Diepgaand debuggen

Debugger

U kunt de code stap voor stap debuggen met XDebug . Een aantal gebruikelijke configuraties:

MediaWiki-Vagrant heeft hiervoor ingebouwde instellingen. Als u MediaWiki-Vagrant niet gebruikt, maar uw set-up vergelijkbaar is, kunt u die waarden hergebruiken. In sommige gevallen (bijvoorbeeld door een firewall) moet u de IDE op dezelfde machine gebruiken als de webserver. In dat geval kunt u eenvoudig instellen:

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

Meer informatie over XDebug.

Om een commando-regel script (PHPUnit of een onderhoudsscript) te debuggen op MediaWiki-Vagrant, gebruik:

xdebug_on; php /vagrant/mediawiki/path/to/script.php --wiki=wiki ; xdebug_off

Pas het script, parameters en de remote host aan (het moet de IP zijn van de computer wat uw IP heeft, 10.0.2.2 zou moeten werken voor MediaWiki-Vagrant).

Inloggen

Voor meer informatie moet u profileren en de log gebruiken.

De onderstaande instructies zijn voor de standaardconfiguratie. Als u de $wgMWLoggerDefaultSpi wijzigt, bijvoorbeeld om de rol psr3 in te schakelen op een vagrant veld, dan worden deze instellingen waarschijnlijk genegeerd. Bekijk dan de documentatie over uw logging, bijvoorbeeld Manual:MonologSpi .

Een logbestand instellen voor het debuggen

Om fouten en debug informatie in een log te plaatsen, voeg $wgDebugLogFile toe aan het bestand LocalSettings.php. Wijzig de waarde naar een tekstbestand waarin u de debug trace de uitvoer wilt laten schrijven.

De MediaWiki software moet rechten krijgen van uw besturingssysteem om dit bestand aan te maken en om erin te schrijven. In een standaard Ubuntu installatie wordt het uitgevoerd als gebruiker en groep www-data:www-data. Een mogelijke instelling:

/**
 * 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";

Dit bestand zal debug-informatie bevatten van de core MediaWiki en diens extensies. Enkele subsystemen schrijven naar eigen of andere logbestanden, lees dit artikel om die logging te bekijken.


  Waarschuwing: Het logbestand van het debuggen kan persoonlijke informatie (inloggegevens, sessie cookies en ingevulde schermvelden) bevatten. Dat is informatie die niet bij (aspirant) hackers van uw computer terecht moet komen. Als iemand deze log wil zien voor bijvoorbeeld een analyse, benader dan de wiki zonder in te loggen. Verwijder uit uw kopie van het bestand dan alle regels over een COOKIE en ook degene die over inloggen gaan.

Aangepast logbestand aanmaken

MediaWiki-versie:
1.31

Voor MediaWiki 1.32 kon je een aangepast logbestand maken dat alleen uw specifieke debug statements bevatte. Dat ging met de functie wfErrorLog(). Deze functie heeft twee argumenten, de te loggen tekst en het pad naar het logbestand:

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

Aangepaste loggroepen aanmaken

Als u verschillende componenten probeert te debuggen, dan kunt u loggen naar meerdere logbestanden. Zie $wgDebugLogGroups voor meer informatie.

Om meerdere loggroepen in te stellen, voeg het volgende toe aan 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';
$wgDebugLogGroups = array(
	'exception' => '/var/log/mediawiki/exception.log',
	'resourceloader' => '/var/log/mediawiki/resourceloader.log',
	'ratelimit' => '/var/log/mediawiki/ratelimit.log',

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

Om dan naar een bepaalde groep te loggen, roep wfDebugLog op deze manier aan:

if ( $module->hasFailed ) {
    wfDebugLog( 'myextension', "Something is not right, module {$module->name} failed." );
}
Als er niets in uw logbestand(en) wordt geschreven en uw systeem gebruikt SELinux, kijk dan naar de sectie logging op de SELinux pagina.
Het schrijven in een logbestand in de map /tmp kan mislukken, ook al is deze map bedoeld om schrijfbaar te zijn. Uw systeem kan een systeemfunctie gebruiken dat een virtuele map /tmp gebruikt voor dat proces. Wijzig, in dat geval, de map van uw logbestand(en) naar een andere waarde, bijvoorbeeld /var/log/mediawiki

Gestructureerde logging

MediaWiki-versie:
1.25

Gestructureerde logging staat u toe om velden in uw loggegevens toe te voegen. Zie Structured logging voor meer informatie.

U dient een betere logger in te stellen om meer informatie te verzamelen, bijvoorbeeld Monolog.

JavaScript loggen van fouten

MediaWiki-versie:
1.36

Zie de documentatie van de ResourceLoader module mediawiki.errorLogger .

Statistieken

Geavanceerde klantzijde logging kan met Extension:EventLogging worden gedaan, hiervoor is een complexe instelling en een zorgvuldige controle op het omgaan met privacy gevoelige informatie nodig.

Het eenvoudig tellen van bepaalde type gebeurtenissen is mogelijk (sinds versie 1.25) met gebruik van StatsD. StatsD zorgt voor tellers van allerlei soort ook voor met meten van de tijd.

Gebruiksvoorbeeld:

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

Deze gegevens kunnen worden verzonden naar een StatD server die met wgStatsdServer kan worden ingesteld. (Zonder het instellen worden de metingen verwijderd.) U kunt lokaal met StatsD werken (zonder een Graphite server nodig te hebben) door een StatsD server te starten en het in te stellen met het "backends/console", de uitvoergegevens van de metingen komen dan op het console.

Vanaf MediaWiki 1.25 is wfIncrStats() een verkorte aanduiding voor de methode increment() in de instantie RequestContext::getStats().

Debuggegevens in HTML commentaar zetten

Dit kan soms bruikbaar zijn bij het ondersteunen van een niet technische gebruiker. Het is veiliger dan het logbestand van het debuggen op het web te laten zien omdat de uitvoer alleen private gegevens van de huidige gebruiker bevat. Maar in de ontwikkelfase is het niet ideaal omdat er dan gegevens over fouten en verwijzingen ontbreken. Het gebruiken op productie-omgevingen wordt niet aanbevolen. Debug commentaar openbaart informatie die het veiligheidsrisico verhoogt.

$wgDebugComments = true;

MediaWiki objecten in productie gebruiken

eval.php is een interactief script voor het evalueren en bekijken van MediaWiki objecten en functies in een volledige geïnitialiseerd omgeving.

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

De portabele MediaWiki-Vagrant virtuele machine integreert met de interactieve PHP shell phpsh (bij gebruik van Zend).

Oproepbare updates

De code die ingebed zit in de functie DeferredUpdates::addCallableUpdate(), zoals $rc->save() in RecentChange.php, wordt niet uitgevoerd bij de webrequest, er wordt dus geen foutboodschap getoond als dat mislukt. Bij het debugging, is het mogelijk handig om tijdelijk deze code niet uit te laten voeren in de functie zodat het loggen wel dan wordt uitgevoerd.

Interactieve shell

U kunt shell.php gebruiken als een PHP REPL met volledige toegang tot de interne functies van MediaWiki (internals).

Cliëntzijde debuggen (JavaScript)

Wikipedia heeft veel hulpmiddelen voor het debuggen aan de klantzijde met JavaScript. Als aanvulling op de hulpmiddelen van MediaWiki tools zijn er andere technieken beschikbaar voor het helpen met de diagnose van de interactie met de klant.

Hulpmiddelen:

  • ResourceLoader zorgt dat JavaScript zeker eenvoudig te bekijken is met de hulpmiddelen.
  • Open het console van uw webbrowser Veel klantzijde Mediawiki scripts zetten de foutboodschappen op het console met gebruik van ResourceLoader, die zorgt dat dat veilig kan. Naast de interne JavaScript logfunctie, zorgt het ook voor een controle dat er een console beschikbaar is en dat de logging zelf niet foutloopt. Deze functie is beschreven in ResourceLoader/Architecture#Debug_mode.
  • De webbrowser heeft vermoedelijk ook interne hulpmiddelen voor het debuggen van code.
  • Netwerk tracers, zoals Wireshark geven inzicht in het script dat wordt gebruikt door een pagina.
  • U kunt ?debug=true toevoegen aan uw URL (bijv. https://www.mediawiki.org/wiki/MediaWiki?debug=true) om gedetailleerde informatie voor het debuggen te krijgen via het console van de webbrowser.

Zie ook