Migrer vers Cloud Logging

La journalisation des environnements d'exécution de deuxième génération est différente des environnements d'exécution de première génération. L'une des principales modifications lors de la mise à niveau vers des environnements d'exécution plus récents est que la journalisation pré-intégrée dans App Engine n'est pas compatible avec les environnements d'exécution de deuxième génération et que les journaux ne sont pas automatiquement corrélés. Si vous migrez vers des environnements d'exécution de deuxième génération, vous devez utiliser la bibliothèque cliente Cloud Logging.

Ce guide explique comment mettre à jour votre application pour utiliser Cloud Logging et obtenir quasiment les mêmes fonctionnalités de filtrage et de corrélation de journaux que celles disponibles avec l'intégration de la journalisation dans App Engine.

Cloud Logging est un système de gestion des journaux en temps réel qui offre une compatibilité avec le stockage, la recherche, l'analyse et la surveillance. Cloud Logging collecte automatiquement les journaux des ressources Google Cloud. Vous pouvez également collecter des journaux à partir de vos applications, des ressources sur site et des ressources d'autres fournisseurs de services cloud.

Différences majeures

Le tableau suivant décrit les différences de journalisation entre les environnements d'exécution de première et de deuxième génération :

	Environnements d'exécution de première génération	Environnements d'exécution de deuxième génération
Journaux de requêtes et d'application (également appelés journaux d'application)	App Engine intègre tous les journaux d'application dans le journal de requêtes. La journalisation dans les environnements d'exécution de première génération utilise le champ protoPayload.line.logMessage du journal de requêtes pour intégrer les journaux d'application.	App Engine n'intègre pas les journaux d'application dans le journal de requêtes. App Engine omet l'attribut protoPayload.line dans le journal de requêtes. Les journaux d'application sont acheminés en fonction de la méthode de journalisation que vous utilisez : stdout et stderr : achemine les journaux tels que print() vers logs/stdout ou logs/stderr. Module de journalisation Python après la configuration du client Cloud Logging : achemine tous les journaux écrits par le module de journalisation racine Python, tels que logging.info() et logging.error(), vers logs/python. Si la bibliothèque cliente Cloud Logging pour Python n'est pas configurée pour la corrélation, le module de journalisation racine Python achemine le trafic vers logs/stderr par défaut.
Afficher les journaux dans l'explorateur de journaux	Les environnements d'exécution de première génération ne contiennent qu'un seul type de journal, appengine.googleapis.com/request_log. Lorsque vous développez un journal de requêtes, vous pouvez voir les journaux d'application imbriqués en dessous.	Les environnements d'exécution de deuxième génération incluent les journaux de plusieurs types de journaux, tels que les journaux de requêtes appengine.googleapis.com/request_log ,stdout ,stderr ,logs/python et bien d'autres encore, selon la manière dont votre application émet des journaux. Les journaux internes à Google sont également disponibles dans /var/log/google_init.log. Étant donné que les journaux d'application ne sont pas automatiquement corrélés aux journaux de requêtes, des étapes supplémentaires sont nécessaires pour afficher la vue imbriquée des journaux de requêtes et d'applications dans l'Explorateur de journaux. Pour en savoir plus, consultez les pages Corréler les journaux de requêtes avec les journaux d'application et Afficher les journaux corrélés dans l'Explorateur de journaux.
Intégration à Cloud Trace	Intégration automatique à Cloud Trace pour la collecte des données de latence	Vous devez intégrer manuellement votre application à Cloud Trace pour recueillir les données relatives à la latence depuis App Engine. Pour en savoir plus, consultez la section Instrumenter pour Cloud Trace.
Corrélation au niveau des erreurs	Enregistre l'erreur générée dans les journaux de requête App Engine avec un niveau de gravité ERROR. Error Reporting établit automatiquement une corrélation entre ces informations dans le tableau de bord Error Reporting.	Par défaut, App Engine n'intègre pas Error Reporting dans les environnements d'exécution de deuxième génération. Pour configurer l'intégration de la journalisation avec Error Reporting, consultez la section Instrumenter des applications à l'aide de bibliothèques clientes.
Niveau de gravité	L'Explorateur de journaux attribue un niveau de gravité aux requêtes de journaux. Il correspond au niveau de gravité le plus élevé détecté sur les entrées de journal de l'application associée à celles-ci. Par exemple, si votre application génère une entrée de journal d'avertissement suite à une requête, l'Explorateur de journaux affiche une icône d'avertissement à côté de l'entrée de journal de la requête. Lorsque vous développez l'entrée de requête, vous voyez l'entrée de journal d'avertissement imbriquée dans l'entrée de requête.	Par défaut, tous les journaux de requêtes ont le niveau de gravité DEFAULT ou INFO. Même si vos journaux de requêtes sont corrélés aux journaux d'application et que l'Explorateur de journaux est configuré pour afficher les journaux corrélés, les journaux de requêtes ne reflètent pas la gravité des journaux d'application associés.
API Logservice	L'API Logservice fait partie du SDK de services groupés.	L'API Logservice a été supprimée du SDK de services groupés Pour en savoir plus, consultez la liste des API disponibles.

