Configurazione di Cloud Debugger per Node.js

Panoramica

Nota: Cloud Debugger è compatibile con Node.js versione 9 e successive. Ti consigliamo di utilizzare la versione di Assistenza a lungo termine.

In questa pagina viene descritto come configurare l'ambiente e l'applicazione Node.js per utilizzare Cloud Debugger. Per alcuni ambienti devi specificare esplicitamente l'ambito di accesso per consentire all'agente Cloud Debugger di inviare i dati. Ti consigliamo di impostare l'ambito di accesso più ampio possibile e quindi utilizzare Identity and Access Management per limitare l'accesso. In base a questa best practice, imposta l'ambito di accesso su tutte le API Cloud con l'opzione cloud-platform.

Versioni linguistiche e ambienti di calcolo

Cloud Debugger è disponibile per Node.js 9 e versioni successive nei seguenti ambienti di calcolo:

Ambiente standard di App Engine	Ambiente flessibile di App Engine	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	VM e container in esecuzione altrove	Cloud Functions

beta

Questa libreria è coperta dai Termini delle Offerte pre-GA dei Termini di servizio di Google Cloud. Le librerie pre-GA potrebbero avere supporto limitato e le modifiche alle librerie pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Configurazione di Cloud Debugger

Per configurare Cloud Debugger, completa le seguenti attività:

1. Verifica che l'API Cloud Debugger sia abilitata per il tuo progetto.

2. Installa e configura il debugger nell'ambiente di calcolo che stai utilizzando.

3. Seleziona il codice sorgente.

   Nota: per motivi legati alle prestazioni, l'agente Cloud Debugger per Node.js non supporta l'aggiunta di snapshot o punti di log sui file nella directory node_modules.

La verifica dell'API Cloud Debugger è abilitata

Per iniziare a utilizzare Cloud Debugger, assicurati che l'API Cloud Debugger sia abilitata. Cloud Debugger è abilitato per impostazione predefinita per la maggior parte dei progetti.
Abilita l'API Cloud Debugger

Nota: Cloud Debugger è gratuito. Tuttavia, è necessario un progetto Google Cloud con fatturazione abilitata per poter utilizzare Cloud Debugger.

Snapshot e punti di log canary

Per evitare il caricamento simultaneo di snapshot e punti di log su tutte le istanze in esecuzione e con la possibile causa della rimozione del job a causa di un bug potenziale dell'agente Debugger, abilita la modalità canary per l'agente Debugger. Quando la modalità canary è abilitata, viene applicato uno snapshot o un punto di log a un sottoinsieme di istanze in esecuzione e Debugger verifica che lo snapshot o il punto di log non influisca negativamente su tali istanze. Al termine della verifica, lo snapshot o il punto di log viene applicato a tutte le istanze.

Nota: la versione canary è disponibile per l'agente Node.js Debugger 5.1.0 e versioni successive.

Per informazioni su come utilizzare Debugger in modalità canary, vai alle pagine Istantanea debug e Punti di log di debug.

Abilitazione di snapshot e punti di log canary

Quando installi la versione più recente dell'agente Debugger, puoi attivare o disattivare la versione canary. Le versioni canary sono disattivate per impostazione predefinita.

Quando abilitare snapshot canary e punti di log

Per proteggere i carichi di lavoro critici di deployment e critici, abilita le versioni canary durante il debug di questi carichi di lavoro.

Se hai una singola istanza, puoi comunque eseguire il debug con la versione canary abilitata, ma l'istanza singola viene eseguita senza eliminare lo snapshot o il punto di log.

Quando non abilitare snapshot e punti di log canary

Non consentire la canary su carichi di lavoro con un tempo di esecuzione inferiore a 40 secondi, ad esempio job che utilizzano Cloud Functions.

Non attivare la versione canary se vuoi un ciclo di attivazione degli snapshot più rapido.

Per configurare l'agente Debugger in modo che non esegua snapshot canary e punti di log, vai alle istruzioni di installazione della piattaforma Google Cloud che stai utilizzando.

App Engine

1. Usa npm per installare il pacchetto:

   npm install --save @google-cloud/debug-agent
   

2. Attiva l'agente nella parte superiore dello script o del punto di ingresso principale dell'app (ma dopo @google/cloud-trace se lo utilizzi anche):

   Per eseguire il debug con la versione canary attivata:

   require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
   

   Per eseguire il debug con la versione canary non abilitata, imposta enableCanary su false:

   require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
   

Il debugger è ora pronto per essere utilizzato con la tua app.

Per fare in modo che la pagina Debug nella console Google Cloud mostri automaticamente il codice sorgente corrispondente all'app di cui è stato eseguito il deployment, consulta la sezione Selezionare il codice sorgente automaticamente.

Google Kubernetes Engine

GCLOUD

Per attivare Debugger utilizzando gcloud, completa i seguenti passaggi:

1. Crea il cluster con uno dei seguenti ambiti di accesso:

   • https://www.googleapis.com/auth/cloud-platform concede al cluster l'accesso a tutte le API Google Cloud.

   • https://www.googleapis.com/auth/cloud_debugger concede al cluster l'accesso solo all'API Debugger. Utilizza questo ambito di accesso per proteggere la sicurezza del tuo cluster.

   gcloud container clusters create example-cluster-name \
          --scopes=https://www.googleapis.com/auth/cloud_debugger
   

   Nota: non è possibile modificare gli ambiti di accesso di un cluster dopo la creazione.

2. Aggiungi la seguente riga al tuo Dockerfile per aggiungere l'agente Debugger:

   RUN  npm install --save @google-cloud/debug-agent
   

