Configurer Cloud Debugger pour Node.js

Présentation

Remarque : Cloud Debugger est compatible avec les versions Node.js 9 et ultérieures. Nous vous recommandons d'utiliser la version LTS (Long Term Support).

Cette page explique comment configurer l'environnement et l'application Node.js pour qu'ils utilisent Cloud Debugger. Pour certains environnements, vous devez spécifier explicitement le champ d'application d'accès pour permettre à l'agent Cloud Debugger d'envoyer des données. Nous vous recommandons de définir le niveau d'accès le plus large possible, puis d'utiliser Identity and Access Management pour limiter l'accès. Conformément à cette bonne pratique, définissez le niveau d'accès sur toutes les API Cloud avec l'option cloud-platform.

Versions de langages et environnements de calcul

Cloud Debugger est disponible pour les versions Node.js 1.9 et ultérieures dans les environnements de calcul suivants :

Environnement standard App Engine	Environnement flexible App Engine	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	VM et conteneurs s'exécutant ailleurs	Cloud Functions

Bêta {/10)

Cette bibliothèque est régie par les Conditions des offres de pré-DG des conditions d'utilisation de Google Cloud. Les bibliothèques de pré-DG peuvent ne pas être entièrement compatibles, et les modifications apportées aux bibliothèques de pré-DG risquent de ne pas être compatibles avec les autres versions de pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Configurer Cloud Debugger

Pour configurer Cloud Debugger, procédez comme suit :

1. Vérifiez que l'API Cloud Debugger est activée pour votre projet.

2. Installez et configurez le Debugger sur l'environnement de calcul que vous utilisez.

3. Sélectionnez votre code source.

   Remarque : Pour des raisons de performances, l'agent Cloud Debugger pour Node.js ne permet pas d'ajouter des instantanés ou des points de journalisation dans les fichiers du répertoire node_modules.

Vérifier que l'API Cloud Debugger est activée

Pour commencer à utiliser Cloud Debugger, assurez-vous que l'API Cloud Debugger est activée. Cloud Debugger est activé par défaut pour la plupart des projets.
Activer l'API Cloud Debugger

Remarque : Cloud Debugger est gratuit. Vous devez toutefois disposer d'un projet Google Cloud avec la facturation activée pour pouvoir utiliser Cloud Debugger.

Instantanés et points de journalisation Canary

Pour empêcher le chargement simultané des instantanés et des points de journalisation sur toutes les instances en cours, et entraîner la suppression de la tâche en raison d'un bug potentiel dans l'Agent Debugger, activez le mode Canary pour le Agent Debugger Lorsque le mode Canary est activé, un instantané ou un point de journalisation est appliqué à un sous-ensemble d'instances en cours d'exécution et Debugger vérifie que l'instantané ou le point de journalisation n'affecte pas ces instances. Une fois la vérification terminée, l'instantané ou le point de journalisation est appliqué à toutes les instances.

Remarque:La version Canary est disponible pour l'agent Debugger Node.js version 5.1.0 et ultérieure.

Pour apprendre à utiliser le débogueur en mode Canary, accédez aux pages Instantanés de débogage et Points de journalisation de débogage.

Activer les instantanés et points de journalisation Canary

Lorsque vous installez la dernière version de l'Agent Debugger, vous avez la possibilité d'activer ou de désactiver la version Canary. La version Canary est désactivée par défaut.

Quand activer les instantanés et les points de journalisation Canary

Pour protéger les charges de travail de déploiement et de production critiques, activez la version Canary lors du débogage de ces charges de travail.

Si vous disposez d'une seule instance, vous pouvez toujours déboguer en utilisant la version Canary, mais votre instance unique s'exécute sans dupliquer l'instantané ou le point de journalisation.

Quand ne pas activer les instantanés et points de journalisation Canary

N'activez pas la fonctionnalité Canary sur des charges de travail dont la durée d'exécution est inférieure à 40 secondes, par exemple les tâches utilisant Cloud Functions.

N'activez pas la version Canary si vous souhaitez un cycle de déclenchement d'instantanés plus rapide.

Pour configurer l'Agent Debugger de manière à ne pas utiliser les instantanés et les points de journalisation Canary, consultez les instructions d'installation de la plate-forme Google Cloud que vous utilisez.

App Engine

1. Installez le package à l'aide de npm :

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