Avant de commencer la migration

1. Activez l'API Cloud Logging dans le projet qui contient votre application.

   Activer l'API

2. Assurez-vous que votre application est autorisée à écrire des journaux.

   Par défaut, le compte de service par défaut de votre application est autorisé à écrire des journaux.

   Si votre application utilise un compte de service différent ou si vous avez modifié les autorisations du compte de service par défaut, assurez-vous que le compte que vous utilisez dispose des autorisations logging.logEntries.create d'écrire des journaux.

3. Familiarisez-vous avec les différents types de journaux dans App Engine.

Présentation du processus de migration

Pour migrer votre application de sorte qu'elle utilise Cloud Logging, procédez comme suit :

1. Installer les bibliothèques clientes Cloud pour Cloud Logging
2. Écrire des journaux avec Cloud Logging
3. Corréler les journaux de requête avec les journaux d'application
4. Afficher les journaux
5. Tester l'application

Installer les bibliothèques clientes Cloud pour Cloud Logging

Pour installer et mettre à jour vos fichiers de configuration, ajoutez les bibliothèques clientes cloud pour Cloud Logging à votre liste de dépendances dans le fichier requirements.txt, comme suit :

google-cloud-logging

Écrire des journaux avec le module de journalisation Python standard

Dans chaque fichier qui écrit des entrées de journal :

1. Importez la bibliothèque cliente Cloud Logging.
2. Instanciez le client Cloud Logging.
3. Exécutez la méthode setup_logging() du client Cloud Logging, qui associe son écouteur par défaut en tant que gestionnaire de journalisation pour l'enregistreur racine Python.

Exemple :

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

Une fois le gestionnaire associé, tous les journaux émis dans votre application de niveau INFO ou supérieur sont envoyés à Logging par défaut :

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

Corréler les journaux de requête avec les journaux d'application

Certaines fonctionnalités disponibles dans les environnements d'exécution de première génération, comme la corrélation automatique des journaux de requêtes avec les journaux d'application, ne sont pas disponibles dans les environnements d'exécution de deuxième génération.

Les applications utilisant des environnements d'exécution de deuxième génération peuvent obtenir un comportement de journalisation imbriquée semblable à celui des environnements d'exécution de première génération, à l'aide de l'une des méthodes suivantes :

• Configurer le client Cloud Logging dans votre application et mettre en corrélation les journaux
• Utiliser un identifiant trace avec stdout et stderr

Le comportement de journalisation dans les environnements d'exécution de première et de deuxième génération présente les différences suivantes :

• Dans les environnements d'exécution de première génération, App Engine intègre tous les journaux d'application émis lors du traitement d'une requête dans le champ protoPayload.line.logMessage du journal de requêtes. Ces journaux sont visibles dans l'explorateur de journaux via appengine.googleapis.com/request_log.

  L'image suivante montre les journaux d'application et de requêtes corrélés dans les environnements d'exécution de première génération :

  

• Dans les environnements d'exécution de deuxième génération, App Engine omet l'attribut protoPayload.line dans le journal de requêtes. Les contenus des journaux d'application ne sont pas présents dans les journaux de requêtes JSON de l'Explorateur de journaux. Chaque journal d'application s'affiche séparément à partir de son nom de journal dans l'Explorateur de journaux.

  L'image suivante montre des journaux de requêtes et d'applications distincts dans les environnements d'exécution de deuxième génération :

  

Les sections suivantes expliquent comment utiliser le client Cloud Logging ou la journalisation structurée avec stdout et stderr pour corréler les journaux.

Utiliser le module de journalisation Python

Pour ajouter la corrélation des requêtes aux journaux d'application enregistrés par le module de journalisation Python, configurez la bibliothèque cliente Cloud Logging.

Lorsque vous exécutez la méthode client.setup_logging() au démarrage de l'application, cette méthode ajoute le champ trace et les détails de la requête HTTP dans les journaux d'application écrits par le module Python logging, tels que logging.info() et logging.error(). Ces journaux sont acheminés vers logs/python.

App Engine ajoute également ce champ trace au journal de requêtes associé, ce qui permet d'afficher les entrées de journal corrélées dans l'Explorateur de journaux.

Utiliser stdout et stderr

Si vous utilisez stdout et stderr pour écrire des entrées de journal, celles-ci apparaissent dans l'Explorateur de journaux. Toutefois, pour activer le filtrage et la corrélation avec les journaux de requêtes, vous devez mettre en forme les entrées en tant qu'objet JSON et fournir des métadonnées spécifiques. Pour en savoir plus sur cette approche, consultez la section Écrire des journaux structurés dans stdout et stderr. Cette approche ajoute l'identifiant de trace de la requête dans les journaux d'application en :

1. Extrayant l'identifiant de trace de l'en-tête de requête X-Cloud-Trace-Context.
2. Écrivant l'ID dans un champ nommé logging.googleapis.com/trace dans votre entrée de journal structurée. Pour en savoir plus sur l'en-tête X-Cloud-Trace-Context, consultez la section Forcer le traçage d'une requête.

