Points de journalisation de débogage

Après avoir déployé ou lancé votre application, vous pouvez ouvrir Cloud Debugger dans Google Cloud Console. Cloud Debugger vous permet d'injecter une journalisation dans les services en cours d'exécution sans avoir à les redémarrer et sans interférer avec leur fonctionnement normal. Cela peut être utile pour déboguer des problèmes de production sans avoir besoin d'ajouter des entrées de journal et de redéployer le code.

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

Avant de commencer

Cloud Debugger peut être utilisé avec ou sans accès au code source de votre application. Si votre code source n'est pas disponible, reportez-vous à la section Ajout d'un point de journalisation de débogage ci-dessous pour obtenir des instructions sur la saisie manuelle du nom de fichier et du numéro de ligne.

Si votre code source est stocké dans les dépôts Google Cloud, il s'affiche automatiquement dans la vue Debug (Débogage).

Pour accéder à un code source stocké ailleurs, par exemple localement ou dans un dépôt git, vous devrez peut-être sélectionner un emplacement de code source.

Points de journalisation

Les points de journalisation vous permettent d'injecter une journalisation dans les services en cours d'exécution sans avoir besoin de les redémarrer et sans interférer avec leur fonctionnement normal. Chaque fois qu'une instance exécute du code à l'emplacement du point de journalisation, Cloud Debugger consigne un message. La sortie est envoyée au journal approprié pour l'environnement de la cible. Sur App Engine, par exemple, la sortie est envoyée au journal de requêtes dans Cloud Logging.

Les points de journalisation restent actifs pendant 24 heures après leur création, ou jusqu'à ce qu'ils soient supprimés ou que le service soit redéployé.

Agent Debugger avec version Canary

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

Après ce processus, lorsque le point de journalisation est déclenché, l'Agent Debugger consigne le message. Si le point de journalisation est déclenché dans les 40 secondes suivant sa définition, l'Agent Debugger consigne le message à partir des instances auxquelles le point de journalisation Canary a été appliqué.

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

Les éléments suivants s'affichent lorsque l'Agent Debugger est en version Canary :

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 que vous définissez un point de journalisation, 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 du point de journalisation, l'Agent Debugger consigne le message. L'Agent Debugger met en œuvre plusieurs stratégies pour réduire la latence générée par l'enregistrement des données.

 

Ajouter un point de journalisation de débogage

Console

Pour ajouter un point de journalisation à partir de la Cloud Console :

  1. Assurez-vous que l'onglet Logpoint (Point de journalisation) est sélectionné dans le panneau de droite.
  2. Dans le panneau de gauche, sélectionnez le fichier contenant le code source dans lequel vous souhaitez ajouter un point de journalisation. Le contenu du fichier s'affiche dans le panneau central.
  3. Cliquez sur le numéro de ligne correspondant à l'emplacement où vous souhaitez ajouter un point de journalisation.
  4. Insérez le message entre les guillemets dans le champ logpoint("") et cliquez sur le bouton "Add" (Ajouter). Vous pouvez placer une expression entre accolades (telle que {newScore.score}, par exemple) pour consigner sa valeur.

Ajout d'un point de journalisation dans une ligne


Si aucun code source n'est disponible, vous pouvez saisir manuellement le couple "nom du fichier:numéro de ligne" et d'autres détails dans le panneau Logpoint (Point de journalisation) : Ajout manuel d'un point de journalisation

gcloud

Pour ajouter un point de journalisation à partir de la ligne de commande, exécutez la commande suivante :

gcloud debug logpoints create LOCATION MESSAGE

Où :

  • LOCATION correspond au nom de fichier et au numéro de ligne où le point de journalisation doit être défini. Le format de cette valeur est du type FILE:LINE, où FILE peut être soit le nom de fichier seul, soit le nom de fichier précédé d'un nombre suffisant de composants de chemin d'accès pour qu'on puisse facilement 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.
  • MESSAGE est le message que vous souhaitez consigner.

L'exemple suivant consigne la valeur de score au niveau du journal info (qui est le niveau de consignation par défaut pour les points de journalisation) :

gcloud debug logpoints create HighScoreService.java:105 \
  "User {name} scored {newScore.score}"

Lorsque la ligne 105 de HighScoreService.java executes s'exécute, le message est consigné avec les valeurs des variables name et newScore.score insérées dans la chaîne de sortie.

