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

Ce document explique comment récupérer et analyser des 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 de l'API Logging savedQueries.create.

Avant de commencer

  • Pour créer des requêtes, vous devez disposer des autorisations nécessaires pour 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 enregistrer des requêtes, votre rôle Identity and Access Management doit inclure l'autorisation logging.queries.{list, create, get, update, delete}.

  • 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 Logging" (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 depuis 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 page 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:

    • rechercher du texte dans tous les champs de journal ;
    • Sélectionnez des options dans les menus de filtrage.
    • Rédigez 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écents, Enregistrés, 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. Ceux-ci 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 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"), établit une correspondance avec les entrées de journal contenant les jetons hello et world, dans n'importe quel ordre. Étant donné que 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 de 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`"), fait correspondre 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 selon les limites du jeton.

Pour voir 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

Vos entrées de champ de recherche sont converties en expressions booléennes qui spécifient un sous-ensemble de toutes les entrées de journal dans 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 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 à 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 de 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 fichier resource.type et la propriété resource.labels associée. Vous pouvez sélectionner un seul type de ressource à l'aide de ce menu de filtre, ainsi que zéro ou plusieurs libellés de ressources à appliquer à 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é.

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

  1. Développez le menu dans n'importe quel menu 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 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 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. Ces noms 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 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 d'horodatage 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ête 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 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 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 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écentes dans le volet Requête. Dans l'onglet Récents, vous disposez des options suivantes:

  • Diffusion en flux continu: pour exécuter la requête et diffuser les résultats, choisissez cette option.
  • Exécuter: sélectionnez 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 des champs de résumé, puis saisissez les champs de résumé que vous souhaitez afficher.
      • Truncate summaryfields (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. Indiquez également si la troncation se produit 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

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. Le volet Requête de l'explorateur de journaux comporte un onglet Enregistré dans lequel vous pouvez 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.

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): 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 des champs de résumé personnalisés (facultatif): activez l'option Inclure des champs de résumé et saisissez les champs de résumé que vous souhaitez afficher.
    • Truncate summaryfields (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. Indiquez également si la troncation se produit au début ou à la fin des champs.
  3. 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 Diffuser.

Vous pouvez également trier et filtrer vos requêtes enregistrées. Le filtre correspond au texte de votre expression de 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 Explorateur d'API 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, qui contient 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"
}
}

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

Console

Vous pouvez partager des 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 Autres options, puis Modifier, ou sélectionnez la requête directement.

  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.

API

Pour créer une requête partagée à l'aide de l'API Logging, utilisez la méthode savedQueries.Create et spécifiez la valeur SHARED dans le champ visibility.

Afficher les requêtes partagées

Console

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 de quelle manière:

  • Partagées 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ées: 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 Mes requêtes. 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, tel que 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, lorsqu'il détecte que vous utilisez Google Kubernetes Engine, Logging peut suggérer une requête qui trouve tous les journaux d'erreurs pour 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:

  • Diffusion en flux continu: pour exécuter la requête et diffuser les résultats, choisissez cette option.
  • Exécuter: sélectionnez 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, vous voyez la requête et 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 apparaît dans votre liste 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 Diffuser.

    • Pour fermer la boîte de dialogue et revenir à la liste des requêtes suggérées, cliquez sur Close (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 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ées sur des cas d'utilisation courants et des produits Google Cloud. Ces requêtes peuvent vous aider à trouver efficacement les journaux lors des sessions de dépannage critiques et à les explorer 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. Sélectionnez l'onglet Bibliothèque dans le volet Requête.

  2. Dans la colonne Toutes les requêtes, vous trouverez des catégories générales de requêtes disponibles et des sous-ensembles de requêtes basés sur les produits Google Cloud. Pour affiner la sélection des requêtes à l'écran, cliquez sur l'un des produits.

    Vous pouvez également utiliser le champ de recherche pour effectuer une recherche dans 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, vous voyez la requête et 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 apparaît dans votre liste 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 Diffuser.

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

Étapes suivantes