Configurer Cloud Debugger pour Python

Aperçu

Cette page explique comment configurer l'environnement et l'application Python 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 Python 3 dans les environnements de calcul suivants :

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

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.

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

Instantanés et points de journalisation Canary

L'Agent Debugger pour Phyton peut utiliser des instantanés et des points de journalisation Canary chaque fois que vous définissez un instantané ou un point de journalisation.

L'Agent Debugger peut envoyer des instantanés et des points de journalisation afin de protéger les tâches volumineuses contre tout bug potentiel dans l'Agent Debugger, qui peut supprimer la tâche entière lorsqu'un instantané ou un point de journalisation est appliqué.

Pour remédier à ce problème, les instantanés et les points de journalisation du système de débogage sur un sous-ensemble de vos instances en cours d'exécution sont définis à chaque fois. Une fois que Debugger a vérifié l'instantané ou le point de journalisation n'affecte pas vos instances en cours d'exécution, Debugger applique ensuite l'instantané ou le point de journalisation à toutes les instances.

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.

Environnement standard App Engine

Python 3.7 ou Python 3.8

Si vous utilisez Python 3.7 ou Python 3.8, vous devez activer manuellement l'Agent Debugger en procédant comme suit :

  1. Assurez-vous que votre fichier app.yaml contient les éléments suivants :

    runtime: python37
    or
    runtime: python38
    
  2. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django (version 1.* uniquement).

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

     breakpoint_enable_canary=False
    
  3. Ajoutez google-python-cloud-debugger au fichier requirements.txt.

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

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

Environnement flexible App Engine

Vous pouvez utiliser Debugger avec l'environnement d'exécution Python d'App Engine ou un environnement d'exécution personnalisé.

  1. Assurez-vous que les instances de VM dans l'environnement flexible App Engine exécutent :

    • Une image Linux Debian 64 bits
    • Python 3
  2. Assurez-vous que votre fichier app.yaml contient les lignes suivantes :

    runtime: python
    env: flex
    

    Si vous utilisez un environnement d'exécution personnalisé, saisissez runtime: custom.

  3. Ajoutez google-python-cloud-debugger au fichier requirements.txt.

  4. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django (version 1.* uniquement).

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

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

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

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
    
  2. Ajoutez le package Debugger à votre application :

    Si vous utilisez un fichier requirements.txt, ajoutez la ligne suivante :

      google-python-cloud-debugger
    

    Si vous utilisez un fichier Dockerfile, ajoutez la ligne suivante :

      RUN pip install google-python-cloud-debugger
    
  3. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django :

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

      try:
        import googleclouddebugger
        googleclouddebugger.enable(
          breakpoint_enable_canary=True
        )
      except ImportError:
        pass
    

    Pour déboguer avec la version Canary NON activée, définissez le paramètre breakpoint_enable_canary sur False :

      breakpoint_enable_canary=False
    

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

Le débogueur est maintenant prêt à être utilisé.

CONSOLE

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

  1. Après avoir sélectionné le type de cluster, cliquez sur More options (Plus d'options) dans le volet Node pools (Pools de nœuds) :

    Champ du pool de nœuds comprenant un rectangle rouge entourant le bouton

  2. Sélectionnez l'une des options suivantes dans le volet Sécurité :

    • Autoriser l'accès complet à l'ensemble des API Cloud

    • Définir l'accès pour chaque API, puis sélectionner Activé pour Cloud Debugger

  3. Ajoutez le package Debugger à votre application :

    Si vous utilisez un fichier requirements.txt, ajoutez la ligne suivante :

    google-python-cloud-debugger
    

    Si vous utilisez un fichier Dockerfile, ajoutez la ligne suivante :

    RUN pip install google-python-cloud-debugger
    
  4. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django :

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

    breakpoint_enable_canary=False
    

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

Le débogueur est maintenant prêt à être utilisé.

Compute Engine

  1. Assurez-vous que les instances de VM Compute Engine exécutent :

    • Une image Linux Debian 64 bits
    • Python 3
  2. Assurez-vous que l'option de niveau d'accès Autoriser l'accès complet à l'ensemble des API Cloud est activée pour les instances de VM Compute Engine, ou qu'elles disposent de l'un des niveaux d'accès suivants :

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  3. Téléchargez l'agent Debugger.

    Le moyen le plus simple d'installer Debugger pour Python est d'utiliser [pip][pip] :

    pip install google-python-cloud-debugger
    
  4. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django :

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        module='[MODULE]',
        version='[VERSION]'
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

    breakpoint_enable_canary=False
    

    Si vous ne pouvez pas modifier le code, exécutez l'agent Debugger en tant que module.

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

    python -m googleclouddebugger \
          --module=[MODULE] \
          --version=[VERSION] \
          --breakpoint_enable_canary=True
          -- \
          myapp.py
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

    breakpoint_enable_canary=False
    

    Remplacez les espaces réservés dans la commande comme suit :

    • [MODULE] est le nom de l'application.
      Conjointement à la version, le nom permet d'identifier la cible de débogage sur la page Débogage de Cloud Console.
      Exemples : MyApp, Backend ou Frontend.
    • [VERSION] correspond à la version de l'application (par exemple, l'ID du build).
      La page Débogage de Cloud Console affiche la version en cours d'exécution au format [MODULE] - [VERSION].
      Exemples de valeurs : v1.0, build_147 ou v20170714.

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 Cloud Console, consultez la page Sélectionner automatiquement le code source.