Format d'un message de point de journalisation

Le message d'un point de journalisation détermine ce qui est consigné dans la sortie. Les expressions vous permettent d'évaluer et de consigner les valeurs qui vous intéressent. Dans un message, tout ce qui se trouve entre accolades ({myObj.myFunc()} ou {a + b}, par exemple) sera remplacé par la valeur de l'expression dans la sortie. Dans l'exemple ci-dessus, le message User {name} scored {newScore.score} consignera une sortie équivalente à User user1 scored 99.

Vous pouvez utiliser les fonctionnalités de langage suivantes pour les expressions :

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 plutôt myInteger.value.

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

Go

La syntaxe de la plupart des expressions Go est compatible, 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
  • Appel de fonctions autres que len

Condition de point de journalisation

Une condition de point de journalisation est une expression simple, dans le langage de l'application, qui doit prendre la valeur "true" pour que le point de journalisation soit consigné. Les conditions du point de journalisation sont évaluées chaque fois que la ligne est exécutée par l'une des instances, et ce, jusqu'à ce que le point de journalisation expire ou soit supprimé.

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

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

Les fonctionnalités de langage prises en charge pour les expressions sont également disponibles pour les conditions.

Console

Saisissez la condition dans l'instruction "if" :

Définition d'une condition dans une ligne

Si aucun code source n'est disponible, vous pouvez spécifier la condition dans le panneau Logpoint.

gcloud

Les conditions sont exprimées à l'aide de l'indicateur --condition de logpoints create :

gcloud debug logpoints create HighScoreService.java:105 
--condition="newScore.score > 40"
--log-level="warning"
"Suspiciously high score ({newScore.score}) from user {name}"

Dans l'exemple ci-dessus, le point de journalisation vérifie la valeur de newScore.score lorsque la ligne 105 de l'application s'exécute. Si cette valeur est supérieure à 40, un message d'avertissement est ajouté au journal.

Afficher la sortie

La sortie du point de journalisation est envoyée au journal approprié pour l'environnement de la cible.

App Engine

Les points de journalisation définis dans les applications App Engine envoient leur sortie au journal de requêtes dans Cloud Logging.

Vous pouvez afficher les journaux dans le panneau Logs (Journaux) ou dans l'explorateur de journaux dédié.

Point de journalisation dans le panneau des journaux

Compute Engine

Les points de journalisation définis dans les applications Compute Engine envoient leur sortie au même emplacement que les entrées de journal classiques. Par exemple, en Python, le module de journalisation par défaut envoie sa sortie à stdout. Il peut toutefois être configuré pour écrire dans un fichier spécifique.

Vous pouvez configurer l'agent de journalisation pour qu'il transfère les journaux vers Cloud Logging. De là, vous pouvez afficher les journaux dans l'explorateur de journaux.

Supprimer des points de journalisation

Les points de journalisation deviennent inactifs et arrêtent la consignation des messages après 24 heures. Ils sont automatiquement supprimés après 30 jours. Vous pouvez supprimer manuellement un point de journalisation. Cette action entraîne l'arrêt de la journalisation et supprime le point de journalisation de l'historique, et il ne sera donc pas possible de s'y référer ultérieurement. Notez toutefois que la suppression d'un point de journalisation n'entraîne pas la suppression des messages de journal déjà générés.

Console

Pour supprimer manuellement un point de journalisation, utilisez le menu à développer dans le volet Logpoint History (Historique des points de journalisation).

Suppression d'un point de journalisation

gcloud

Pour supprimer un point de journalisation manuellement, vous pouvez spécifier son ID ou utiliser des expressions régulières sur l'emplacement du code :

gcloud debug logpoints delete HighScoreService.java:105

Debug target not specified. Using default target: default-1
This command will delete the following logpoints:

LOCATION                   CONDITION            LOG_LEVEL  LOG_MESSAGE_FORMAT                                             ID
HighScoreService.java:105                       INFO       User {name} scored {newScore.score}.                           53aaa3bd8d2d7-b76f-feb5d
HighScoreService.java:105  newScore.score > 40  WARNING    Suspiciously high score ({newScore.score}) from user {name}  53aaa3bsdffd7-b56f-fasfg

Do you want to continue (Y/n)?  Y
Deleted 2 logpoints.