Créer des requêtes à l'aide du langage de requête Logging

Ce document explique comment récupérer et analyser les journaux lorsque vous utilisez l'explorateur de journaux. Vous récupérez les journaux en écrivant et en exécutant des requêtes. Vous pouvez créer des requêtes en effectuant des sélections dans les menus de filtre, en utilisant les options incluses dans les entrées de journal et en utilisant le champ de l'éditeur de requête. Les requêtes que vous créez sont écrites dans le langage de requête Logging.

Avant de commencer

  • Pour créer des requêtes, vous devez être autorisé à lire les données des journaux. Ces autorisations sont incluses dans le rôle Lecteur de journaux (roles/logging.viewer). Pour en savoir plus sur les autorisations IAM nécessaires, consultez la section Autorisations pour la console Google Cloud.

  • Pour partager des requêtes, votre rôle Identity and Access Management doit inclure l'autorisation logging.queries.share. Cette autorisation est incluse dans les rôles Propriétaire (roles/owner) et Administrateur de journaux (roles/logging.admin).

    Pour obtenir la liste des autorisations associées à chaque rôle Logging, consultez la section Rôles Logging.

Créer des requêtes

Pour créer des requêtes à l'aide de la console Google Cloud, 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. Sélectionnez le projet Google Cloud ou une autre ressource Google Cloud dont vous souhaitez afficher les journaux.

    Pour afficher les journaux que vous envoyez à Logging à partir d'un compte Amazon Web Services (AWS), sélectionnez le projet de connecteur AWS dans le sélecteur de ressources de la console Google Cloud, puis utilisez l'explorateur de journaux. Le projet de connecteur AWS stocke le nom de ressource Amazon (ARN) de votre compte AWS et associe votre compte AWS aux services Google Cloud. Pour en savoir plus, consultez la section Collecter des métriques à partir de comptes AWS.
  3. Utilisez le volet Requête pour créer votre requête.

    Volet de requête de l'explorateur de journaux

    Le volet Requête offre plusieurs façons de créer et d'exécuter des expressions de requête:

    • Recherchez du texte dans tous les champs de journal.
    • Sélectionnez des options dans les menus de filtrage.
    • Écrivez ou modifiez des requêtes à l'aide de l'éditeur de requête.
    • Affichez, modifiez ou exécutez les requêtes dans les onglets Récent, Enregistré, Suggestions et Bibliothèque.

Rechercher du texte dans les champs de journal

Pour rechercher du texte dans tous les champs de journal et trouver toutes les entrées de journal correspondantes, saisissez les termes de votre recherche dans le champ de recherche:

Champ de recherche de l'explorateur de journaux dans le volet de requête.

Vous pouvez rechercher des mots et des expressions, et vos termes de recherche peuvent inclure des opérateurs booléens et des expressions régulières:

  • Pour effectuer une recherche non sensible à la casse le long des limites de jetons, saisissez les termes de recherche sans guillemets obliques ni guillemets doubles.

    Par exemple, pour rechercher les entrées de journal contenant le mot hello et le mot world, saisissez hello world. Cette commande, qui est convertie en SEARCH("hello world"), établit une correspondance avec les entrées de journal contenant les jetons hello et world, dans n'importe quel ordre. Comme la recherche n'est pas sensible à la casse, elle correspond également à une entrée de journal contenant les jetons Hello et World. La recherche ne correspond pas au jeton worlds.

  • Pour effectuer une recherche non sensible à la casse sur une expression le long des limites des jetons, mettez-la entre guillemets obliques.

    Par exemple, pour rechercher l'expression hello world, saisissez `hello world`. Cette commande, qui est convertie en SEARCH("`hello world`"), établit une correspondance avec les entrées de journal contenant le jeton hello world. La recherche ne correspond pas au jeton hello worlds.

  • Pour effectuer une recherche non sensible à la casse sur une sous-chaîne, encapsulez le texte entre guillemets doubles. Par exemple, "hello world" correspond à Hello World et Hello world. La même requête correspond également à hello worlds, car la recherche n'est pas effectuée en fonction des limites du jeton.

Pour voir les termes de recherche dans l'expression de requête, activez l'option Afficher la requête.

Après avoir saisi vos termes de recherche, cliquez sur Exécuter la requête ou appuyez sur la touche Entrée. Les résultats de la requête sont affichés dans le volet Résultats de la requête.