3. Attiva l'agente nella parte superiore dello script o del punto di ingresso principale dell'app (ma dopo @google/cloud-trace se lo utilizzi anche):

   Per eseguire il debug con la versione canary attivata:

   require('@google-cloud/debug-agent').start({
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Per eseguire il debug con la versione canary non abilitata, imposta enableCanary su false:

   enableCanary: false
   

   Dove:

   • SERVICE è un nome per la tua app, ad esempio MyApp, Backend o Frontend.
   • VERSION è una versione, ad esempio v1.0, build_147 o v20170714.

   Ti consigliamo di impostarle dalle variabili di ambiente, in modo da non dover cambiare il codice sorgente con ogni deployment.

Il debugger è ora pronto per l'uso durante il deployment dell'app containerizzata.

Per fare in modo che la pagina Debug nella console Google Cloud mostri automaticamente il codice sorgente corrispondente all'app di cui è stato eseguito il deployment, consulta la sezione Selezionare il codice sorgente automaticamente.

CONSOLE

Per attivare Debugger utilizzando Google Cloud Console, completa i seguenti passaggi:

1. Nella sezione Pool di nodi, seleziona Sicurezza, quindi seleziona Imposta l'accesso per ogni API.

2. Abilita Debugger.

   

3. (Facoltativo) Seleziona Consenti l'accesso completo a tutte le API di Cloud.

4. Aggiungi la seguente riga al tuo Dockerfile per aggiungere l'agente Debugger:

       RUN  npm install --save @google-cloud/debug-agent
   

5. Attiva l'agente nella parte superiore dello script o del punto di ingresso principale dell'app (ma dopo @google/cloud-trace se lo utilizzi anche):

   Per eseguire il debug con la versione canary attivata:

   require('@google-cloud/debug-agent').start({
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Per eseguire il debug con la versione canary non abilitata, imposta enableCanary su false:

   enableCanary: false
   

   Dove:

   • SERVICE è un nome per la tua app, ad esempio MyApp, Backend o Frontend.
   • VERSION è una versione, ad esempio v1.0, build_147 o v20170714.

   Ti consigliamo di impostarle dalle variabili di ambiente, in modo da non dover cambiare il codice sorgente con ogni deployment.

Compute Engine

1. Assicurati che le istanze di Compute Engine vengano create con l'opzione dell'ambito di accesso Consenti l'accesso completo a tutte le API di Cloud o hanno uno dei seguenti ambiti di accesso:

   • https://www.googleapis.com/auth/cloud-platform
   • https://www.googleapis.com/auth/cloud_debugger

2. Usa npm per installare il pacchetto:

   npm install --save @google-cloud/debug-agent
   

3. Attiva l'agente nella parte superiore dello script o del punto di ingresso principale dell'app (ma dopo @google/cloud-trace se lo utilizzi anche):

   Per eseguire il debug con la versione canary attivata:

   require('@google-cloud/debug-agent').start({
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Per eseguire il debug con la versione canary non abilitata, imposta enableCanary su false:

   enableCanary: false
   

   Dove:

   • SERVICE è un nome per la tua app, ad esempio MyApp, Backend o Frontend.
   • VERSION è una versione, ad esempio v1.0, build_147 o v20170714.

   Ti consigliamo di impostarle dalle variabili di ambiente, in modo da non dover cambiare il codice sorgente con ogni deployment.

Il debugger è ora pronto per essere utilizzato con la tua app.

Per fare in modo che la pagina Debug nella console Google Cloud mostri automaticamente il codice sorgente corrispondente all'app di cui è stato eseguito il deployment, consulta la sezione Selezionare il codice sorgente automaticamente.

Cloud Run e Cloud Run for Anthos

1. Usa npm per installare il pacchetto:

   npm install --save @google-cloud/debug-agent
   

2. Attiva l'agente nella parte superiore dello script o del punto di contatto principale dell'app (ma dopo @google/cloud-trace se la utilizzi anche):

   Per eseguire il debug con la versione canary attivata:

   require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
   

   Per eseguire il debug con la versione canary non abilitata, imposta enableCanary su false:

   enableCanary: false
   

   Il debugger è ora pronto per l'uso durante il deployment dell'app.

Locale e altrove

1. Usa npm per installare il pacchetto:

   npm install --save @google-cloud/debug-agent
   

2. Scarica le credenziali dell'account di servizio.

   Per utilizzare l'agente Cloud Debugger per Node.js sulle macchine non ospitate da Google Cloud, l'agente deve utilizzare le credenziali di un account di servizio Google Cloud per eseguire l'autenticazione con il servizio Cloud Debugger.

   Utilizza la pagina Account di servizio di Google Cloud Console per creare un file delle credenziali per un account di servizio esistente o nuovo. L'account di servizio deve avere almeno il ruolo Cloud Debugger Agent.

3. Configura e abilita l'agente con le credenziali scaricate:

   Per eseguire il debug con la versione canary attivata:

   require('@google-cloud/debug-agent').start({
     projectId: 'your-project-id',
     keyFilename: '/path/to/key.json',
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Per eseguire il debug con la versione canary non abilitata, imposta enableCanary su false:

   enableCanary: false
   

   Dove:

   • SERVICE è un nome per la tua app, ad esempio MyApp, Backend o Frontend.
   • VERSION è una versione, ad esempio v1.0, build_147 o v20170714.

   Ti consigliamo di impostarle dalle variabili di ambiente, in modo da non dover cambiare il codice sorgente con ogni deployment.

Il debugger è ora pronto per essere utilizzato con la tua app.

Nella pagina Debug nella console Google Cloud puoi visualizzare i file di origine locali, senza caricamento, per lo sviluppo locale. Consulta Selezionare il codice sorgente manualmente.

Nota: puoi trovare il codice e la documentazione dell'agente Debugger su GitHub.