Best practice per il debug per Adobe Commerce

Questo argomento spiega come eseguire il debug sistematico ed efficace del framework Adobe Commerce. L’obiettivo è quello di aiutarti a individuare rapidamente la radice di un problema e ridurre al minimo i tempi di investigazione.

Risoluzione dei problemi: sospetti abituali

Questa sezione descrive i problemi più comuni che potresti riscontrare durante lo sviluppo.

Cache

Nell'esempio di codice riportato di seguito vengono forniti utili comandi relativi alla gestione della cache (da non eseguire in ambienti di produzione):

# 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>

Dati indicizzati

Reindicizza tutto se il problema può essere correlato all'indice. Il debug dei dati indicizzati avviene tipicamente in ambienti non di produzione. Negli ambienti di produzione, è possibile esaminare l'origine del disallineamento dell'indice prima di reindicizzare. Le caratteristiche dello stato difettoso possono dirvi qualcosa sull'origine del problema.

Compositore

È possibile che il codice non sia aggiornato a causa di una modifica del ramo o di file core modificati in un precedente tentativo di debug. Per eliminare potenziali problemi, esegui i seguenti comandi:

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

contenuto generata

Ricostruisci i file front-end prima di eseguire il debug dei contenuto generati in JS, CSS, immagini, traduzioni e altri file.

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

Modalità sviluppatore

Verificare che l'installazione locale sia in modalità developer.

Nuovo modulo

Se hai creato un modulo, verifica la presenza dei seguenti problemi:

Risoluzione dei problemi: Suddivisione in parti uguali

Se i soliti sospetti non offrono una soluzione al problema, il modo più veloce per procedere è quello di dividere il problema per metà (o bisecare). Con questo metodo, si eliminano grandi blocchi e si divide ciò che rimane per individuare la causa principale invece di passare attraverso il codice in modo lineare.

Vedere i seguenti diagrammi:

Esistono diversi approcci alla bisezione, ma l’Adobe consiglia di seguire questo ordine:

Passaggio 1: Bisect per argomento

Se il problema non è correlato al codice, eliminare prima i blocchi di grandi dimensioni. Alcuni dei blocchi più grandi a cui pensare includono:

Passaggio 2: eseguire il bisect per commit

Se il problema è iniziato tra ora e due mesi fa, riporta il codice a due mesi fa. Verificare se il problema persiste. Andare avanti di un mese. Il problema si verifica qui? In caso contrario, procedere di due settimane. Si verifica ora? Torna indietro di una settimana. Ancora lì? Torna indietro di quattro giorni. A un certo punto, è rimasto un solo commit che probabilmente conterrà il codice relativo al problema. La causa principale è ora probabilmente limitata ai file modificati in tale commit.

È possibile sostituire settimane e giorni con commit. Ad esempio, esegui il rollback di 100 commit, avanti 50, avanti 25, indietro 12.

Passaggio 3: creare un file Bisect by

Risparmi di tempo

Oltre alle tecniche di risoluzione dei problemi, questa sezione fornisce alcune regole generali che possono aiutare a risparmiare tempo durante il debug.

Limita dati

Valuta se hai bisogno dell'intero catalogo o di tutte le store viste per replicare il problema. È possibile debug problemi di indicizzazione con un clone di database in cui è stato rimosso il 95% del catalogo prima di iniziare il debug. Questo metodo consente di risparmiare molto tempo durante i processi di indicizzazione. Crea un duplicato del database client con conteggio store e catalogo ridotti. Ciò può essere applicato anche ad altre entità (ad esempio i clienti) a seconda dell'area di cui si esegue il debug.

Richiedi maggiori informazioni

A volte, un passo facile da dimenticare in mezzo a tutto il codice e il lavoro tecnico: chiedere maggiori informazioni. Acquisizioni a schermo intero, un video, una chat in videoconferenza con la persona che ha identificato il problema, passaggi di replica, domande sul fatto che altre cose apparentemente non importanti siano accadute intorno all'evento problematico. Chiedi cosa qualcuno si aspettava che accadesse. Si tratta davvero di un bug o forse solo di un'incomprensione del modo in cui funziona il codice?

Lingua e interpretazione

La descrizione del problema è chiara? Sei sicuro che nessun termine o descrizione possa essere interpretato in più modi? Se è così, assicurati di parlare della stessa cosa.

Internet ricerca

Eseguire una ricerca su Internet con i termini relativi al problema. È probabile che un altro utente abbia già riscontrato lo stesso problema. Cerca nei problemi GitHub di Adobe Commerce.

Fai una pausa

Se si sta cercando un problema troppo a lungo, può essere difficile trovare una soluzione. Metti giù il tuo lavoro e prendi un altro compito o fai una passeggiata. La risposta potrebbe venire quando si dimentica del problema per un po '.

Strumenti

Gli strumenti CLI n98 magerun (https://github.com/netz98/n98-magerun2) forniscono funzionalità utili per l'utilizzo di Adobe Commerce dalla riga di comando. In particolare, i seguenti comandi:

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

Frammenti di codice

Negli argomenti seguenti vengono forniti snippet di codice che possono essere utilizzati per registrare o identificare i problemi nei progetti Commerce.

Controlla se Commerce utilizza un file XML

Aggiungi un errore di sintassi evidente in un file XML per verificare se è utilizzato. Apri un tag e non chiuderlo, ad esempio:

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

Se questo file viene utilizzato, genera un errore. In caso contrario, il modulo potrebbe non essere utilizzato o non essere abilitato, ad esempio, oppure il file XML potrebbe trovarsi in una posizione errata.

Registrazione

\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));

Registrazione di basso livello

Due esempi che funzionano sempre in qualsiasi file 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);

E per una traccia dello stack:

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