Opérateurs booléens

Les entrées du champ de recherche sont converties en expressions booléennes qui spécifient un sous-ensemble de toutes les entrées de journal de la ressource Google Cloud sélectionnée.

Le champ de recherche accepte l'utilisation des opérateurs booléens AND, OR et NOT. Lorsque vous utilisez des opérateurs booléens dans vos expressions de recherche, tenez compte des points suivants:

  • Vous ne pouvez pas utiliser de parenthèses pour imbriquer des règles. Toutes les parenthèses dans l'expression de recherche sont analysées en tant que termes de recherche.
  • Vous devez mettre les opérateurs booléens en majuscules. Les minuscules and, or et not sont analysées comme des termes de recherche, et non comme des opérateurs.

Si vous n'incluez aucun opérateur, tous les termes de recherche et toutes les expressions sont reliés par AND. Vous pouvez omettre l'opérateur AND entre les termes de recherche.

Les opérateurs AND et OR sont des opérateurs de court-circuit. Vous pouvez combiner les règles AND et OR dans la même expression. Par exemple, lorsque les deux opérateurs sont mixtes, l'expression a AND b OR c AND d devient l'expression du langage de requête Logging suivante:

"a"
"b" OR "c"
"d"

L'opérateur NOT possède la priorité la plus élevée, suivi de OR et AND.

L'opérateur NOT effectue une négation du terme suivant. Par exemple, NOT error renvoie des entrées de journal qui ne contiennent pas error. Vous pouvez également remplacer l'opérateur NOT par l'opérateur - (moins). Par exemple, les deux requêtes suivantes sont identiques:

"response" AND "successful" AND NOT "error"
"response successful" -"error"

Cette logique fonctionne également avec une expression, si l'opérateur - (moins) se trouve en dehors des guillemets. Par exemple, les deux requêtes suivantes sont identiques:

-"response successful"
NOT "response successful"

Créer des requêtes à l'aide de menus de filtrage

Vous pouvez utiliser les menus de filtre du volet Requête pour ajouter des paramètres de ressource, de nom de journal et de gravité des journaux au champ de l'éditeur de requête. Ces options correspondent aux champs LogEntry de tous les journaux Logging.

Les options des menus Ressource et Nom du journal n'affichent que les journaux actuellement stockés dans Cloud Logging.

Menus de filtrage de l'éditeur de requête

  • Ressource: permet de spécifier le resource.type et le resource.labels associé. Vous pouvez sélectionner un seul type de ressource à l'aide de ce menu de filtre et zéro, un ou plusieurs libellés de ressource à appliquer à votre requête. Les paramètres de ressource sont joints par l'opérateur logique AND.
  • Log name (Nom de journal) : permet de spécifier le logName. Vous pouvez sélectionner plusieurs noms de journaux à appliquer à votre requête. Lorsque vous sélectionnez plusieurs noms de journaux, l'opérateur logique OR est utilisé.
  • Severity(Gravité) : permet de spécifier le niveau de gravité. Vous pouvez sélectionner simultanément plusieurs niveaux de gravité à ajouter à votre requête. Lorsque vous sélectionnez plusieurs niveaux de gravité, l'opérateur logique OR est utilisé.

Pour utiliser l'un des menus de filtrage, procédez comme suit:

  1. Développez le menu sur l'un des menus de filtre du volet Requête.

  2. Affinez les paramètres de filtre.

  3. Cliquez sur Appliquer. Les paramètres s'affichent dans le champ de l'éditeur de requête.

    Pour voir les termes de recherche dans l'expression de requête, activez l'option Afficher la requête.

  4. Après avoir examiné la requête, cliquez sur Run query (Exécuter la requête). Les résultats de la requête sont affichés dans le volet Résultats de la requête.

Pour certains types de ressources Compute Engine, tels que gce_instance et gce_network, le nom de la ressource s'affiche avec l'ID de ressource sous forme de sous-texte. Par exemple, pour le type de ressource gce_instance, le nom de la VM s'affiche à côté de l'ID de la VM. Les noms de ressource vous aident à identifier l'ID de ressource correct sur lequel vous pouvez créer des requêtes.

Afficher les journaux par période