Cloud Run et Cloud Run pour Anthos sur Google Cloud

  1. Package Python.

    Si vous utilisez un fichier requirements.txt, ajoutez la ligne suivante :

    google-python-cloud-debugger
    

    Si ce n'est pas le cas, ajoutez la ligne suivante au fichier Dockerfile :

    RUN pip install google-python-cloud-debugger
    
  2. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django :

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    
    except ImportError:
      pass
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

    breakpoint_enable_canary=False
    

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

Le débogueur est maintenant prêt à être utilisé.

Environnement local et autre

  1. Assurez-vous que le poste de travail exécute :

    • Une image Linux Debian 64 bits
    • Python 3
  2. Téléchargez l'agent Debugger.

    Le moyen le plus simple d'installer Debugger pour Python est d'utiliser [pip][pip]{: .external} :

    pip install google-python-cloud-debugger
    
  3. Téléchargez les identifiants du compte de service.

    Pour que vous puissiez utiliser l'agent Cloud Debugger pour Python 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.

    Suivez les instructions de la page Comptes de service de Cloud Console pour 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.

    Placez le fichier JSON de compte de service avec l'agent Cloud Debugger pour Python.

  4. Ajoutez les lignes suivantes le plus tôt possible dans votre code d'initialisation, comme dans la fonction principale, ou dans manage.py si vous utilisez le framework Web Django :

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

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
          module='[MODULE]',
          version='[VERSION]',
          breakpoint_enable_canary=True
          service_account_json_file='/opt/cdbg/gcp-svc.json')
    except ImportError:
      pass
    

    Pour déboguer avec la version Canary NON activée, définissez le paramètre breakpoint_enable_canary sur False :

    breakpoint_enable_canary=False
    

    Si vous ne pouvez pas modifier le code, exécutez l'agent Debugger en tant que module.

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

    python \
        -m googleclouddebugger \
        --module=[MODULE] \
        --version=[VERSION] \
        --breakpoint_enable_canary=True
        --service_account_json_file=/opt/cdbg/gcp-svc.json \
        -- \
        myapp.py
    

    Pour déboguer avec la version Canary non activée, définissez le paramètre breakpoint_enable_canary sur False :

    breakpoint_enable_canary=False
    

    Remplacez les espaces réservés dans la commande comme suit :

    • [MODULE] est le nom de l'application.
      Conjointement à la version, le nom permet d'identifier la cible de débogage sur la page Débogage de Cloud Console.
      Exemples : MyApp, Backend ou Frontend.
    • [VERSION] correspond à la version de l'application (par exemple, l'ID du build).
      La page Débogage de Cloud Console affiche la version en cours d'exécution au format [MODULE] - [VERSION].
      Exemples de valeurs : v1.0, build_147 ou v20170714.
    • Vous pouvez utiliser la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS au lieu de spécifier service_account_json_file.

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

La page Débogage de Cloud Console peut afficher les fichiers source locaux, sans les importer, pour les développements en local. Consultez la page Sélectionner manuellement le code source pour en savoir plus.