Cloud Debugger est obsolète et sera arrêté le 31 mai 2023. Pour en savoir plus, consultez la page Abandons et les notes de version.

Instantanés de débogage

Après avoir déployé ou démarré votre application, vous pouvez ouvrir Cloud Debugger dans Google Cloud Console. Debugger vous permet d'enregistrer et d'inspecter la pile d'appel et les variables locales dans votre application sans l'arrêter ni la ralentir.

Accédez à la page Débogage de Google Cloud Console pour utiliser Debugger.

Avant de commencer

Debugger peut être utilisé avec ou sans accès au code source de votre application. Si votre code source n'est pas disponible, consultez la section Prendre un instantané de débogage ci-dessous pour en savoir plus sur la saisie manuelle du nom de fichier et du numéro de ligne.

Pour accéder au code source stocké localement ou dans un dépôt Git, vous devrez peut-être sélectionner un emplacement de code source.

Instantanés

Les instantanés enregistrent les variables locales et la pile d'appel au niveau d'une ligne spécifique dans le code source de votre application. Vous pouvez spécifier certaines conditions et certains emplacements pour renvoyer un instantané des données de votre application et l'afficher en détail pour déboguer cette dernière.

Agent Debugger avec version Canary

Une fois que vous avez défini un instantané, l'Agent Debugger le teste sur un sous-ensemble de vos instances. Une fois que l'Agent Debugger a vérifié que l'instantané peut s'exécuter correctement, il est appliqué à toutes vos instances. Cela prend environ 40 secondes.

Après ce processus, lorsque l'instantané est déclenché, les résultats apparaissent dans les volets Variables et Pile d'appel. Si l'instantané est déclenché dans les 40 secondes suivant sa définition, les résultats de ces instances sur lesquels l'instantané Canary s'appliquent seront appliqués.

L'Agent Debugger met en œuvre plusieurs stratégies pour réduire la latence générée par l'enregistrement des données.

Le texte suivant s'affiche lorsque l'agent Debugger est en version Canary :

"Vérification du point d'arrêt d'un sous-ensemble d'instances d'application."

L'Agent Debugger est des instances en version Canary

Pour savoir comment procéder en cas de défaillance de l'Agent Debugger en mode Canary, consultez la section Dépannage de la page Débogage des instantanés.

Pour savoir quelles versions de l'Agent Debugger ont des fonctionnalités Canary, consultez les pages spécifiques à chaque langage.

Agent Debugger sans version Canary

Lorsque vous utilisez l'Agent Debugger sans version Canary et définissez un instantané, il s'applique à toutes les instances en cours d'exécution de votre application. La première fois qu'une instance exécute le code à l'emplacement de l'instantané, l'Agent Debugger prend un instantané et le met à disposition pour consultation. L'Agent Debugger met en œuvre plusieurs stratégies pour réduire la latence générée par l'enregistrement des données.

Prendre un instantané de débogage

Console

Cliquez sur le numéro d'une ligne du code source pour prendre un instantané à cet emplacement.

  1. Assurez-vous que le panneau Instantané est sélectionné.
  2. Sélectionnez le fichier contenant le code source. Le contenu du fichier sélectionné s'affiche dans le panneau central.

  3. Cliquez sur le numéro de ligne de l'emplacement du code source.

    Rechercher un emplacement d'instantané.

Vous pouvez sélectionner plusieurs lignes pour définir plusieurs emplacements d'instantanés sur un fichier.

Consultez la section Options de code source pour découvrir d'autres façons de charger votre code source dans Debugger.

Si aucun code source n'est disponible, vous pouvez saisir manuellement le fichier et la ligne au format "fichier:ligne" dans le panneau Instantané :

Définir manuellement un emplacement d'instantané.

gcloud

Pour définir un emplacement d'instantané à partir de la ligne de commande :

gcloud debug snapshots create LOCATION

Où :

  • LOCATION est le nom de fichier et la ligne dans lesquels définir l'instantané. Cette valeur est au format "FICHIER:LIGNE", où FICHIER peut être le nom de fichier seul ou le nom de fichier précédé d'un nombre suffisant de composants de chemin d'accès afin de le différencier des autres fichiers portant le même nom. Le fait de fournir un nom de fichier qui n'est pas unique dans la cible de débogage est considéré comme une erreur.