Afficher les journaux

Vous pouvez afficher les journaux d'application et les journaux de requêtes de plusieurs manières :

• Utilisez l'Explorateur de journaux depuis Cloud Logging dans la console Google Cloud.
• Afficher les journaux à l'aide de gcloud via la Google Cloud CLI
• Lire les journaux de manière automatisée à l'aide de différentes méthodes.

Utiliser l'Explorateur de journaux

Vous pouvez afficher les journaux d'application et de requêtes à l'aide de l'Explorateur de journaux :

1. Accédez à l'Explorateur de journaux dans la console Google Cloud :

   Accéder à l'explorateur de journaux

2. Sélectionnez un projet Google Cloud existant en haut de la page.

3. Dans Type de ressource, sélectionnez Application GAE.

Vous pouvez filtrer l'Explorateur de journaux en fonction du service, de la version et d'autres critères d'App Engine. Vous pouvez également rechercher des entrées spécifiques dans les journaux. Consultez la page Utiliser l'explorateur de journaux pour plus d'informations.

Si vous envoyez des entrées de texte simples à la sortie standard, vous ne pouvez pas utiliser la visionneuse de journaux pour filtrer les entrées d'application par gravité ni identifier les journaux d'application correspondant à des requêtes spécifiques. Vous pouvez toujours utiliser d'autres types de filtres dans l'explorateur de journaux, tels que le texte et l'horodatage.

Afficher les entrées de journal corrélées dans l'Explorateur de journaux

Dans l'Explorateur de journaux, pour afficher les entrées de journal enfants corrélées à une entrée de journal parente, développez l'entrée de journal.

Par exemple, pour afficher les entrées de journal de requêtes App Engine et d'application, procédez comme suit :

1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Logging, puis Explorateur de journaux :

   Accéder à l'explorateur de journaux

2. Dans Type de ressource, sélectionnez Application GAE.

3. Pour afficher et mettre en corrélation les journaux de requêtes, sélectionnez request_log dans le champ Nom du journal. Sinon, pour mettre en corrélation par journaux de requêtes, cliquez sur Corréler par et sélectionnez request_log.

   

4. Dans le volet Résultats de la requête, cliquez sur Développer pour développer une entrée de journal. Lors du développement, chaque journal de requêtes affiche les journaux d'application associés.

Après avoir créé un filtre pour les journaux, chaque journal de requêtes affiche les journaux d'application correspondants en tant que journaux enfants. Pour ce faire, l'Explorateur de journaux met en corrélation le champ trace dans les journaux d'application et un journal de requêtes donné, en supposant que l'application utilise la bibliothèque google-cloud-logging.

L'image suivante montre les journaux d'application regroupés par champ trace :

Utiliser la Google Cloud CLI

Pour afficher vos journaux App Engine à partir de la ligne de commande, exécutez la commande suivante :

gcloud app logs tail

Pour plus d'informations, consultez la page gcloud app logs tail.

Lire les journaux de manière automatisée

Si vous souhaitez lire les journaux de manière automatisée, vous pouvez utiliser l'une des méthodes suivantes :

• Utilisez un récepteur pour envoyer les journaux à Pub/Sub et un script pour les extraire de Pub/Sub.
• Appelez l'API Cloud Logging via la bibliothèque cliente correspondant à votre langage de programmation.
• Appelez directement les points de terminaison REST de l'API Cloud Logging.

Comprendre les journaux de scaling des instances

Lorsque de nouvelles instances sont démarrées pour votre application, Cloud Logging inclut des entrées de journal sous le nom de journal varlog/system pour indiquer pourquoi chaque instance a été créée. L'entrée de journal suit le format suivant :

Starting new instance. Reason: REASON - DESCRIPTION

Le tableau suivant fournit une répartition des descriptions d'instance :

Motif	Description
CUSTOMER_MIN_INSTANCE	Instance minimale configurée par le client pour l'application.
SCHEDULED	L'instance a démarré en raison des facteurs de scaling configurés (par exemple, utilisation du processeur, débit des requêtes, etc.) et de leurs cibles.
OVERFLOW	L'instance a démarré, car aucune capacité n'a été trouvée pour le trafic actuel.

Tester l'application

La migration est réussie si vous êtes en mesure de déployer votre application sans erreur. Pour vérifier que Cloud Logging fonctionne, procédez comme suit :

1. Accédez à l'Explorateur de journaux, puis développez une entrée de journal de requêtes.

   Accéder à l'explorateur de journaux

2. Assurez-vous que les journaux d'application générés par votre application lors du traitement d'une requête sont imbriqués dans le journal de requêtes.

3. Si tous les points de terminaison de votre application fonctionnent comme prévu, utilisez la répartition du trafic pour augmenter progressivement le trafic de votre application mise à jour. Surveillez attentivement les éventuels problèmes avant d'acheminer davantage de trafic vers l'application mise à jour.