Debug delle app PWA Kit

I bug e i colli di bottiglia delle prestazioni costituiscono un aspetto inevitabile dello sviluppo di app web. Con PWA Kit è possibile risolvere questi problemi grazie a una serie di strumenti e tecniche di analisi approfondita.

Sostituire tutti i segnaposto in questa guida con i valori effettivi. I segnaposto sono formattati nel seguente modo: $PLACEHOLDER.

Prima di seguire le istruzioni più specifiche di questa guida, provare la seguente procedura di carattere generale:

• Prima di avviare il server di sviluppo locale, verificare che la versione di Node utilizzata sia supportata (fare riferimento alla guida della sezione Inizia).
• Controllare che il server di sviluppo sia ancora in funzione e che la porta non sia occupata da un altro processo.
• Dopo una modifica di codice, verificare che nel terminale venga visualizzato il messaggio HTTP development server listening prima di ricaricare il browser.
• Cercare eventuali errori sia nella console del browser sia nel terminale.
• Cercare eventuali risposte di errore di rete utilizzando gli strumenti per sviluppatori del browser. (In Chrome DevTools, passare alla scheda Rete.)
• Per identificare gli errori di sintassi e di battitura, utilizzare un formattatore di codice e un linter. In Retail React App sono disponibili i file di configurazione per Prettier (formattatore di codice) e per ESLint (linter).
• Controllare le impostazioni antivirus e firewall del computer per individuare eventuali ostacoli che impediscono al codice di eseguire o bloccare le richieste di rete.
• Per identificare e analizzare i problemi di prestazioni, utilizzare il Profiler in Chrome DevTools. Per ulteriori informazioni, vedere la seguente guida di Google: Analyze Runtime Performance (Analisi delle prestazioni di runtime). È possibile inoltre installare l'estensione React Developer Tools per Chrome per aggiungere un'ulteriore scheda Profiler in cui visualizzare informazioni simili, ma a livello di componente.

Per facilitare il debug dei problemi di codice di lato server, è possibile aggiungere due parametri di query speciali a qualsiasi URL pubblicato dall'app di e-commerce.

Il parametro di query __server_only interrompe il processo di hydration, in modo tale che la pagina venga visualizzata nel browser esattamente come appare dopo il rendering di lato server. Poiché i motori di ricerca scansionano la versione della pagina renderizzata sul lato server, la possibilità di visualizzare tale versione consente di risolvere i problemi non solo legati al rendering di lato server, ma anche alla SEO.

Il parametro di query __pretty_print aggiunge una formattazione all'oggetto __PRELOADED_STATE__ per renderlo più leggibile. Questo oggetto fornisce uno snapshot dello stato dell'app anteriore all'hydration, che può essere utile durante il debug per sapere se l'oggetto contiene i valori previsti. Per visualizzare i contenuti dell'oggetto, caricare l'app, visualizzare il codice sorgente della pagina e cercare __PRELOADED_STATE__.

L'oggetto __PRELOADED_STATE__ è incluso in un tag <script> nel codice sorgente HTML della pagina, che è stato inizialmente richiesto quando è iniziata l'esecuzione dell'app sul lato server. L'oggetto __PRELOADED_STATE__ contiene valori serializzati restituiti dalla funzione getProps (incluse le versioni di getProps associate al componente _app e al componente page).

Per impostazione predefinita, l'app server visualizza i messaggi della console nel terminale, ma non consente di osservare altrimenti l'esecuzione del codice. Questo limite può rendere complicato il debug del codice che renderizza le pagine sul lato server (o sulla macchina locale).

Per ottimizzare il debug, è possibile avviare il server di sviluppo locale con un comando alternativo che esegue un processo di controllo in Node associabile a un debugger. (Per ulteriori dettagli, consultare la documentazione di Node.)

È possibile associare al processo di controllo di Node il debugger incluso in molti browser ed editor di testo più diffusi. Ecco le istruzioni per Google Chrome e Visual Studio Code.

