[PaaS uniquement]{class="badge informative" title="S’applique uniquement aux projets Adobe Commerce on Cloud (infrastructure PaaS gérée par Adobe) et aux projets On-premise."}

Bonnes pratiques de débogage pour Adobe Commerce

Cette rubrique explique comment déboguer systématiquement et efficacement le framework Adobe Commerce. L’objectif est de vous aider à vous attaquer rapidement à la racine d’un problème et de réduire le temps nécessaire aux enquêtes.

Dépannage : les suspects habituels

Cette section décrit les problèmes les plus courants que vous pouvez rencontrer pendant le développement.

Cache

L’exemple de code suivant fournit des commandes utiles liées à la gestion du cache (ne pas exécuter dans les environnements de production) :

# restart php-fpm to flush APC
sudo service php-fpm restart

# restart varnish to force full flush
sudo service varnish restart

# clear generated files
rm -rf generated/*

# clear static file cache
rm -rf var/view_preprocessed/*
rm -rf pub/static/*

# flush redis cache
redis-cli -n <db_number> FLUSHDB

# flush redis cache and sessions
redis-cli FLUSHALL

# flush redis cache with telnet
telnet <ip_or_host> 6379
SELECT <db_number>
FLUSHDB
Ctrl + ]
quit

# flush redis cache and sessions with telnet
telnet <ip_or_host> 6379
FLUSHALL
Ctrl + ]
quit

# find consumers
pgrep -af queue:consumers:start

# kill all queue consumers (they will restart by cron job)
sudo pkill -f queue:consumers:start

# kill a specific queue consumer (it will restart by cron job)
sudo kill <process_id>

Données indexées

Réindexez tout si le problème peut être lié à l’index. Le débogage des données indexées se produit généralement dans les environnements hors production. Dans les environnements de production, vous pouvez rechercher l’origine de l’alignement incorrect des index avant de les réindexer. Les caractéristiques de l'état défectueux peuvent vous en dire quelque chose sur l'origine du problème.

Compositeur

Il se peut que votre code soit obsolète en raison d’une modification de branche ou de fichiers principaux modifiés lors d’un effort de débogage précédent. Pour éliminer les problèmes potentiels, exécutez les commandes suivantes :

rm -rf vendor/*
composer clear-cache
composer install

Contenu généré

Recréez les fichiers frontend avant de déboguer le contenu généré dans les fichiers JS, CSS, images, traductions et autres.

rm -rf generated/* var/cache/* var/page_cache/* var/session/* var/view_preprocessed/* pub/static/*
bin/magento setup:static-content:deploy
bin/magento cache:flush

Mode Développeur

Assurez-vous que votre installation locale est en mode developer.

Nouveau module

Si vous avez créé un module, vérifiez les problèmes suivants :

Dépannage : division en deux

Si les suspects habituels n’offrent pas de solution au problème, la façon la plus rapide de procéder est de diviser le problème en deux (ou en deux). Avec cette méthode, vous éliminez des blocs volumineux et divisez ce qui reste pour localiser la cause principale au lieu de parcourir le code de manière linéaire.

Voir les diagrammes suivants :

Il existe plusieurs approches pour bissecter, mais Adobe recommande de suivre cet ordre :

Étape 1 : Bisecter par sujet

Si le problème n’est pas lié au code, éliminez d’abord les blocs volumineux. Voici quelques-uns des éléments importants à prendre en compte :

Étape 2 : division par validations

Si le problème a commencé entre maintenant et il y a deux mois, restaurez le code à deux mois auparavant. Vérifiez si le problème existe toujours. Avance d'un mois. Le problème se produit-il là-bas? Sinon, allez-y pendant deux semaines. Cela se produit-il maintenant ? Retourne une semaine en arrière. Toujours là ? Remontez quatre jours en arrière. À un moment donné, il ne vous reste qu’une seule validation, qui contient probablement du code lié au problème. Votre cause première est désormais probablement limitée aux fichiers modifiés dans cette validation.

Vous pouvez remplacer semaines et jours par des validations. Par exemple, annuler 100 validations, avancer 50, avancer 25, reculer 12.

Étape 3 : Diviser par fichiers

Gains de temps

Outre les techniques de dépannage, cette section fournit quelques règles générales qui peuvent vous aider à gagner du temps lors du débogage.

Limiter les données

Déterminez si vous avez besoin du catalogue complet ou de toutes les vues de magasin pour répliquer le problème. Vous pouvez déboguer les problèmes d’indexation avec un clone de base de données dans lequel vous avez supprimé 95 % du catalogue avant de commencer le débogage. Cette méthode permet de gagner beaucoup de temps pendant les processus d’indexation. Créez un doublon de la base de données cliente avec un nombre de magasins et un catalogue réduits. Cela peut également s’appliquer à d’autres entités (comme les clients) en fonction de la zone que vous déboguez.

Demander plus d'informations

Parfois, une étape facile à oublier parmi tout le code et le travail technique : demandez plus d'informations. Captures en plein écran, vidéo, conversation par vidéoconférence avec la personne qui a identifié le problème, étapes de réplication, questions pour savoir si d’autres événements apparemment sans importance se sont produits autour de l’événement problématique. Demandez-lui ce que quelqu'un s'attendait à voir se produire. S’agit-il vraiment d’un bug ou peut-être simplement d’une mauvaise compréhension du fonctionnement du code ?

Langue et interprétation

La description du problème est-elle claire ? Êtes-vous certain qu’aucun terme ou description ne peut être interprété de plusieurs façons. Si oui, assurez-vous de parler de la même chose.

Recherche sur Internet

Effectuez une recherche sur Internet avec les termes liés au problème. Il est probable que quelqu’un d’autre ait déjà rencontré le même problème. Recherchez parmi les problèmes GitHub d’Adobe Commerce.

Faites une pause

Si vous cherchez un problème depuis trop longtemps, il peut être difficile de trouver une solution. Déposez votre travail et prenez une autre tâche ou faites une promenade. La réponse peut vous venir lorsque vous oubliez la question pendant un certain temps.

Outils

Les outils de l’interface de ligne de commande n98 magerun (https://github.com/netz98/n98-magerun2) offrent des fonctionnalités utiles pour travailler avec Adobe Commerce à partir de la ligne de commande. En particulier, ces commandes :

n98-magerun2.phar dev:console
n98-magerun2.phar sys:cron:run
n98-magerun2.phar db:console
n98-magerun2.phar index:trigger:recreate

Fragments de code

Les rubriques suivantes fournissent des fragments de code qui peuvent être utilisés pour consigner ou identifier des problèmes dans les projets Commerce.

Vérifier si un fichier XML est utilisé par Commerce

Ajoutez une erreur de syntaxe évidente dans un fichier XML pour voir si elle est utilisée. Ouvrez une balise sans la fermer par exemple :

<?xml version="1.0"?>
<test

Si ce fichier est utilisé, il génère une erreur. Si ce n'est pas le cas, il se peut que votre module ne soit pas utilisé ou activé, par exemple, ou que le fichier XML se trouve au mauvais emplacement.

Journalisation

\Magento\Framework\App\ObjectManager::getInstance()
    ->get(\Psr\Log\LoggerInterface::class)->debug('message');

$log = new \Monolog\Logger('custom', [new \Monolog\Handler\StreamHandler(BP.'/var/log/test.log')]);
$log->info('Your Logging Message', ['context' => ['email' => 'john@example.com']]);

$writer = new \Zend\Log\Writer\Stream(BP . '/var/log/test.log');
$logger = new \Zend\Log\Logger();
$logger->addWriter($writer);
$logger->info('Your text message');
$logger->info(print_r($yourArray, true));

Journalisation de bas niveau

Deux exemples qui fonctionnent toujours dans n'importe quel fichier PHP :

file_put_contents('/var/www/html/var/log/example.log', "example line\n", FILE_APPEND);
file_put_contents('/var/www/html/var/log/example.log', print_r($yourArray, true) . "\n", FILE_APPEND);

Et pour une trace de pile :

try {
    throw new \Exception('example');
} catch (\Exception $e) {
    file_put_contents('/var/www/html/var/log/example.log', $e->getTraceAsString() . "\n", FILE_APPEND);
}