Il existe deux façons d'afficher les journaux écrits sur une période spécifique:

  1. Utilisez le sélecteur de période.
  2. Incluez une expression de code temporel dans le champ de l'éditeur de requête.

Utiliser le sélecteur de période

La période par défaut est d'une heure, mais vous pouvez choisir parmi des options de temps prédéfinies, spécifier des heures de début et de fin personnalisées ou centrer la période sur un horodatage spécifique à l'aide du sélecteur de période. Par exemple, si vous souhaitez afficher les données de la semaine passée, sélectionnez La semaine dernière dans le sélecteur de période.

Vous pouvez également définir vos préférences de fuseau horaire à l'aide du sélecteur de période.

Inclure une expression de code temporel dans le champ de l'éditeur de requête

Pour ajouter une expression de code temporel directement dans le champ de l'éditeur de requête, utilisez le langage de requête Logging.

Si le champ de l'éditeur de requêtes contient une expression avec un horodatage, le sélecteur de période est désactivé et la requête utilise l'expression d'horodatage comme restriction de période. Si une requête n'utilise pas d'expression de code temporel, elle utilise le sélecteur de période comme restriction de période.

Rédiger des requêtes avancées à l'aide du langage de requête Logging

Vous pouvez utiliser le langage de requête Logging pour créer des requêtes plus avancées dans le champ de l'éditeur de requête de l'explorateur de journaux:

  1. Si vous ne voyez pas le champ de l'éditeur de requête dans le volet Requête, activez l'option Afficher la requête.

  2. Saisissez vos expressions de requête directement dans le champ de l'éditeur de requête.

    Si vous avez ajouté des termes de recherche dans le champ de recherche ou sélectionné des paramètres dans les menus de filtre, ceux-ci apparaissent également dans le champ de l'éditeur de requête et sont évalués dans le cadre de votre expression de requête.

  3. Après avoir examiné votre requête, cliquez sur Exécuter la requête.

    Les journaux correspondant à votre requête sont répertoriés dans le volet Résultats de la requête. Les volets Histogramme et Champs de journal sont également ajustés en fonction de l'expression de requête.

Pour obtenir des exemples de requêtes courantes que vous pouvez utiliser, consultez la page Exemples de requêtes avec l'explorateur de journaux.

Utiliser les requêtes récentes

Lorsque vous exécutez une requête, celle-ci est ajoutée à la liste des requêtes Récentes, qui contient les 10 000 dernières requêtes uniques sur une période de 30 jours.

Pour afficher vos requêtes récentes, sélectionnez l'onglet Récent dans le volet Requête. Dans l'onglet Récent, vous disposez des options suivantes:

  • Flux: pour exécuter la requête et diffuser les résultats, choisissez cette option.
  • Run (Exécuter) : choisissez cette option pour exécuter la requête.
  • Autres options : permet d'afficher l'expression de requête avec les options permettant d'exécuter la requête ou de l'enregistrer dans votre liste de requêtes enregistrées. Vous pouvez aussi directement sélectionner la requête pour obtenir ces options.

    Pour enregistrer la requête, procédez comme suit:

    1. Cliquez sur Enregistrer sous. La boîte de dialogue Enregistrer la requête s'ouvre.
    2. Remplissez les champs suivants :

      • Nom (obligatoire): indiquez un nom pour votre requête. Les noms sont limités à 64 caractères.
      • Description (facultatif) : fournissez une description vous permettant d'identifier l'objectif de la requête.
      • Inclure les champs de résumé (facultatif): activez l'option Inclure les champs de résumé et saisissez les champs de résumé que vous souhaitez afficher.
      • Truncate summary fields (Tronquer les champs de résumé) (facultatif): activez l'option Truncate summary fields (Tronquer les champs de résumé) et sélectionnez le nombre de caractères à tronquer et indiquez si la troncation doit être effectuée au début ou à la fin des champs.
    3. Cliquez sur Enregistrer la requête. La requête est maintenant disponible dans la liste des requêtes enregistrées.

Vous pouvez également trier et filtrer vos requêtes récentes. Le filtre correspond au texte de votre expression de requête.

Enregistrer les requêtes

Le volet Requête comporte un onglet Enregistré, dans lequel vous pouvez accéder à vos requêtes enregistrées. Les requêtes enregistrées vous permettent de stocker des expressions de requête pour vous aider à explorer vos journaux de manière plus cohérente et efficace.

