Générer des requêtes de journal (aperçu)

Cette page décrit comment créer des requêtes dans la visionneuse de journaux (aperçu) de Google Cloud Console afin de récupérer, d'affiner et d'analyser les journaux.

Avant de commencer

Vous n'avez pas besoin d'un espace de travail pour utiliser Logging, sauf si vous envoyez des journaux d'Amazon Web Services (AWS) à Logging.

La visionneuse de journaux affiche les journaux d'un seul projet Google Cloud. Si vous utilisez un espace de travail, Logging ne combine pas les journaux des projets surveillés. Vous devez sélectionner un projet spécifique pour afficher ses journaux.

Si vous utilisez un espace de travail et AWS, sélectionnez le projet de connecteur AWS pour afficher les journaux AWS.

Premiers pas

Pour accéder à la visionneuse de journaux (aperçu), procédez comme suit :

  1. Accédez au menu de navigation Google Cloud , puis sélectionnez Journaux > Visionneuse de journaux :
    Accéder à la visionneuse de journaux.
  2. Sélectionnez un projet Google Cloud.
  3. Dans le menu de l'outil de sélection des versions, passez de la version Classic (Classique) de la visionneuse de journaux à la version Preview the new log viewer (Aperçu de la nouvelle visionneuse de journaux).

Vous êtes maintenant dans la visionneuse de journaux (aperçu).

Créer des requêtes

Le volet "Query builder" (Générateur de requêtes) offre plusieurs moyens de récupérer des journaux :

  1. Menus déroulants du générateur de requêtes
  2. Requêtes utilisant le langage du générateur de requêtes
  3. Onglet des requêtes Saved (Enregistrées)

query-builder-pane

Dans les sections suivantes, nous allons voir comment créer et exécuter des requêtes pour récupérer des journaux.

Menus déroulants du générateur de requêtes

Les menus déroulants vous permettent d'ajouter des paramètres de requête au générateur de requêtes. Vous pouvez utiliser les menus déroulants pour sélectionner des ressources, des noms de journaux, le niveau de gravité des journaux et des plages horaires. Ces options correspondent aux champs LogEntry de tous les journaux de la suite des opérations Google Cloud.

Menus déroulants du générateur de requêtes

  • Resource (Ressource) : permet de spécifier resource.type. Vous pouvez sélectionner une seule ressource à ajouter au générateur de requêtes à la fois. Les entrées utilisent l'opérateur logique AND.
  • Log name (Nom de journal) : permet de spécifier logName. Vous pouvez sélectionner simultanément plusieurs noms de journaux à ajouter au générateur de requêtes. Lorsque vous sélectionnez plusieurs entrées, 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 au générateur de requêtes. Lorsque vous sélectionnez plusieurs entrées, l'opérateur logique OR est utilisé.

Pour utiliser l'un des menus des paramètres de recherche, développez-les et sélectionnez un ou plusieurs paramètres, puis cliquez sur Ajouter.

Une fois votre requête créée, cliquez sur Exécuter la requête pour récupérer les entrées de journal souhaitées.

Requêtes avec une restriction de période

Deux méthodes permettent d'interroger les journaux en fonction de la date :

  1. Requête utilisant une expression d'horodatage
  2. Requête utilisant le sélecteur de période

    Section de la visionneuse de journaux présentant deux méthodes de filtrage par date

Lorsque vous rédigez une requête 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 d'horodatage, la requête utilise le sélecteur de période comme restriction.

Requêtes utilisant le langage du générateur de requêtes

Vous pouvez utiliser le langage du générateur de requêtes pour créer des requêtes dans le volet du générateur de requêtes Cloud Logging, l'API Logging ou l'interface de ligne de commande.

Pour en savoir plus, consultez la page Langage du générateur de requêtes.

Vous trouverez ci-dessous quelques suggestions pour optimiser vos requêtes.

Optimiser vos requêtes

Pour trouver plus efficacement les entrées de journal, procédez comme suit :

  • Utilisez des champs indexés.
  • Réduisez le nombre d'entrées de journal à rechercher.

Utiliser les champs indexés

Pour tirer parti de l'index, spécifiez des valeurs exactes pour les champs indexés à l'aide de l'opérateur d'égalité. N'utilisez pas de correspondances de sous-chaîne.

Les champs LogEntry suivants sont indexés :

Les sections suivantes expliquent comment utiliser ces champs indexés pour réduire le nombre d'entrées de journal à interroger.

Trouver des entrées de journal rapidement

Accélérez vos recherches en réduisant le nombre de journaux, le nombre d'entrées de journal ou la durée des recherches. Idéalement, réduisez les trois.

Exemple : Utilisez le nom de journal correct