1. Aprire un terminale.
2. Passare alla directory di progetto.
3. Avviare il server di sviluppo locale utilizzando npm run start:inspect.
4. Per verificare che il debugger sia in ascolto, cercare il messaggio "Debugger listening" (Debugger in ascolto) nell'output del terminale.
5. Aprire Chrome e inserire l'URL chrome://inspect.
6. Fare clic su Open dedicated DevTools for Node (Apri DevTools dedicato per Node).
7. DevTools si apre in una nuova finestra.
8. Per verificare che il debugger sia associato, cercare il messaggio "Debugger attached" (Debugger associato) nell'output del terminale.
9. Impostare punti di interruzione, aggiungere istruzioni debugger ecc.
10. Caricare una pagina dal server di sviluppo locale in Chrome.
11. Eseguire il debug utilizzando la finestra dedicata.

Ora è possibile tracciare l'esecuzione del codice di lato server.

Per ulteriori informazioni sul debug con punti di interruzione in DevTools, consultare la seguente guida di Google: Debug JavaScript.

1. Aprire i file di progetto in Visual Studio Code.
2. Nella barra dei menu, fare clic su Terminal > New Terminal (Terminale > Nuovo terminale).
3. Avviare il server di sviluppo locale utilizzando npm run start:inspect.
4. Aprire il riquadro comandi. Scelta rapida per Windows: Ctrl + Shift + P. Scelta rapida per Mac: Command + Shift + P.
5. Digitare il comando seguente: “Debug: Attach to Node Process.” (Debug: associa a processo Node.).
6. Viene visualizzato un elenco dei processi Node. Scegliere il primo dell'elenco.
7. Per verificare che il debugger sia associato, cercare il messaggio "Debugger attached" (Debugger associato) nell'output del terminale.
8. Impostare punti di interruzione, aggiungere istruzioni debugger ecc.
9. Caricare una pagina dal server di sviluppo locale nel browser web.
10. Eseguire il debug utilizzando il debugger integrato in Visual Studio Code.

Ora è possibile tracciare l'esecuzione del codice di lato server in Visual Studio Code.

Esistono tre modi per eseguire il debug del codice distribuito su Managed Runtime (MRT):

• Utilizzare le mappe di origine per individuare i punti in cui si sono verificati gli errori.
• Applicare il comando tail ai registri eseguire il debug di problemi o errori in tempo reale in un ambiente a basso volume.
• Per un ambiente Production, utilizzare Log Center, che offre potenti funzionalità di ricerca e conservazione.

Utilizzare le mappe di origine per identificare eventuali errori di lato server o lato client. Le mappe di origine forniscono una semplice analisi dello stack degli errori che individua i punti in cui si è verificato un errore. Ad esempio, l'analisi dello stack identifica il file e il numero di riga in cui si è verificato l'errore per agevolare la risoluzione dei problemi.

Per utilizzare le mappe di origine, è necessario creare il sito utilizzando PWA Kit versione 3.4.x o successiva. Se si dispone di una versione precedente, aggiornare il progetto per l'utilizzo di PWA Kit 3.4.x.

Sono disponibili due opzioni per abilitare le mappe di origine: usare Runtime Admin o Managed Runtime API.

Uso di Runtime Admin

1. Accedere a Runtime Admin.
2. Fare clic sul progetto.
3. Fare clic su un ambiente.
4. Fare clic su Environment Settings (Impostazioni ambiente).
5. Nella sezione Advanced (Avanzate), fare clic su Edit (Modifica).
6. Abilitare Source Maps (Mappe di origine).
7. Nella parte superiore della sezione Advanced (Avanzate), fare clic su Update (Aggiorna).
8. Attendere la fine della redistribuzione del bundle.

Uso di Managed Runtime API

Richiamare l'endpoint API projects_target_partial_update e impostare enable_source_maps su true. In questo modo viene configurata la variabile di ambiente Managed Runtime NODE_OPTIONS nel proprio ambiente con --enable-source-maps e viene ridistribuito il bundle.

1. Quando si compila il progetto, generare il file ssr.js.map utilizzando questa variabile di ambiente locale: PWA_KIT_SSR_SOURCE_MAP=true.

2. Distribuire il bundle in Managed Runtime.

Dopo aver abilitato e caricato le mappe di origine, è possibile visualizzarle utilizzando l'Applicazione del comando tail ai registri in Managed Runtime.

L'utilizzo delle mappe di origine può causare problemi di prestazioni. Ad esempio, c'è latenza ogni volta che si accede a error.stack. Quindi, quando si include console.error(e) nel proprio codice, l'azione può rallentare il sito.