Pour enregistrer une expression de requête que vous avez créée dans le champ de l'éditeur de requête, procédez comme suit:

  1. Cliquez sur Enregistrer dans le volet Requête. La boîte de dialogue Enregistrer la requête s'ouvre, avec votre expression de requête dans le champ de l'éditeur de requête.

  2. Remplissez les champs suivants :

    • Nom (obligatoire): indiquez un nom pour votre requête. Les noms sont limités à 64 caractères.
    • Description (facultatif) : fournissez une description vous permettant d'identifier l'objectif de la requête.
    • Inclure les champs de résumé (facultatif): activez l'option Inclure les champs de résumé et saisissez les champs de résumé que vous souhaitez afficher.
    • Truncate summary fields (Tronquer les champs de résumé) (facultatif): activez l'option Truncate summary fields (Tronquer les champs de résumé) et sélectionnez le nombre de caractères à tronquer et indiquez si la troncation doit être effectuée au début ou à la fin des champs.
    1. Cliquez sur Enregistrer la requête. Vos requêtes enregistrées s'affichent sous forme de liste dans l'onglet Saved (Enregistrées).

Pour exécuter une requête enregistrée, cliquez sur Exécuter. Pour exécuter la requête et diffuser les résultats, cliquez sur Flux.

Vous pouvez également trier et filtrer vos requêtes enregistrées. Le filtre correspond au texte de votre expression de requête.

Partager des requêtes

Les requêtes partagées permettent aux utilisateurs d'un projet Google Cloud de partager leurs requêtes enregistrées entre eux. Vous pouvez afficher les requêtes partagées dans l'onglet Enregistrés.

Pour connaître les rôles et les autorisations nécessaires pour afficher et modifier des requêtes partagées, consultez la page Autorisations de la console Google Cloud. Notez que les utilisateurs disposant du rôle IAM roles/logging.admin ou roles/editor peuvent modifier les requêtes partagées d'autres utilisateurs.

Créer une requête partagée

Vous pouvez partager les requêtes que vous avez déjà enregistrées ou en partager une nouvelle.

Pour créer et partager une requête, procédez comme suit:

  1. Saisissez une requête dans le champ de l'éditeur de requête.

  2. Cliquez sur Enregistrer.

  3. Renseignez les champs de la boîte de dialogue Enregistrer la requête.

  4. Activez l'option Share with project.

  5. Cliquez sur Enregistrer la requête.

Votre requête est désormais partagée avec d'autres utilisateurs du projet Google Cloud.

Pour partager une requête déjà enregistrée, procédez comme suit:

  1. Sélectionnez l'onglet Saved (Éléments enregistrés).

  2. Sélectionnez Plus d'options, puis Modifier, ou sélectionnez directement la requête.

  3. Dans la boîte de dialogue Modifier la requête, activez l'option Partager avec le projet, puis cliquez sur Mettre à jour la requête.

Votre requête est désormais partagée avec d'autres utilisateurs du projet Google Cloud.

Afficher les requêtes partagées

Pour afficher rapidement toutes les requêtes partagées, triez la colonne Visibility pour afficher d'abord les requêtes partagées:

  1. Sélectionnez l'onglet Saved (Éléments enregistrés).

  2. Cliquez sur All (Tous).

  3. Triez la colonne Visibility.

La colonne Visibilité indique si les requêtes sont partagées et comment:

  • Partagés par moi: requêtes que vous avez enregistrées et partagées avec d'autres utilisateurs du projet Google Cloud.
  • Partagées: requêtes partagées par d'autres utilisateurs du projet Google Cloud.
  • Privée: requêtes que vous avez enregistrées et que vous n'avez pas partagées avec d'autres utilisateurs du projet Google Cloud.

Afficher uniquement vos requêtes

Pour afficher les requêtes enregistrées que vous avez créées ou partagées, cliquez sur Mine. La liste des requêtes que vous avez créées et enregistrées s'affiche. Dans la colonne Visibility, vos requêtes non partagées s'affichent dans Private. Les requêtes que vous avez partagées sont indiquées par Shared by me.

Utiliser les requêtes suggérées

