Créer et enregistrer 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 en écrivant des requêtes dans le champ de l'éditeur de requêtes et en effectuant des sélections dans les menus de filtrage à l'aide des options incluses dans les entrées de journal. Les requêtes que vous créez sont écrites dans le langage de requête Logging.

Vous pouvez également enregistrer vos requêtes sur la page de l'explorateur de journaux ou à l'aide de la méthode d'API Logging savedQueries.create.

Avant de commencer

• Pour obtenir les autorisations nécessaires pour lire les données de journal afin de créer des requêtes, d'utiliser des requêtes enregistrées privées ou de lister et d'obtenir des requêtes partagées, demandez à votre administrateur de vous accorder le rôle IAM Lecteur de journaux (roles/logging.viewer) sur votre projet.

  Ce rôle prédéfini contient les autorisations requises pour lire les données de journal afin de créer des requêtes, d'utiliser des requêtes enregistrées privées ou de lister et d'obtenir des requêtes partagées. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

  Autorisations requises

  Vous devez disposer des autorisations suivantes pour lire les données de journal afin de créer des requêtes, d'utiliser des requêtes enregistrées privées ou de lister et d'obtenir des requêtes partagées:

  • Utiliser des requêtes enregistrées privées : logging.queries.usePrivate
  • Lister et obtenir les requêtes partagées :
    • logging.queries.listShared
    • logging.queries.getShared

• Pour obtenir les autorisations nécessaires pour créer, mettre à jour et supprimer des requêtes partagées, demandez à votre administrateur de vous accorder le rôle IAM Administrateur de journalisation (roles/logging.admin) sur votre projet.

  Ce rôle prédéfini contient les autorisations requises pour créer, mettre à jour et supprimer des requêtes partagées. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

  Autorisations requises

  Les autorisations suivantes sont requises pour créer, mettre à jour et supprimer des requêtes partagées:

  • logging.queries.share
  • logging.queries.updateShared
  • logging.queries.deleteShared

Pour en savoir plus sur les autorisations IAM nécessaires, consultez la page Autorisations pour la console Google Cloud.

Créer des requêtes

Pour créer des requêtes à l'aide de la console Google Cloud, procédez comme suit:

1. Dans la console Google Cloud, accédez à la page Explorateur de journaux.

   Accéder à l'explorateur de journaux

   Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

2. Sélectionnez le projet Google Cloud ou une autre ressource Google Cloud pour laquelle vous souhaitez afficher les journaux.

3. Utilisez le volet Requête pour créer votre requête.

   Le volet Requête propose 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 filtre.
   • Rédigez ou modifiez des requêtes à l'aide de l'éditeur de requêtes.
   • Affichez et exécutez les requêtes enregistrées, récentes et suggérées à partir de la bibliothèque de requêtes menu_book.

Rechercher du texte dans les champs de journaux

Pour rechercher du texte dans tous les champs de journal et trouver toutes les entrées de journal correspondantes, saisissez vos termes de recherche dans le champ de recherche du volet 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 sensible à la casse, vous devez utiliser une expression régulière.

• Pour effectuer une recherche insensible à la casse en fonction des limites des jetons, saisissez les termes de recherche sans guillemets inversés ni guillemets doubles.

  Par exemple, pour rechercher des entrées de journal contenant le mot hello et le mot world, saisissez hello world. Cette commande, qui est convertie en SEARCH("hello world"), correspond aux entrées de journal contenant les jetons hello et world, dans n'importe quel ordre. Étant donné que la recherche est insensible à 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 insensible à la casse d'une expression en fonction des limites des jetons, placez-la entre guillemets.

  Par exemple, pour rechercher la phrase hello world, saisissez `hello world`. Cette commande, qui est convertie en SEARCH("`hello world`"), correspond aux entrées de journal contenant le jeton hello world. La recherche ne correspond pas au jeton hello worlds.

• Pour effectuer une recherche insensible à la casse d'une sous-chaîne, placez 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 des jetons.

Pour afficher vos termes de recherche dans l'expression de requête, activez Afficher la requête.