• Nuovi ambienti non di produzione: enable_source_maps è impostato su true.
• Nuovi ambienti Production: enable_source_maps è impostato su false. Questo comportamento consente di evitare potenziali riduzioni delle prestazioni che possono verificarsi quando è abilitata la funzionalità delle mappe di origine .
• Tutti gli ambienti preesistenti: enable_source_maps è impostato su false.

Quando l'app viene distribuita su Managed Runtime, il debug remoto non è supportato. Tuttavia, è possibile applicare il comando tail ai registri per qualsiasi ambiente Managed Runtime in tempo reale per diagnosticare eventuali errori di lato server.

Per applicare il comando tail ai registri tramite la riga di comando sono disponibili due opzioni:

Se si lavora in progetto PWA Kit generato nella versione 2.4.1 o successiva, è possibile:

• Visualizzare la guida per il comando dei registri: npm run tail-logs -- --help
• Applicare il comando tail ai registri per un progetto e un ambiente specifici: npm run tail-logs -- --environment $ENV_ID

Se si lavora al di fuori di un progetto PWA Kit o in un progetto generato in versioni precedenti alla 2.4.1, è possibile utilizzare npx per:

• Visualizzare la guida per il comando dei registri: npx @salesforce/pwa-kit-dev tail-logs --help
• Applicare il comando tail ai registri per un ID ambiente e un ID progetto specifici: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

Quando si applica il comando tail ai registri, è importante tenere presente i seguenti limiti:

• Ciascuna sessione di applicazione del comando tail ai registri terminerà dopo 60 minuti.
• Ogni ambiente può supportare fino a 100 sessioni attive di applicazione del comando tail ai registri alla volta tra tutti gli utenti.
• Per applicare il comando tail ai registri è necessario disporre delle autorizzazioni di utente amministratore o sviluppatore per il progetto Managed Runtime.

Utilizzare Log Center per risolvere gli errori se è stato creato un sito utilizzando PWA Kit o se si dispone di un'istanza B2C Commerce. Log Center:

• Fornisce un'unica posizione per accedere ai registri da Managed Runtime (MRT) e dalla propria istanza B2C Commerce. Connettere ciò che accade nell'ambiente MRT con ciò che accade nella propria istanza B2C Commerce.
• Consente di cercare e filtrare molti registri storici. Si possono ottenere ulteriori informazioni su ciò che è accaduto nell'ambiente Production e così indagare e risolvere i problemi più rapidamente.

Questa guida è incentrata sul debug per i siti creati utilizzando PWA Kit. Per informazioni sull'uso di Log Center con l'istanza B2C Commerce, vedere Log Center centralizzato.

Per accedere ai registri MRT per un ambiente in Log Center, è necessario innanzitutto:

1. Disporre del ruolo Utente di Log Center in Account Manager. Per verificare, controllare il proprio ruolo in Account Manager. Se non dispone del ruolo, chiedere all'amministratore dell'Account Manager di concedere l'accesso. Vedere Gestione di Account Manager per gli utenti di Salesforce B2C Commerce.

2. Configurare l'ambiente come segue:

   a. Contrassegnare l'ambiente come ambiente Production. Vedere i dettagli e le limitazioni relativi agli ambienti Production.

   b. Selezionare un'istanza Commerce Cloud (B2C Commerce) per connettersi all'ambiente.

   c. Aggiungere uno o più ID di sito da associare all'ambiente.

Dopo aver completato i Prerequisiti, per visualizzare i registri MRT in Log Center:

1. Avviare Log Center.
2. Selezionare una Region (Area geografica).
3. Selezionare un Realm. Se l'ID del realm è sconosciuto, rivolgersi all'Account Executive (AE) o al Customer Success Manager (CSM).
4. Fare clic su Show filtered results (Mostra risultati filtrati).
5. Fare clic su Search > Current Search (Cerca > Ricerca corrente).
6. In Service Type (Tipo di servizio) selezionare mrt.
7. In Host selezionare l'ambiente Production di cui si desidera visualizzare i registri MRT. Il formato dell'host è $PROJECT.$ENVIRONMENT. Se si dispone di più ambienti Production MRT, è possibile visualizzare più nomi host MRT.
8. Visualizzare i registri MRT.

Per informazioni sui livelli e sui volumi di registro in Log Center, vedere Configurazione per amministratori.