Logging génère des requêtes suggérées en fonction du contexte de votre projet Google Cloud (par exemple, les produits Google Cloud que vous utilisez). Les requêtes suggérées peuvent vous aider à identifier les problèmes et vous fournir des informations sur l'état général de vos systèmes. Par exemple, s'il détecte que vous utilisez Google Kubernetes Engine, Logging peut suggérer une requête qui trouve tous les journaux d'erreurs de vos conteneurs.

Pour afficher et exécuter des requêtes suggérées, sélectionnez l'onglet Suggestions dans le volet Requête. L'onglet Suggestions affiche une liste de requêtes, chacune avec une description et les options suivantes:

  • Flux: pour exécuter la requête et diffuser les résultats, choisissez cette option.
  • Run (Exécuter) : choisissez cette option pour exécuter la requête.
  • Autres options : permet d'afficher les détails de l'expression de requête, ainsi que les options permettant d'exécuter la requête ou de l'enregistrer. Vous pouvez aussi directement sélectionner la requête pour obtenir ces options.

    Pour examiner les détails d'une requête suggérée, effectuez l'une des opérations suivantes:

    • Sélectionnez la ligne de la requête.

    • Cliquez sur Plus, puis sélectionnez Afficher. La boîte de dialogue Détails de la requête s'ouvre.

    Dans la boîte de dialogue Détails de la requête, la requête s'affiche, ainsi que les options Exécuter, Diffuser ou Enregistrer sous:

    • Pour enregistrer la requête, procédez comme suit:

      1. Cliquez sur Enregistrer sous.
      2. Renseignez les champs de la boîte de dialogue Enregistrer la requête.

      La requête modifiée s'affiche dans la liste des requêtes Enregistrées, où vous pouvez choisir de l'exécuter ultérieurement.

    • Pour exécuter la requête maintenant, cliquez sur Exécuter. La requête s'exécute et apparaît dans le champ de l'éditeur de requête.

    • Pour exécuter la requête maintenant et diffuser les résultats, cliquez sur Stream.

    • Pour fermer la boîte de dialogue et revenir à la liste des requêtes suggérées, cliquez sur Fermer.

Notez les comportements attendus suivants:

  • Il est possible que les chargements de pages successifs n'affichent pas les mêmes requêtes, dans le même ordre.
  • Il est possible qu'aucune suggestion de requête ne s'affiche.
  • Parfois, l'exécution d'une requête suggérée ne renvoie aucun journal.

Sélectionner des requêtes dans la bibliothèque

Logging fournit une bibliothèque de requêtes basée sur des cas d'utilisation courants et sur des produits Google Cloud. Ces requêtes peuvent vous aider à trouver efficacement les journaux lors de sessions de dépannage urgentes et à les explorer afin de mieux comprendre quelles données de journalisation sont disponibles.

Pour afficher et exécuter les requêtes de la bibliothèque, procédez comme suit:

  1. Sélectionnez l'onglet Bibliothèque dans le volet Requête.

  2. Dans la colonne Toutes les requêtes, vous pouvez consulter les grandes catégories de requêtes disponibles et les sous-ensembles de requêtes basés sur les produits Google Cloud. Pour affiner la sélection des requêtes qui s'affichent, cliquez sur l'un des produits.

    Vous pouvez également utiliser le champ de recherche pour rechercher les requêtes disponibles par catégorie, description ou contenu de l'expression de requête.

  3. Pour examiner une expression de requête, effectuez l'une des opérations suivantes:

    a. Cliquez sur la ligne de la requête.

    b. Cliquez sur Plus, puis sélectionnez Afficher.

  4. Dans la boîte de dialogue Détails de la requête, la requête s'affiche, ainsi que les options Exécuter, Diffuser ou Enregistrer sous:

    • Pour enregistrer la requête, procédez comme suit:

      1. Cliquez sur Enregistrer sous.
      2. Renseignez les champs de la boîte de dialogue Enregistrer la requête.

      La requête modifiée s'affiche dans la liste des requêtes Enregistrées, où vous pouvez choisir de l'exécuter ultérieurement.

    • Pour exécuter la requête maintenant, cliquez sur Exécuter. La requête s'exécute et apparaît dans le champ de l'éditeur de requête.

    • Pour exécuter la requête maintenant et diffuser les résultats, cliquez sur Stream.

    • Pour fermer la boîte de dialogue et revenir à la liste des requêtes suggérées, cliquez sur Fermer.

Étapes suivantes