Configurer Cloud Debugger pour Python

Présentation

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 for Anthos	VM et conteneurs s'exécutant ailleurs	Cloud Functions

Configurer Cloud Debugger

Pour configurer Cloud Debugger, procédez comme suit :

Vérifiez que l'API Cloud Debugger est activée pour votre projet.
Installez et configurez le Debugger sur l'environnement de calcul que vous utilisez.
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

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.

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 :

Assurez-vous que votre fichier app.yaml contient les éléments suivants :
```
runtime: python37
or
runtime: python38
```
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
```
Ajoutez google-python-cloud-debugger au fichier requirements.txt.
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.

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é.

Assurez-vous que les instances de VM dans l'environnement flexible App Engine exécutent :
- Une image Linux Debian 64 bits
- Python 3
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.
Ajoutez google-python-cloud-debugger au fichier requirements.txt.
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
```
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.

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 :

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.
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
```
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 Google 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 Google Cloud Console, procédez comme suit:

Dans la section Pools de nœuds, sélectionnez Sécurité, puis cliquez sur Définir l'accès pour chaque API.
Activez Debugger.
Facultatif : Sélectionnez Autoriser l'accès complet à l'ensemble des API Cloud.
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
```
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
```

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

Compute Engine

Assurez-vous que les instances de VM Compute Engine exécutent :
- Une image Linux Debian 64 bits
- Python 3
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
Téléchargez l'agent Debugger.

Le moyen le plus simple d'installer Debugger pour Python est d'utiliser pip :
```
pip install google-python-cloud-debugger
```
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
```
Remarque : Lors de l'exécution de Debugger en tant que module, la valeur de --breakpoint_enable_canary est une chaîne. Toute valeur autre que True est traitée comme False.

Remplacez les espaces réservés dans la commande comme suit :
- [MODULE] est le nom de votre application.
  Conjointement à la version, le nom permet d'identifier la cible de débogage sur la page Débogage de Google 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 Google 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 Google Cloud Console, consultez la page Sélectionner automatiquement le code source.

Cloud Run et Cloud Run pour Anthos

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

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

Environnement local et autre

Assurez-vous que le poste de travail exécute :
- Une image Linux Debian 64 bits
- Python 3
Téléchargez l'agent Debugger.

Le moyen le plus simple d'installer Debugger pour Python est d'utiliser pip :
```
pip install google-python-cloud-debugger
```
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.

Utilisez la page Comptes de service Google 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.
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
```
Remarque : Lors de l'exécution de Debugger en tant que module, la valeur de --breakpoint_enable_canary est une chaîne. Toute valeur autre que True est traitée comme False.

Remplacez les espaces réservés dans la commande comme suit :
- [MODULE] est le nom de votre application.
  Conjointement à la version, le nom permet d'identifier la cible de débogage sur la page Débogage de Google 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 Google 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 Google Cloud Console peut afficher les fichiers sources locaux, sans les importer, pour les développements en local. Consultez la page Sélectionner manuellement le code source pour en savoir plus.