Conditions d'instantané (facultatif)

Une condition d'instantané est une expression simple dans le langage de l'application (Go, Java et Python sont acceptés) qui doit prendre la valeur "true" pour que l'instantané soit pris. Les conditions d'instantané sont évaluées chaque fois que la ligne est exécutée par une instance, et ce, jusqu'à ce que la condition prenne la valeur "true" ou que l'instantané arrive à expiration.

L'utilisation de conditions d'instantané est facultative.

La condition est une expression booléenne complète pouvant inclure des opérateurs logiques :

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

Console

Pour spécifier la condition, créez un instantané. Dans le champ Condition, saisissez une condition, puis sélectionnez Mettre à jour. Si la condition renvoie la valeur "true", l'instantané est déclenché.

Définir une condition d'instantané.

gcloud

Les conditions sont spécifiées à l'aide de l'indicateur --condition de snapshots create :

gcloud debug snapshots create LOCATION --condition="ultimateAnswer <= 42 && foo==bar"

Vous pouvez exprimer les conditions à l'aide des fonctionnalités de langage suivantes :

Java

La plupart des expressions Java sont compatibles, y compris les suivantes :
  • Variables locales : a == 8.
  • Opérations numériques et booléennes: x + y < 20.
  • Champs d'instance et champs statiques : this.counter == 20, this.myObj.isShutdown, myStatic ou com.mycompany.MyClass.staticMember.
  • Comparaisons de chaînes avec l'opérateur d'égalité : myString == "abc"
  • Appels de fonctions. Seules les fonctions en lecture seule peuvent être utilisées. Par exemple, la fonction StringBuilder.indexOf() est acceptée, mais StringBuilder.append() ne l'est pas.
  • Diffusion de type, avec des types complets : ((com.myprod.ClassImpl) myInterface).internalField

Les fonctionnalités de langage suivantes ne sont pas compatibles :

  • Déballage de types numériques, tels que Integer. Utilisez myInteger.value à la place.

Python

La plupart des expressions Python sont compatibles, y compris les suivantes :
  • Lecture des variables locales et globales
  • Lecture à partir de tableaux, de listes, de tranches de tableau, de dictionnaires et d'objets
  • Appel de méthodes simples

Les fonctionnalités de langage suivantes ne sont pas compatibles :

  • Appel de fonctions qui allouent de nouveaux objets ou utilisent des constructions complexes
  • Création d'objets dans l'expression

Accéder

La plupart des syntaxes d'expressions Go sont compatibles, y compris les suivantes :
  • Lecture des variables locales et globales
  • Lecture à partir de tableaux, de tranches de tableau, de cartes et de structures

Les fonctionnalités de langage suivantes ne sont pas compatibles :

  • Lecture à partir des valeurs d'interface
  • Conversion de type et valeurs littérales composites
  • Appels de fonctions autres que len.

Expressions (facultatif)

La fonctionnalité d'expressions de Debugger vous permet d'évaluer des expressions complexes ou de parcourir des hiérarchies d'objets lors de la prise d'un instantané. Les expressions sont compatibles avec les mêmes fonctionnalités de langage que les conditions d'instantané décrites ci-dessus.

L'utilisation d'expressions est facultative.

Les expressions sont généralement utilisées aux fins suivantes :

  • Afficher les variables statiques ou globales qui ne font pas partie de l'ensemble de variables locales
  • Afficher facilement les variables de membre profondément imbriquées sans avoir à développer chaque fois une variable locale dans le panneau du débogueur
  • Éviter les calculs mathématiques répétitifs Vous pouvez par exemple calculer une durée en secondes à l'aide de l'expression (endTimeMillis - startTimeMillis) / 1000.0.

Pour ajouter une expression :

Console

  1. Saisissez l'expression dans le champ Expression. Vous pouvez ajouter autant d'expressions que nécessaire.
  2. Sélectionnez Recréer.

Le résultat de l'expression est affiché lorsque l'instantané est pris.

Définir une expression.

gcloud

Les expressions sont définies à l'aide de l'indicateur --expression de snapshots create :

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

Afficher un instantané

Console

