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 sélectionnant des options de filtrage prédéfinies. 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 "Explorateur de journaux" ou à l'aide de la méthode d'API Logging savedQueries.create.

Avant de commencer

Le rôle Lecteur de journaux (roles/logging.viewer) permet d'afficher les journaux. Par exemple, lorsque ce rôle vous est attribué, vous pouvez rédiger et exécuter des requêtes. Vous pouvez également enregistrer des requêtes en tant que requêtes privées et exécuter des requêtes privées et partagées. Toutefois, ce rôle ne vous permet pas d'enregistrer ni de modifier les requêtes partagées. Si vous souhaitez enregistrer ou modifier des requêtes partagées, assurez-vous de disposer du rôle Administrateur Logging (roles/logging.admin), qui vous donne un accès complet à Cloud Logging.

Effectuez l'une des opérations suivantes :

  • Pour obtenir les autorisations nécessaires pour écrire et exécuter des requêtes, exécuter et enregistrer des requêtes privées, et exécuter des requêtes partagées, demandez à votre administrateur de vous accorder le rôle IAM Lecteur de journaux (roles/logging.viewer) sur votre projet.

  • Pour obtenir les autorisations nécessaires pour écrire et exécuter des requêtes, exécuter et enregistrer des requêtes privées, et exécuter, créer et gérer des requêtes partagées, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Logging (roles/logging.admin) sur votre projet.

Pour en savoir plus sur les autorisations IAM nécessaires, consultez 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 Cloudpour laquelle vous souhaitez afficher les journaux.

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

    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 journaux.
    • Sélectionnez des options dans les menus de filtre.
    • Rédigez ou modifiez des requêtes à l'aide de l'éditeur de requête.
    • Affichez et exécutez des requêtes enregistrées, récentes et suggérées à partir de la bibliothèque de requêtes .

Rechercher du texte dans les champs de journaux

Pour rechercher du texte dans tous les champs de journaux et trouver toutes les entrées de journaux correspondantes, saisissez vos termes de recherche dans le champ de recherche du volet Requête.

Vous pouvez rechercher des mots et des expressions. 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 non sensible à la casse le long des limites des jetons, saisissez les termes de recherche sans accent grave ni guillemets doubles.

    Par exemple, pour rechercher les entrées de journal contenant les mots hello et world, saisissez hello world. Cette commande, qui est convertie en SEARCH("hello world"), correspond aux entrées de journal qui contiennent les jetons hello et world, dans n'importe quel ordre. Comme la recherche ne tient pas compte de 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 d'une expression le long des limites de jeton, placez l'expression entre accents graves.

    Par exemple, pour rechercher l'expression 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 non sensible à la casse pour 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 le long 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 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 les 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 de l'expression de recherche sont analysées comme des 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 les 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 suivante du langage de requête Logging :

"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 niveau 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 proviennent des entrées de journal stockées par Cloud Logging.

  • Resource (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 appliquer aucun ou plusieurs libellés de ressources à votre requête. Les paramètres de ressource sont reliés 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 au format "parent-enfant". Pour en savoir plus, consultez Corréler les entrées de journal.

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

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

  2. Affinez 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 s'affichent 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 la ressource en sous-titre. 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 plage de temps

Il existe deux façons d'afficher les journaux écrits dans une plage de temps spécifique :

  1. Utilisez le sélecteur de période.
  2. Incluez une expression d'horodatage 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 sélectionner une période prédéfinie, 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 dernière, sélectionnez 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 d'horodatage dans le champ de l'éditeur de requête

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

Si le champ de l'éditeur de requête 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, elle 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 Requête, activez 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 filtres, ils s'affichent également dans le champ de l'éditeur de requête et sont évalués dans l'expression de votre 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 , 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 Bibliothèque de requêtes dans la barre d'outils principale. Pour les requêtes récentes, vous disposez des options suivantes :

  • Diffuser : sélectionnez cette option pour exécuter la requête et diffuser les résultats.
  • Exécuter : sélectionnez cette option pour exécuter la requête.

  • Autres options : vous permet d'afficher l'expression de requête ainsi que l'option 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. La boîte de dialogue Enregistrer la requête s'ouvre.

    2. Remplissez les champs suivants :

      • Nom (obligatoire) : donnez 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 synthèse, puis saisissez les champs de résumé que vous souhaitez afficher.
      • Tronquer les champs de synthèse (facultatif) : activez l'option Tronquer les champs de synthèse, 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 à vos 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 de manière privée afin qu'elle ne soit visible que par vous, ou vous pouvez 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.

Console

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) : donnez 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 des champs de résumé personnalisés (facultatif) : activez l'option Inclure les champs de synthèse, puis saisissez les champs de synthèse que vous souhaitez afficher.
    • Tronquer les champs de synthèse (facultatif) : activez l'option Tronquer les champs de synthèse, 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.
    • Partager avec le projet : si vous le souhaitez, activez l'option Partager avec le projet pour partager votre requête avec d'autres membres du projet Google Cloud .

  3. Cliquez sur Enregistrer la requête. Vos requêtes enregistrées s'affichent sous forme de liste dans l'onglet 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 Diffuser.