Précisez le journal contenant les entrées qui vous intéressent. Assurez-vous de connaître le véritable nom du journal en consultant l'une de ses entrées. Par exemple, la visionneuse de journaux indique qu'il existe un journal dans la section Compute Engine nommé "activity_log". En examinant de plus près les entrées du journal d'activité, le journal s'appelle en réalité "compute.googleapis.com/activity_log".

De ce fait, la comparaison suivante est erronée. Elle ne renvoie rien car le nom du journal est incorrect :

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

En revanche, la comparaison suivante est correcte. Elle sélectionne les entrées du journal d'activité. Vous devez indiquer le nom du journal sous forme d'URL, comme suit :

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

Exemple : Choisissez les entrées de journal correctes

Si les entrées de journal que vous recherchez proviennent d'une instance de VM particulière, spécifiez-la. Vérifiez que les noms de libellé sont corrects en inspectant l'une des entrées de journal que vous souhaitez rechercher. Dans l'exemple suivant, instance_id correspond à l'un des libellés indexés :

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

Vous devez spécifier une valeur pour le type de ressource. Sinon, la comparaison de instance_id n'utilise pas l'index.

Exemple : Sélectionnez la période correcte

Vous devez spécifier une période pour effectuer une recherche. Pour déterminer rapidement les horodatages utiles au format RFC 3339, vous pouvez utiliser la commande Gnu/Linux date :

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

Utilisez les valeurs de ces horodatages dans les requêtes suivantes. Pour créer un horodatage acceptable pour Logging, remplacez l'espace entre la date et l'heure par la lettre T.

Par exemple, pour effectuer une recherche dans les trois dernières heures :

    timestamp >= "2016-06-27T14:40:00-04:00"

Autre exemple, pour rechercher entre trois et cinq heures auparavant :

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

Pour un autre exemple d'utilisation de l'horodatage, accédez à Index de champs temporaires sur cette page.

Minimiser les recherches globales et de sous-chaînes

Évitez de céder à la facilité lorsque vous saisissez des requêtes de journalisation.

Exemple : N'utilisez pas de sous-chaînes dans les champs indexés

Vous voulez rechercher une entrée de journal sur le serveur Web Apache2. Vous savez que les journaux Apache sont nommés apache-access et apache-error. Comment procéder ?

  • N'utilisez pas de correspondance de sous-chaîne pour vous éviter la saisie :

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • Utilisez des correspondances exactes lors de la recherche dans les champs indexés :

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

Un champ indexé perd en rapidité lorsque vous effectuez une recherche de sous-chaîne.

Exemple : N'utilisez pas les recherches globales

Vous voulez rechercher une entrée de journal contenant "Hello, Kitty" dans la charge utile :

  • N'effectuez pas une recherche globale. Il s'agit ici de recherches de sous-chaînes :

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • Limitez la recherche à un seul champ, même si vous devez conserver la recherche de sous-chaîne :

        textPayload:"Hello, Kitty"
    
  • Utilisez si possible un test d'égalité :

        textPayload = "Hello, Kitty"
    
  • Faites référence aux champs individuels d'une charge utile si vos entrées de journal possèdent des charges utiles structurées :

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • Utilisez un champ indexé pour limiter la recherche :

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

Exemples de recherches

Les entrées de journal affichées sont celles qui correspondent à la requête dans la zone de requête de recherche. Si le menu Aller à la date contient une valeur, l'affichage défile jusqu'à ce point dans le temps. Voici quelques exemples de requêtes :

resource.type=gae_app

Affiche les mêmes entrées de journal que l'interface de requête de base si vous avez sélectionné Application GAE (Tous les ID de module) dans le menu du journal des ressources et Tous les journaux dans le menu du nom du journal. Pour obtenir la liste des types de ressources, consultez la section Liste de ressources surveillées.

Au fur et à mesure que vous tapez, la visionneuse de journaux suggère de compléter les champs tels que resource.type.

resource.type=gae_app AND logName:request_log

Recherche les entrées de journal des applications App Engine à partir des noms de journaux contenant request_log. Veuillez noter que :

  • L'opérateur = signifie égalité parfaite. Le type de ressource doit correspondre exactement à "gae_app", à ceci près qu'il n'est pas sensible à la casse.
  • L'opérateur : signifie "contient". Le champ logName doit contenir request_log, quelle que soit la casse. Le véritable nom du journal est beaucoup plus long. L'utilisation de : peut ralentir les recherches.
  • Les deux comparaisons sont jointes par AND. Vous pouvez également utiliser OR, mais AND est implicite si vous omettez l'opérateur.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Recherche les entrées de journal avec l'un des deux types de ressources suivants : instance de VM Compute Engine ou instance de VM AWS EC2. Les entrées de journal doivent avoir severity d'au moins ERROR, ce qui équivaut à sélectionner ERREUR dans le menu de gravité de l'interface de requête de base. Vous ne pouvez pas afficher les journaux de plusieurs types de ressources dans l'interface de requête de base.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Affiche toutes les entrées du journal d'audit pour les activités d'administration du projet [PROJECT_ID]. Les journaux d'audit possèdent tous le même nom au sein d'un projet, mais des types de ressources différents. L'ID de journal, cloudaudit.googleapis.com/activity, doit être codé en URL dans le nom du journal. L'utilisation de l'égalité dans la comparaison accélère la recherche. Pour en savoir plus, consultez la page Comprendre les journaux d'audit.