2. Activez l'agent dans la partie supérieure du script principal ou du point d'entrée de votre application (mais après @google/cloud-trace si vous l'utilisez également) :

   Pour procéder au débogage avec la version Canary activée, procédez comme suit :

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

   Pour déboguer avec la version Canary non activée, définissez enableCanary sur false :

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

Le débogueur est maintenant prêt à être utilisé avec l'application.

Pour découvrir comment afficher automatiquement le code source correspondant à l'application déployée sur la page "Débogage" de Google Cloud Console, consultez la page Sélectionner automatiquement le code source.

Google Kubernetes Engine

GCLOUD

Pour activer Debugger à l'aide de gcloud, procédez comme suit :

1. Créez votre cluster avec l'un des niveaux d'accès suivants :

   • https://www.googleapis.com/auth/cloud-platform permet à votre cluster d'accéder à toutes les API Google Cloud.

   • https://www.googleapis.com/auth/cloud_debugger ne permet à votre cluster d'accéder qu'à l'API Debugger. Utilisez ce niveau d'accès pour renforcer la sécurité de votre cluster.

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

   Remarque : Vous ne pouvez pas modifier les champs d'application d'accès d'un cluster après sa création.

2. Incluez la ligne suivante dans le fichier Dockerfile pour ajouter l'agent Debugger :

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

3. Activez l'agent dans la partie supérieure du script principal ou du point d'entrée de votre application (mais après @google/cloud-trace si vous l'utilisez également) :

   Pour procéder au débogage avec la version Canary activée, procédez comme suit :

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

   Pour déboguer avec la version Canary non activée, définissez enableCanary sur false :

   enableCanary: false
   

   Où :

   • SERVICE est le nom de votre application, tel que MyApp, Backend ou Frontend.
   • VERSION est une version, telle que v1.0, build_147 ou v20170714.

   Nous vous recommandons de définir ces éléments à partir de variables d'environnement. Ainsi, vous n'aurez pas à modifier le code source à chaque déploiement.

Le débogueur est maintenant prêt à être utilisé lors du déploiement de votre application en conteneur.

Pour découvrir comment afficher automatiquement le code source correspondant à l'application déployée sur la page "Débogage" de Google Cloud Console, consultez la page Sélectionner automatiquement le code source.

CONSOLE

Pour activer Debugger à l'aide de Google Cloud Console, procédez comme suit:

1. Dans la section Pools de nœuds, sélectionnez Sécurité, puis cliquez sur Définir l'accès pour chaque API.

2. Activez Debugger.

   

3. Facultatif : Sélectionnez Autoriser l'accès complet à l'ensemble des API Cloud.

4. Incluez la ligne suivante dans le fichier Dockerfile pour ajouter l'agent Debugger :

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

5. Activez l'agent dans la partie supérieure du script principal ou du point d'entrée de votre application (mais après @google/cloud-trace si vous l'utilisez également) :

   Pour procéder au débogage avec la version Canary activée, procédez comme suit :

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

   Pour déboguer avec la version Canary non activée, définissez enableCanary sur false :

   enableCanary: false
   

   Où :

   • SERVICE est le nom de votre application, tel que MyApp, Backend ou Frontend.
   • VERSION est une version, telle que v1.0, build_147 ou v20170714.

   Nous vous recommandons de définir ces éléments à partir de variables d'environnement. Ainsi, vous n'aurez pas à modifier le code source à chaque déploiement.

Compute Engine

1. Assurez-vous que l'option de champ d'application d'accès Autoriser l'accès complet à toutes les API Cloud est activée pour vos instances Compute Engine, ou que ces dernières disposent de l'un des champs d'application d'accès suivants :

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

2. Installez le package à l'aide de npm :

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

3. Activez l'agent dans la partie supérieure du script principal ou du point d'entrée de votre application (mais après @google/cloud-trace si vous l'utilisez également) :

   Pour procéder au débogage avec la version Canary activée, procédez comme suit :

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

   Pour déboguer avec la version Canary non activée, définissez enableCanary sur false :

   enableCanary: false
   

   Où :

   • SERVICE est le nom de votre application, tel que MyApp, Backend ou Frontend.
   • VERSION est une version, telle que v1.0, build_147 ou v20170714.

   Nous vous recommandons de définir ces éléments à partir de variables d'environnement. Ainsi, vous n'aurez pas à modifier le code source à chaque déploiement.

Le débogueur est maintenant prêt à être utilisé avec l'application.

Pour découvrir comment afficher automatiquement le code source correspondant à l'application déployée sur la page "Débogage" de Google Cloud Console, consultez la page Sélectionner automatiquement le code source.

Cloud Run et Cloud Run pour Anthos

1. Installez le package à l'aide de npm :

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

2. Activez l'agent dans la partie supérieure du script principal ou du point d'entrée de votre application (mais après @google/cloud-trace si vous l'utilisez également) :

   Pour procéder au débogage avec la version Canary activée, procédez comme suit :

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

   Pour déboguer avec la version Canary non activée, définissez enableCanary sur false :

   enableCanary: false
   

   Le débogueur est maintenant prêt à être utilisé lors du déploiement de votre application en conteneur.

Environnement local et autre

1. Installez le package à l'aide de npm :

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

2. Téléchargez les identifiants du compte de service.

   Pour que vous puissiez utiliser l'agent Cloud Debugger pour Node.js sur des machines qui ne sont pas hébergées par Google Cloud, celui-ci doit s'authentifier auprès du service Cloud Debugger à l'aide des informations d'identification du compte de service Google Cloud.

   Accédez à la page Comptes de service de Google Cloud Console afin de créer un fichier d'identifiants pour un compte de service nouveau ou existant. Ce compte doit au moins disposer du rôle Cloud Debugger Agent.

3. Configurez et activez l'agent avec les identifiants téléchargés.

   Pour procéder au débogage avec la version Canary activée, procédez comme suit :

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

   Pour déboguer avec la version Canary non activée, définissez enableCanary sur false :

   enableCanary: false
   

   Où :

   • SERVICE est le nom de votre application, tel que MyApp, Backend ou Frontend.
   • VERSION est une version, telle que v1.0, build_147 ou v20170714.

   Nous vous recommandons de définir ces éléments à partir de variables d'environnement. Ainsi, vous n'aurez pas à modifier le code source à chaque déploiement.

Le débogueur est maintenant prêt à être utilisé avec l'application.

La page "Débogage" de Google Cloud Console peut afficher les fichiers sources locaux, sans les importer, à des fins de développement local. Consultez la page Sélectionner manuellement le code source.

Remarque : Vous trouverez le code et la documentation de l'agent Debugger sur GitHub.