Aller au contenu principal

Traçage et Profilage avec Xdebug

En plus du débogueur pas à pas, Xdebug peut enregistrer ce que votre code a fait après coup :

  • Le mode trace écrit chaque appel de fonction, argument et durée dans un fichier trace.*.xt.
  • Le mode profile écrit un fichier cachegrind que vous pouvez ouvrir dans Speedscope, KCachegrind, QCachegrind ou PhpStorm.

Lorsqu'il est démarré avec --xdebug, Playground active les modes debug et develop par défaut. Utilisez --php-ini pour activer des modes supplémentaires ou modifier n'importe quel réglage php.ini, y compris les réglages Xdebug. Les valeurs passées de cette manière remplacent à la fois les valeurs par défaut de Playground et celles de Xdebug.

Enregistrer une trace et un profil​

Les fichiers de trace et de profil sont écrits dans xdebug.output_dir, qui est un chemin dans le système de fichiers virtuel de Playground. Montez-y un répertoire à vous pour que les fichiers soient conservés après la fin de la requête :

mkdir -p ./xdebug-output

npx @wp-playground/cli@latest server \
--xdebug \
--mount ./xdebug-output:/xdebug-output \
--php-ini xdebug.mode debug,develop,trace,profile \
--php-ini xdebug.start_with_request trigger \
--php-ini xdebug.output_dir /xdebug-output \
--php-ini xdebug.trace_output_name trace.%u.%p \
--php-ini xdebug.profiler_output_name cachegrind.out.%u.%p

Ensuite, demandez la page que vous voulez mesurer avec le paramètre XDEBUG_TRIGGER :

curl "http://127.0.0.1:9400/wp-json/wp/v2/posts?XDEBUG_TRIGGER=1"

./xdebug-output contient maintenant un fichier trace.*.xt et un fichier cachegrind.out.* pour cette requête. Déposez le fichier cachegrind dans Speedscope pour voir où le temps est passé, et ouvrez le fichier de trace dans votre éditeur pour suivre le chemin des appels.

Enregistrer à la demande, pas à chaque requête​

xdebug.start_with_request=trigger est le réglage qui rend l'enregistrement optionnel. Rien n'est écrit tant qu'une requête ne porte pas XDEBUG_TRIGGER comme paramètre GET, paramètre POST ou cookie.

C'est important parce que les fichiers sont volumineux. Une requête sur la page d'accueil de WordPress produit une trace d'environ 135 Mo et un fichier cachegrind d'environ 22 Mo. Avec xdebug.start_with_request=yes, chaque requête, y compris chaque appel admin-ajax et REST effectué par votre navigateur, écrit les deux fichiers.

Le déclencheur démarre aussi le débogueur pas à pas, donc un Playground démarré de cette manière ne se connecte à votre IDE que sur les requêtes déclenchées.

Donner à chaque enregistrement son propre nom de fichier​

Par défaut, Xdebug peut donner le même nom de fichier à deux enregistrements, donc une nouvelle requête peut écraser un enregistrement précédent. Consultez xdebug.trace_output_name et xdebug.profiler_output_name pour les noms par défaut.

Ajouter %u (horodatage avec microsecondes) à xdebug.trace_output_name et xdebug.profiler_output_name conserve un fichier par requête, comme dans la commande ci-dessus. Exécuter avec --workers=1 garde aussi la sortie prévisible.

Utiliser l'API de la bibliothèque​

PHP lit php.ini avant les fichiers ini spécifiques aux extensions, donc les réglages dans xdebug.ini prennent le pas sur les réglages correspondants dans php.ini. Le Playground CLI écrit les entrées xdebug.* dans xdebug.ini et toutes les autres entrées dans php.ini. Lorsque vous utilisez @php-wasm/node directement, passez le chemin du fichier ini de Xdebug à setPhpIniEntries() :

import { PHP, PHP_EXTENSIONS_DIR, setPhpIniEntries } from '@php-wasm/universal';
import { joinPaths } from '@php-wasm/util';
import { mkdirSync } from 'node:fs';
import { loadNodeRuntime, createNodeFsMountHandler } from '@php-wasm/node';

const php = new PHP(await loadNodeRuntime('8.5', { extensions: ['xdebug'] }));

await setPhpIniEntries(
php,
{
'xdebug.mode': 'debug,develop,trace,profile',
'xdebug.start_with_request': 'trigger',
'xdebug.output_dir': '/xdebug-output',
'xdebug.trace_output_name': 'trace.%u.%p',
'xdebug.profiler_output_name': 'cachegrind.out.%u.%p',
},
joinPaths(PHP_EXTENSIONS_DIR, 'xdebug.ini')
);

mkdirSync('./xdebug-output', { recursive: true });
await php.mount('/xdebug-output', createNodeFsMountHandler('./xdebug-output'));

Appelez setPhpIniEntries() avant que la première requête s'exécute. PHP analyse les fichiers ini une seule fois, à la première exécution, et ignore toute écriture ultérieure.

Sans le troisième argument, setPhpIniEntries() écrit php.ini, et les entrées fournies par une extension continuent de prendre le pas sur lui. Une entrée que vous ne définissez pas conserve sa valeur par défaut.

Démarrer une trace depuis PHP​

Les fonctions propres à Xdebug fonctionnent aussi, et elles n'ont pas besoin de déclencheur :

xdebug_start_trace('/xdebug-output/checkout');
do_the_slow_thing();
xdebug_stop_trace();

C'est l'option la plus ciblée. Elle enregistre un bloc de code au lieu d'une requête entière, ce qui garde le fichier de trace assez petit pour être lu à la main.