unicorn

Trouve les entrées de journal contenant unicorn dans n'importe quel champ, dans n'importe quelle casse. Un terme de recherche qui ne fait pas partie d'une comparaison de champ est une requête "tous les champs".

unicorn phoenix

Affiche les entrées de journal contenant unicorn dans un champ et phoenix dans un autre.

textPayload:(unicorn phoenix)

Affiche les entrées de journal dont le champ textPayload contient à la fois unicorn et phoenix dans n'importe quel ordre. AND est implicite entre les deux mots.

textPayload:"unicorn phoenix"

Affiche les entrées de journal dont le champ textPayload contient "unicorn phoenix". Il en va de même dans l'interface de requête de base.

textPayload: NOT "unicorn phoenix"

Affiche les entrées de journal dont le champ textPayload ne contient pas la chaîne "unicorn phoenix". Ce type de requête réduit le nombre d'entrées de journal indésirables.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Affiche les entrées de journal créées sur une période de 30 minutes.

Requêtes enregistrées

Le volet du générateur de requêtes comporte un onglet Saved (Enregistrées) qui vous permet d'accéder aux requêtes enregistrées.

Liste des 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 requête créée dans le volet du générateur de requêtes, procédez comme suit :

  1. Cliquez sur Save (Enregistrer) dans le volet du générateur de requêtes. La boîte de dialogue Enregistrer la requête s'ouvre, avec votre expression de requête dans le champ Query (Requête).

  2. Attribuez un nom à votre requête.

    Les noms ne peuvent pas comporter plus de 64 caractères.

  3. Facultatif : Pour ajouter des champs de résumé à votre requête, activez l'option Include summary fields (Inclure des champs de résumé).

  4. Facultatif : Ajoutez une description à votre requête.

    Les descriptions ne peuvent pas comporter plus de 1 000 caractères. N'incluez aucune information sensible.

  5. Dans la boîte de dialogue, cliquez sur Enregistrer la requête.

Vos requêtes enregistrées s'affichent sous forme de liste dans l'onglet Saved (Enregistrées) du volet du générateur de requêtes.

Pour exécuter une requête enregistrée, cliquez sur Exécuter la requête.

Dépannage

Texte sans guillemets

Vous pouvez omettre les guillemets autour des chaînes de texte qui ne contiennent pas d'espaces blancs ou certains caractères spéciaux. C'est ce qu'on appelle le texte sans guillemets, et le mot ERROR en est un exemple comme illustré ci-dessus. La chaîne "v1.compute.instances.insert" est placée entre guillemets, car elle contient des points. Si vous souhaitez inclure des guillemets dans une chaîne, faites-les précéder d'une barre oblique inverse.

Problèmes de syntaxe

Si vous rencontrez des problèmes avec le langage du générateur de requêtes, vérifiez les points suivants :

  • Votre requête respecte les règles de syntaxe. Les parenthèses et les guillemets vont par paires. Votre requête ne peut pas contenir de commentaires.

  • Les noms des champs d'entrée de journal sont correctement orthographiés.

  • Les opérateurs booléens sont en majuscules (AND, OR, NOT).

  • Les expressions booléennes (restrictions globales ou partie droite des comparaisons) doivent être entre parenthèses pour plus de clarté. Par exemple, les deux requêtes ci-dessous se ressemblent, mais ne sont pas équivalentes :

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • Le texte sans guillemets ne doit contenir aucun caractère spécial. En cas de doute, ajoutez des guillemets doubles. Par exemple, la première comparaison ci-dessous est illégale à cause de l'opérateur de sous-chaîne incorporé (:). La comparaison doit être écrite entre guillemets :

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • La commande gcloud logging nécessite que la requête soit entre guillemets doubles. Pour utiliser des guillemets doubles afin d'échapper des caractères spéciaux à l'aide de la commande gcloud logging, enveloppez la totalité de la requête avec des guillemets simples à la place :

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • Si vous rédigez une requête qui inclut un horodatage, vous devez sélectionner Aucune limite dans le sélecteur de période situé sous la zone de requête de recherche.