Après avoir saisi vos termes de recherche, cliquez sur Run query (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

Vos entrées dans le 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 les opérateurs booléens AND, OR et NOT. Lorsque vous utilisez des opérateurs booléens dans vos expressions de recherche, notez les points suivants:

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

Si vous n'incluez aucun opérateur, tous les termes et expressions de recherche sont joints 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 des règles AND et OR dans la même expression. Par exemple, lorsque les deux opérateurs sont mélangés, l'expression a AND b OR c AND d se transforme en l'expression de 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 les 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 avec des menus de filtres

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

Les options des menus Ressource et Nom du journal sont dérivées des entrées de journal stockées par Cloud Logging.

• Resource (Ressource) : permet de spécifier le type de ressource resource.type et le resource.labels associé. Vous pouvez sélectionner un seul type de ressource à l'aide de ce menu de filtre, et appliquer aucun ou plusieurs libellés de ressources à 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é.
• Corréler par: vous permet de regrouper et d'afficher les entrées de journal dans un format "parent-enfant". Pour en savoir plus, consultez la section Corréler les entrées de journal.

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

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

2. affiner les paramètres du filtre ;

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

   Pour afficher vos termes de recherche dans l'expression de requête, activez 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 est affiché avec l'ID de la ressource en sous-texte. Par exemple, pour le type de ressource gce_instance, le nom de la VM s'affiche à côté de son ID. Les noms de ressources vous aident à identifier l'ID de ressource approprié, sur lequel vous pouvez créer des requêtes.

Afficher les journaux par période

Il existe deux méthodes pour afficher les journaux écrits dans 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 une heure de début et de fin personnalisées, ou centrer la période autour d'un code temporel spécifique à l'aide du sélecteur de période. Par exemple, si vous souhaitez afficher les données de la semaine précédente, sélectionnez 1 semaine 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 code temporel, le sélecteur de période est désactivé et la requête utilise l'expression de code temporel comme restriction de période. Si une requête n'utilise pas d'expression d'horodatage, la requête utilise le sélecteur de période comme restriction.

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êtes de l'explorateur de journaux:

1. Si le champ de l'éditeur de requête n'apparaît pas dans le volet Query (Requête), activez Show query (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, ils 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 du journal s'ajustent également 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 bibliothèque de requêtes menu_book, 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 le bouton menu_book Bibliothèque de requêtes dans la barre d'outils principale. Pour les requêtes récentes, vous disposez des options suivantes:

• Diffusion: choisissez cette option pour exécuter la requête et diffuser les résultats.
• Exécuter: choisissez cette option pour exécuter la requête.

• more_vert Autres options : permet d'afficher l'expression de requête avec les options d'exécution de 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. La boîte de dialogue Enregistrer la requête s'ouvre.

  2. Remplissez les champs suivants :

     • Nom (obligatoire): attribuez un nom à votre requête. Les noms ne peuvent pas comporter plus de 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é, puis 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, puis sélectionnez le nombre de caractères à tronquer et si la troncature 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 l'expression de la requête.

Enregistrer et partager des requêtes

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. L'explorateur de journaux comporte une bibliothèque de requêtes, qui vous permet d'accéder aux requêtes enregistrées. Vous pouvez également enregistrer vos requêtes à l'aide de la méthode savedQueries.create de l'API Logging.

Vous pouvez enregistrer votre requête pour qu'elle soit privée et visible par vous seul, ou la partager avec d'autres membres du projet Google Cloud. Une fois que vous avez partagé une requête, vous n'en êtes plus le propriétaire. Tout membre du projet disposant des autorisations nécessaires peut y accéder.

{
  "parent": "projects/my-project/locations/global"
  "savedQueryId": "compute-query"
  {
    "displayName": "compute-admin-activity-query",
    "description": "Queries for Compute Engine Admin Activity logs.",

    "loggingQuery":
      {
        "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
      },
    "visibility": "PRIVATE"
  }
}

Afficher les requêtes enregistrées

Vous pouvez afficher à la fois les requêtes privées et celles qui sont partagées avec d'autres membres du projet Google Cloud en cliquant sur le bouton menu_book Bibliothèque de requêtes:

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

Utiliser les requêtes suggérées

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

Pour afficher et exécuter des requêtes suggérées, cliquez sur le bouton menu_book Bibliothèque de requêtes, puis sur Suggérées. Dans l'onglet Suggestions, vous disposez des options suivantes:

• Diffusion: choisissez cette option pour exécuter la requête et diffuser les résultats.
• Exécuter: choisissez cette option pour exécuter la requête.

• more_vert Autres options : vous permet d'afficher les détails de l'expression de requête avec les options d'exécution ou d'enregistrement de la requête. 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 more_vert Plus et 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, avec les options permettant de l'exécuter, de la lire en streaming ou de l'enregistrer sous:

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

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

    La requête modifiée apparaît dans votre liste Enregistrées, où vous pourrez l'exécuter ultérieurement.

  • Pour exécuter la requête maintenant, cliquez sur Exécuter. La requête s'exécute et s'affiche dans le champ "query-editor".

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

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

Notez les comportements attendus:

• Les chargements de page successifs peuvent ne pas afficher les mêmes requêtes dans le même ordre.
• Il est possible que le système ne renvoie aucune requête suggérée.
• Il arrive que 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 des produits Google Cloud. Ces requêtes peuvent vous aider à trouver efficacement des journaux lors de sessions de dépannage urgentes et à explorer vos journaux pour mieux comprendre les données de journalisation disponibles.

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

1. Dans la console Google Cloud, accédez à la page Explorateur de journaux.

   Accéder à l'explorateur de journaux

   Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

2. Sélectionnez le projet Google Cloud ou une autre ressource Google Cloud pour laquelle vous souhaitez afficher les journaux.

3. Cliquez sur le bouton menu_book Interroger la bibliothèque. Vous voyez les catégories de requêtes disponibles et les sous-ensembles de requêtes en fonction des produits Google Cloud. Pour affiner la sélection des requêtes affichées, 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.

4. 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 more_vert Plus, puis sélectionnez Afficher.

5. Dans la boîte de dialogue Détails de la requête, la requête s'affiche, avec les options permettant de l'exécuter, de la lire en streaming ou de l'enregistrer sous:

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

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

     La requête modifiée apparaît dans votre liste Enregistrées, où vous pourrez l'exécuter ultérieurement.

   • Pour exécuter la requête maintenant, cliquez sur Exécuter. La requête s'exécute et s'affiche dans le champ "query-editor".

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

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

Étape suivante

• Exemples de requêtes