Les données d'instantané apparaissent dans Debugger lorsque l'application exécute le code source à l'emplacement que vous avez spécifié. Les variables d'instance et les variables locales apparaissent dans la section Variables du panneau. La trace de la pile apparaît dans la section Call Stack (Pile des appels) du panneau.

Afficher l'instantané.

Vous pouvez examiner la valeur des variables locales au moment où l'instantané a été pris et explorer les structures de données plus profondes. Vous pouvez également cliquer sur n'importe quel cadre de pile d'appels et examiner les variables locales à ce niveau de la pile.

Si vous avez défini plusieurs emplacements d'instantanés sur un fichier, ou si vous souhaitez afficher les instantanés que vous avez déjà pris, développez le panneau Historique des instantanés :

Afficher l'historique d'un instantané.

gcloud

Pour récupérer l'URL Google Cloud Console d'un instantané à partir de la ligne de commande:

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE  HighScoreService.java:105                             53bd97d4-b6c6-74fc  https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

Copiez la valeur de la colonne VIEW et collez-la dans votre navigateur pour afficher l'instantané dans Google Cloud Console.

Pour afficher des données d'instantané détaillées à partir de la ligne de commande, exécutez la commande suivante :

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

La commande describe renvoie la trace de la pile et les valeurs des variables locales. Ces données sont principalement destinées à être exploitées par un ordinateur plutôt que par un humain.

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

Reprendre un instantané

Un instantané n'est pris qu'une seule fois. Si vous souhaitez enregistrer un autre instantané des données de votre application au même emplacement, vous pouvez le reprendre manuellement.

Console

Pour recréer un instantané, sélectionnez Recréer :

Bouton "Recréer" sélectionné.

Le nouvel instantané est ajouté au panneau Historique des instantanés. Les anciens instantanés de cette ligne sont accessibles depuis le panneau Historique des instantanés ou en cliquant sur le marqueur du numéro de ligne concerné :

Anciens instantanés affichés sur le marqueur de ligne.

gcloud

Pour reprendre un instantané à partir de la ligne de commande, répétez votre commande create d'origine :

gcloud debug snapshots create LOCATION

Supprimer un emplacement d'instantané

Console

Pour supprimer un emplacement d'instantané, cliquez sur Supprimer .

Supprimer l'instantané sélectionné.

gcloud

Pour supprimer un instantané à partir de la ligne de commande :

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

Où :

  • ID est la valeur renvoyée par gcloud debug snapshots list.

  • LOCATION-REGEXP est une expression régulière définissant l'emplacement du code des instantanés.

Partager des instantanés

Vous pouvez partager un instantané en copiant son URL à partir de votre navigateur ou de la sortie de la commande gcloud debug snapshots list, puis en la transmettant à un autre utilisateur ayant accès à votre projet. Vous pouvez également enregistrer cette URL pour référence ultérieure et y revenir pour afficher ses résultats. Debugger utilise une nouvelle URL pour chaque instantané pris. Cela vous permet de partager des ensembles de résultats distincts, même s'ils ont été enregistrés au même emplacement dans le code. Le partage expire 30 jours après la prise de l'instantané.

Dépannage

L'Agent Debugger a-t-il planté mes instances ?

L'erreur suivante peut s'afficher si l'Agent Debugger est défectueux :

Le volet "Variables" affiche un message d'erreur.

Vous pouvez obtenir des faux positifs qui donnent l'impression que l'Agent Debugger a déclenché ses sauvegardes pour les raisons suivantes :

  • Une instance a été arrêtée pendant que l'Agent Debugger était en version Canary.

    Lorsqu'une instance à laquelle un instantané Canary est appliqué est arrêtée, il semble que l'Agent Debugger l'ait arrêtée. Vérifiez qu'aucune instance n'a été arrêtée dans les 40 secondes suivant la définition de l'instantané. Par exemple, l'autoscaling depuis Cloud Run et App Engine, ou le déploiement d'un nouveau code peut être des raisons d'arrêter les instances.

Vous devez supprimer l'Agent Debugger de vos instances et réinstaller la version précédente. Pour réinstaller la version précédente, suivez les instructions d'installation pour installer la version précédente de l'Agent Debugger.

Si le problème persiste avec l'ancienne version de l'agent, vérifiez qu'il ne s'agit pas d'un faux positif, puis désactivez l'Agent Debugger et envoyez vos commentaires.