Pour modifier une requête enregistrée, sélectionnez Plus d'options, puis  Modifier. Vous pouvez également sélectionner la requête, la modifier, puis l'enregistrer.

Pour supprimer une requête enregistrée, sélectionnez Plus d'options, puis Supprimer.

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

API

Pour enregistrer une requête à l'aide de l'API Logging, utilisez la méthode savedQueries.create. Pour en savoir plus sur cette méthode, ses paramètres et les données de réponse, consultez la page de référence de savedQueries.create.

Vous pouvez exécuter la méthode savedQueries.create à l'aide du widget APIs Explorer sur la page de référence de la méthode. Pour les requêtes de l'explorateur de journaux, vous devez spécifier le champ loggingQuery. L'exemple suivant illustre un exemple de corps de requête contenant une instance de SavedQuery :

{
  "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"
  }
}

Pour partager la requête avec d'autres membres du projet Google Cloud , spécifiez la valeur SHARED dans le champ visibility.

Afficher les requêtes enregistrées

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

Console

  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 Cloudpour laquelle vous souhaitez afficher les journaux.

  3. Cliquez sur le bouton Bibliothèque de requêtes, puis sur Enregistrées.

Vous pouvez trier le tableau par n'importe quel en-tête. La colonne Visibilité indique si les requêtes sont partagées ou privées :

  • Partagées : requêtes partagées avec d'autres membres du projetGoogle Cloud .
  • Privé : requêtes que vous avez enregistrées et qui ne sont visibles que par vous.

API

Vous pouvez utiliser l'API Logging pour afficher les requêtes privées et partagées à l'aide de la méthode savedQueries.list.

Par exemple, le corps de requête suivant liste toutes les requêtes partagées de l'explorateur de journaux avec un ID d'emplacement générique :

{
  "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 en fonction du contexte de votre projetGoogle 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 Bibliothèque de requêtes, puis sur Suggérées. Dans l'onglet Suggestions, vous disposez des options suivantes :

  • Diffuser : sélectionnez cette option pour exécuter la requête et diffuser les résultats.
  • Exécuter : sélectionnez cette option pour exécuter la requête.

  • Autres options : vous 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, avec les options permettant de l'exécuter, de la diffuser 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 de l'éditeur de requête.

    • Pour exécuter la requête maintenant et diffuser les résultats, 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 suivants :

  • Les chargements de page successifs peuvent ne pas afficher les mêmes requêtes dans le même ordre.
  • Il arrive 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ées sur des cas d'utilisation et des produits Google Cloud courants. 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 Cloudpour laquelle vous souhaitez afficher les journaux.

  3. Cliquez sur le bouton Bibliothèque de requêtes. Vous voyez des catégories de requêtes disponibles et des sous-ensembles de requêtes basés sur les produits Google Cloud. Pour affiner la sélection de 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 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 diffuser 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 de l'éditeur de requête.

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

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

Étapes suivantes