Requêtes de journaux avancées

Ce guide vous explique comment utiliser la version classique de la visionneuse de journaux pour écrire des requêtes de journaux avancées, qui peuvent spécifier un ensemble d'entrées de journal à partir de n'importe quel nombre de journaux. Les requêtes de journaux avancées peuvent être utilisées dans la version classique de la visionneuse de journaux, l'API Logging ou l'outil de ligne de commande gcloud.

Pour obtenir des options de requête plus simples, accédez à la page Requêtes de journaux de base.

Pour obtenir la liste des requêtes recommandées pour rechercher des journaux, accédez à la page Exemples de requêtes.

Présentation

Une requête de journaux avancée est une expression booléenne qui délimite un sous-ensemble parmi toutes les entrées de journal d'un projet. Elle est destinée à :

  • sélectionner des entrées de journal à partir de journaux ou de services de journalisation spécifiques ;
  • sélectionner des entrées de journal dans un intervalle donné ;
  • sélectionner des entrées de journal correspondant aux critères des métadonnées ou des champs définis par l'utilisateur ;
  • sélectionner un échantillon partiel de toutes les entrées de journal.

Premiers pas avec les requêtes de journaux avancées

Pour utiliser les requêtes de journaux avancées dans la visionneuse de journaux :

  1. Accédez à la page Logging > Journaux (Visionneuse de journaux) de la suite d'opérations Google Cloud dans Cloud Console :

    Accéder à la page Visionneuse de journaux

  2. Sélectionnez un projet Google Cloud existant en haut de la page ou créez-en un.

  3. À l'aide du menu déroulant , sélectionnez la ressource dont vous souhaitez afficher les journaux.

  4. Cliquez sur le menu déroulant  dans la zone de requête de recherche, puis sélectionnez Convertir en filtre avancé.

L'interface utilisateur affiche la conversion en filtre avancé.

Dans l'interface utilisateur, les requêtes de journaux sont associées à la mention "filtres", car elles vous permettent de sélectionner un ensemble spécifique d'entrées de journal.

L'interface de requête des journaux avancée s'affiche :

L'interface utilisateur affiche des options de filtres avancés.

Vous pouvez reconnaître cette interface de requête par l'absence des menus de sélection des journaux et la présence du bouton Submit Filter (Soumettre le filtre). La visionneuse de journaux affiche les entrées de journal qui remplissent toutes les conditions spécifiées dans la requête.

Voici un exemple simple de requête de journal avancée :

    resource.type = "gce_instance" AND
    severity >= ERROR AND
    NOT textPayload:robot

Cette requête correspond aux entrées de journal de Compute Engine dont les valeurs de gravité sont au moins de ERROR et dont le champ textPayload ne contient pas la chaîne robot. Les comparaisons de chaînes ne sont pas sensibles à la casse. Les noms resource, severity et textPayload sont définis dans le type LogEntry.

Suggestions et mise en surbrillance pendant la saisie : lorsque vous saisissez une requête de journaux avancée dans la visionneuse de journaux, des suggestions de champs d'entrée de journal spécifiques peuvent s'afficher. Les suggestions proviennent à la fois du langage de requête et de l'ensemble des entrées de journal réelles chargées par la visionneuse de journaux. Pour choisir une suggestion, appuyez sur TAB. Si les suggestions ne s'affichent pas, essayez d'appuyer sur CTRL + SPACE. Les différentes parties d'une expression de requête sont mises en surbrillance dans différentes couleurs. Si votre expression est en rouge vif, la requête que vous avez saisie peut contenir une erreur ou être incomplète.

Texte sans guillemets : vous pouvez omettre les guillemets autour des chaînes de texte qui ne contiennent pas d'espaces ou certains caractères spéciaux. C'est ce qu'on appelle le texte sans guillemets. Des exemples sont les mots ERROR et robot dans l'exemple précédent. La chaîne "v1.compute.instances.insert" est placée entre guillemets, car elle contient des points. Pour inclure des guillemets dans une chaîne, faites-les précéder d'une barre oblique inverse.

Bonne pratique : ajoutez des guillemets aux chaînes que vous comparez à des valeurs de champ. Ceci évite les erreurs qui modifient le sens de vos comparaisons et sont difficiles à déboguer. Vous pouvez omettre les guillemets dans le cas de mots composés d'une lettre suivie d'une séquence de lettres, de chiffres ou de traits de soulignement (_).

Utilisation d'un clavier : si vous utilisez un clavier pour saisir une requête de journaux avancée dans la zone de requête de recherche, vous pouvez appuyer sur ESC pour quitter le mode d'édition, puis sur TAB pour accéder aux autres options, telles que le menu déroulant ou le bouton Submit Filter (Envoyer le filtre).

Syntaxe des requêtes de journaux avancées

Cette section explique la structure des requêtes de journaux avancées et le processus de mise en correspondance.

Syntaxe

La syntaxe des requêtes de journaux avancées inclut les éléments suivants :

  • a = e signifie que a est le nom de l'expression e.
  • a b signifie "a suivi de b".
  • a | b signifie "a ou b".
  • ( e ) sert au regroupement.
  • [ e ] signifie que e est facultatif.
  • { e } signifie que e peut être répété zéro ou plusieurs fois.
  • "abc" signifie que abc doit être écrit tel quel.

Résumé de la syntaxe

Cette section présente la syntaxe des requêtes de journaux avancées.

Une requête de journaux avancée est une chaîne qui contient une expression :

   expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

Une comparaison est une valeur unique ou une expression booléenne :

  "The cat in the hat"
  resource.type = "gae_app"

La première ligne est un exemple de comparaison exprimé sous la forme d'une valeur unique. Ces types de comparaisons sont des restrictions globales. Chaque champ d'une entrée de journal est comparé à la valeur via l'utilisation implicite de l'opérateur has (contient). Pour cet exemple, si un champ d'une entrée de journal (LogEntry) ou sa charge utile contient l'expression "The cat in the hat" (Le chat dans le chapeau), alors la comparaison est réussie.

La deuxième ligne est un exemple de comparaison qui est une expression booléenne de la forme [FIELD_NAME] [OP] [VALUE]. Les éléments de la comparaison sont décrits ci-dessous :

  • [FIELD_NAME] : est un champ dans une entrée de journal. Exemple :resource.type

  • [OP] : est un opérateur de comparaison. Exemple :=

  • [VALUE] : est un nombre, une chaîne, une fonction ou expression entre parenthèses. Par exemple, "gae_app".

Les sections suivantes donnent plus de détails sur les requêtes et les correspondances.

Opérateurs booléens

Les opérateurs booléens AND et OR sont des opérateurs de court-circuit. L'opérateur NOT possède la priorité la plus élevée, suivi de OR et AND. Par exemple, les deux expressions suivantes sont équivalentes :

a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)

Vous pouvez omettre l'opérateur AND entre les comparaisons. Vous pouvez également remplacer l'opérateur NOT par l'opérateur - (moins). Par exemple, les deux requêtes suivantes sont équivalentes :

a=b AND c=d AND NOT e=f
a=b c=d -e=f

Cette documentation utilise toujours AND et NOT.

Comparaisons

Les comparaisons ont la forme suivante :

[FIELD_NAME] [OP] [VALUE]

Les éléments de la comparaison sont décrits ci-dessous :

  • [FIELD_NAME] : est le nom de chemin d'un champ dans une entrée de journal. Exemples de nom de champ :

    resource.type
    resource.labels.zone
    resource.labels.project_id
    insertId
    jsonPayload.httpRequest.protocol
    labels."compute.googleapis.com/resource_id"
    

    Si un composant du nom d'un chemin d'accès comporte des caractères spéciaux, ce nom doit être entre guillemets doubles. Par exemple, compute.googleapis.com/resource_id doit être entre guillemets doubles, car il contient une barre oblique /.

    Pour en savoir plus, consultez les identificateurs de chemin d'accès à un champ sur cette page.

  • [OP] : est un opérateur de comparaison, parmi les suivants :

    =           # equal
    !=          # not equal
    > < >= <=   # numeric ordering
    :           # "has" matches any substring in the log entry field
    =~          # regular expression search for a pattern
    !~          # regular expression search not for a pattern
    
  • [VALUE] : est un nombre, une chaîne, une fonction ou expression entre parenthèses. Les chaînes comprennent du texte arbitraire, ainsi que des valeurs booléennes, d'énumération et de chaînes d'octets. La valeur [VALUE] est convertie dans le type du champ avant la comparaison.

Si [VALUE] est une combinaison booléenne de comparaisons entre parenthèses, le nom du champ et l'opérateur de comparaison sont appliqués à chaque élément. Exemple :

    jsonPayload.cat = ("longhair" OR "shorthair")
    jsonPayload.animal : ("nice" AND "pet")

La première comparaison vérifie que le champ cat possède la valeur "longhair" (poils longs) ou "shorthair" (poils courts). La seconde vérifie que la valeur du champ animal contient les deux mots "nice" (gentil) et "pet" (animal domestique), dans n'importe quel ordre.

Identificateurs de chemin d'accès à un champ

Toutes les entrées de journal sont des instances de type LogEntry. L'identificateur qui est (ou commence à) la partie gauche d'une comparaison doit être un champ défini dans le type LogEntry. Pour plus de détails sur les identificateurs possibles et leurs valeurs, consultez la page Type LogEntry.

Voici la liste actuelle des champs d'entrée de journal. Chaque champ est suivi du niveau de noms suivant pour ce champ, le cas échéant :

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { variable }
  • labels { variable }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, variable }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

Vous trouverez ci-dessous des exemples d'identificateurs de chemin d'accès à des champs que vous pouvez utiliser dans vos comparaisons :

  • resource.type : si votre premier identificateur de chemin d'accès est resource, l'identificateur suivant doit être un champ de type MonitoredResource.

  • httpRequest.latency : si votre premier identificateur de chemin d'accès est httpRequest, l'identificateur suivant doit être un champ de type HttpRequest.

  • labels.[KEY] Si votre premier identificateur de chemin est labels, l'identificateur suivant, [KEY], doit être l'une des clés des paires clé/valeur figurant dans le champ labels.

  • logName : le champ logName étant une chaîne, vous ne pouvez pas le faire suivre de noms de sous-champs.

Caractères spéciaux

Si un champ LogEntry contient des caractères spéciaux, le champ de journal doit être entre guillemets. Exemple :

  jsonPayload.":name":apple

  jsonPayload."foo.bar":apple

  jsonPayload."\"foo\"":apple

Pour obtenir la liste des caractères spéciaux, consultez la section string de la page Valeurs et conversions.

Pour en savoir plus sur l'utilisation d'identificateurs de chemin d'accès à un champ faisant référence à des objets ou des tableaux, accédez à la section Types d'objets et de tableaux sur cette page.

Types de ressources surveillées

Pour des requêtes plus rapides, spécifiez le type des ressources surveillées. Pour obtenir la liste des types de ressources, consultez la section Types de ressources surveillées.

Par exemple, les VM Compute Engine utilisent le type de ressource gce_instance et les instances Amazon EC2 utilisent aws_ec2_instance. L'exemple suivant montre comment limiter vos requêtes à ces deux types de VM :

    resource.type = ("gce_instance" OR "aws_ec2_instance")

Les valeurs des types de ressources surveillées dans les journaux sont indexées. L'utilisation de correspondances de sous-chaînes ralentit les requêtes.

Champs non renseignés

Si vous utilisez un nom de champ dans une requête et que ce champ n'apparaît pas dans une entrée de journal, le champ est manquant, indéterminé, ou défini par défaut :

  • Si le champ fait partie de la charge utile de l'entrée de journal (jsonPayload ou protoPayload) ou s'il figure dans une étiquette de la section labels de l'entrée de journal, le champ est manquant. L'utilisation d'un champ manquant n'affichera pas d'erreur, mais toutes les comparaisons utilisant des champs manquants échoueront en silence.

    Exemples : jsonPayload.nearest_store, protoPayload.name.nickname

  • Si le champ est défini dans le type LogEntry, le champ est défini par défaut. Les comparaisons sont effectuées comme si le champ était présent et avait sa valeur par défaut.

    Exemples : httpRequest.remoteIp, trace, operation.producer

  • Sinon, le champ n'est pas défini, ce qui correspond à une erreur détectée avant l'utilisation de la requête.

    Exemples : thud, operation.thud, textPayload.thud

Pour tester si un champ manquant ou par défaut existe sans tester une valeur particulière de ce champ, utilisez la comparaison :*. Par exemple, la comparaison suivante réussit si le champ operation.id est explicitement présent dans une entrée de journal :

operation.id:*

Observez le comportement des requêtes suivantes :

  • Lorsque vous utilisez l'opérateur booléen NOT sur un champ manquant, le résultat est TRUE :

    # Returns TRUE
    NOT missingField=foo
    
  • Lorsque vous utilisez l'opérateur de comparaison d'inégalité != sur un champ manquant, le résultat est FALSE :

    # Returns FALSE
    missingField!=foo
    

Types d'objets et de tableaux

Chaque champ d'entrée de journal peut contenir un scalaire, un objet ou un tableau.

  • Un champ scalaire stocke une seule valeur, telle que 174.4 ou -1. Un string est également considéré comme un scalaire. Les champs pouvant être convertis en (ou à partir de) chaîne, tels que Duration et Timestamp sont également de type scalaire.

  • Un type d'objet stocke un ensemble de valeurs nommées, semblable à la valeur JSON suivante :

    {"age": 24, "height": 67}
    

    Vous pouvez faire référence à la valeur à l'intérieur d'un objet. Par exemple, si jsonPayload.x contient la valeur précédente, alors jsonPayload.x.age aura la valeur 24.

  • Un champ de type tableau stocke une liste de valeurs, toutes du même type. Par exemple, un champ contenant des mesures peut avoir un tableau de nombres :

    {8.5, 9, 6}
    

    Lorsque des comparaisons sont effectuées et que [FIELD_NAME] est un champ de tableau, chaque partie du tableau est comparée à [VALUE] et les résultats sont joints à l'aide de l'opérateur OR. Par exemple, si jsonPayload.shoeSize est un champ de tableau qui stocke {8.5, 9, 6}, la comparaison :

    jsonPayload.shoeSize < 7
    

    équivaut à :

    8.5 < 7 OR 9 < 7 OR 6 < 7
    

    Dans cet exemple, la comparaison globale est évaluée comme réussie.

Valeurs et conversions

La première étape de l'évaluation d'une comparaison consiste à convertir la valeur de droite en type de champ d'entrée de journal. Les types de champs scalaires sont autorisés dans les comparaisons, ainsi que deux types supplémentaires dont les valeurs sont représentées par des chaînes : Duration et Timestamp. Pour obtenir la liste des types scalaires, accédez à la liste types de tampons de protocole scalaires. Le tableau suivant explique quelles valeurs peuvent être converties en types de champs de journal :

Type de champ Valeur de requête autorisée
bool

"True" ou "false" dans n'importe quelle casse. Exemples : "True", "true"

bytes

Chaîne contenant n'importe quelle séquence d'octets. Exemple : "\377\377".

Duration

Chaîne contenant un nombre décimal signé suivi de l'une des unités "ns", "us", "ms", "s", "m" ou "h". Les durées sont exprimées avec une précision de l'ordre de la nanoseconde. Exemple : "3,2 s".

enum

Nom d'un type d'énumération littéral, non sensible à la casse. Exemples : "WARNING", qui est une valeur de type LogSeverity.

double

Tout nombre, avec ou sans signe, ni partie exponentielle, ou les chaînes de valeurs spéciales "NaN", "-Infinity" et "Infinity" (en majuscules ou non). Exemples : "-3.2e-8", "nan".

intNN

Tout entier signé ne dépassant pas la taille du type. Exemple : "-3".

string

Toute chaîne contenant du texte encodé en UTF-8 ou en ASCII sur 7 bits. Les guillemets intégrés doivent être échappés avec une barre oblique inverse.

Les valeurs de chaîne doivent être entre guillemets pour échapper les caractères spéciaux suivants :

  • Chaînes commençant par + (plus), - (moins) ou . (point).

  • Chaînes comportant les caractères ~ (tilde), = (égal), () (parenthèses), : (deux-points), > (supérieur à), < (inférieur à), , (virgule) ou . (point).

  • Toutes les séquences d'échappement, par exemple \t.

Timestamp

Une chaîne au format RFC 3339 ou au format ISO 8601. Exemples : "2014-10-02T15:01:23.045Z" (RFC 3339), "2014-10-02" (ISO 8601). Dans les expressions de requête, les horodatages au format RFC 3339 peuvent mentionner un fuseau horaire avec "Z" ou ±hh:mm. Les horodatages bénéficient d'une précision de l'ordre de la nanoseconde.

uintNN

Tout entier non signé qui ne dépasse pas la taille du type. Exemple : "1234".

Si une tentative de conversion échoue, la comparaison échoue.

Lorsqu'une conversion nécessite une chaîne, vous pouvez également utiliser un nombre ou un texte non mis entre guillemets s'ils ne contiennent pas de caractères spéciaux tels que des espaces et des opérateurs. De même, lorsqu'une conversion nécessite un nombre, vous pouvez utiliser une chaîne dont le contenu est un nombre.

Les types intNN et uintNN représentent des types entiers de différentes tailles, tels que int32 et uint64. Lorsque vous écrivez une valeur à convertir en type d'entier de 64 bits, vous devez écrire la valeur sous forme de chaîne, telle que "9223372036854775807".

Types de champs de journal

Voici comment le type d'un champ d'entrée de journal est déterminé :

  • Les champs de journal définis par le type LogEntry et le type composant sont des champs de tampon de protocole. Les champs de tampon de protocole possèdent des types explicites.

  • Les champs de journal qui font partie d'objets protoPayload sont également des champs de tampon de protocole et possèdent des types explicites. Le nom du type de tampon de protocole est stocké dans le champ "@type" de protoPayload. Pour en savoir plus, consultez le mappage JSON.

  • Les champs de journal de jsonPayload possèdent des types déduits de la valeur du champ lorsque l'entrée de journal est reçue :

    • Les champs dont les valeurs sont des nombres sans guillemets sont de type double.
    • Les champs dont les valeurs sont true ou false sont de type bool.
    • Les champs dont les valeurs sont des chaînes sont de type string.

    Les entiers longs (64 bits) sont stockés dans des champs de type chaîne, car ils ne peuvent être représentés exactement comme valeurs de type double.

  • Les types Duration et Timestamp ne sont reconnus que dans les champs de tampon de protocole. Dans tous les autres contextes, ces valeurs sont stockées dans des champs de type chaîne.

Opérateurs de comparaison

Le sens des opérateurs d'égalité (=, !=) et d'inégalité (<, <=, >, >=) dépendent du type sous-jacent du nom de champ à gauche.

  • Tous les types numériques : l'égalité et l'inégalité s'appliquent de façon normale aux nombres.
  • bool : l'égalité signifie la même valeur booléenne. L'inégalité est définie par true> false.
  • enum : l'égalité signifie la même valeur d'énumération. L'inégalité utilise les valeurs numériques sous-jacentes des littéraux d'énumération.
  • Duration : l'égalité signifie la même durée. L'inégalité est basée sur la durée du délai. Exemple : en tant que durées, "1s"> "999ms".
  • Timestamp : l'égalité signifie le même instant temporel. Si a et b sont des valeurs Timestamp, a < b signifie que a est antérieur à b.
  • bytes : les opérandes sont comparés octet par octet, de gauche à droite.
  • string : les comparaisons ignorent les lettres majuscules. Plus précisément, les deux opérandes sont d'abord normalisés en utilisant la normalisation Unicode NFKC_CF, puis font appel à des comparaisons lexicographiques. En revanche, les recherches d'expressions régulières ne sont pas normalisées. Pour en savoir plus sur la recherche d'entrées de journal à l'aide d'expressions régulières, consultez la section Interroger et filtrer des entrées de journal avec des expressions régulières.

L'opérateur de sous-chaîne (:) est applicable à string et bytes. Il est traité comme une égalité, sans que l'opérande de droite ait besoin d'être égal à la totalité du champ de gauche. Les correspondances de sous-chaînes sur les champs indexés ne tirent pas parti des index de journal.

Restrictions globales

Si la comparaison consiste en une valeur unique, cela s'appelle une restriction globale. Logging utilise l'opérateur has (contient) (:) pour déterminer si un champ dans une entrée de journal, ou sa charge utile, contient la restriction globale. Si c'est le cas, la comparaison réussit.

La requête la plus simple rédigée en termes de restriction globale est une valeur unique :

"The Cat in The Hat"

Vous pouvez combiner des restrictions globales en utilisant les opérateurs AND et OR pour obtenir une requête plus intéressante. Par exemple, si vous souhaitez afficher toutes les entrées de journal comportant un champ contenant cat et un champ contenant hat ou bat, écrivez la requête comme suit :

(cat AND (hat OR bat))

Dans ce cas, il existe trois restrictions globales : cat, hat et bat. Ces restrictions globales sont appliquées séparément et les résultats sont combinés, comme si l'expression avait été écrite sans parenthèses.

Une restriction globale facilite l'interrogation d'une valeur particulière dans un journal. Par exemple, si vous recherchez dans votre journal d'activité des entrées contenant la mention GCE_OPERATION_DONE, vous pouvez utiliser la requête suivante :

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

Bien que les restrictions globales soient faciles, elles peuvent être lentes. Pour en savoir plus, consultez la section Trouver des entrées de journal rapidement sur cette page.

Fonctions

Vous pouvez utiliser les fonctions intégrées comme restrictions globales dans les requêtes avancées :
function = identifier ( [ argument { , argument } ] )

argument est une valeur, un nom de champ ou une expression entre parenthèses. Les fonctions sont décrites dans les sections suivantes.

log_id

La fonction log_id renvoie les entrées de journal correspondant à l'argument [LOG_ID] spécifié dans le champ logName :

  log_id([LOG_ID])

Par exemple, la requête suivante renvoie toutes les entrées de journal avec un [LOG_ID] cloudaudit.googleapis.com%2Factivity :

  log_id("cloudaudit.googleapis.com/activity")

sample

La fonction sample sélectionne une partie du nombre total d'entrées de journal :

sample([FIELD], [FRACTION])

[FIELD] correspond au nom d'un champ dans l'entrée de journal, tel que logName ou jsonPayload.a_field. La valeur du champ détermine si l'entrée de journal fait partie de l'échantillon. Le type de champ doit être une chaîne ou une valeur numérique. Définir [FIELD] sur insertId est un bon choix, car chaque entrée de journal a une valeur différente pour ce champ.

[FRACTION] est la fraction des entrées du journal qui ont des valeurs pour [FIELD] à inclure. C'est un nombre supérieur à 0,0 et inférieur à 1,0. Par exemple, si vous spécifiez 0.01, l'échantillon contient environ 1 % de toutes les entrées de journal ayant des valeurs pour [FIELD]. Si [FRACTION] vaut 1, toutes les entrées de journal dotées de valeurs pour [FIELD] sont retenues.

Exemple : la requête suivante renvoie 25 % des entrées de journal du journal syslog :

    logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

Précisions : un algorithme déterministe, basé sur le hachage, est utilisé pour déterminer si une entrée de journal est incluse ou exclue de l'échantillon. La précision de l'échantillon résultant dépend de la distribution des valeurs hachées. Si les valeurs hachées ne sont pas distribuées uniformément, l'échantillon résultant peut être faussé. Dans le pire des cas, lorsque [FIELD] contient toujours la même valeur, l'échantillon contient soit la [FRACTION] de toutes les entrées du journal, soit aucune entrée du journal.

Si [FIELD] apparaît dans une entrée de journal, alors :

  • Un hachage de la valeur est calculé.
  • La valeur hachée, qui est un nombre, est divisée par la valeur hachée maximale possible.
  • Si la fraction résultante est inférieure ou égale à [FRACTION], l'entrée du journal est incluse dans l'échantillon, sinon, elle est exclue de l'échantillon.

Si [FIELD] n'apparaît pas dans une entrée de journal, alors :

  • Si [FIELD] fait partie de la charge utile de l'entrée de journal ou des sections labels, l'entrée de journal n'est pas sélectionnée pour l'exemple, même si [FRACTION] vaut 1.
  • Sinon, l'entrée de journal est traitée comme si [FIELD] était dans l'entrée de journal et que la valeur de [FIELD] était la valeur par défaut. La valeur par défaut est déterminée par le type LogEntry. Pour en savoir plus sur les champs manquants et définis par défaut, consultez la section Champs non renseignés sur cette page.

Pour exclure de l'échantillon les entrées de journal dotées de champs par défaut, utilisez l'opérateur "le champ existe", :*. La requête suivante génère un échantillon de 1 % des entrées de journal qui possèdent une valeur explicitement définie pour field :

field:* AND sample(field, 0.01)

ip_in_net

La fonction ip_in_net détermine si une adresse IP d'une entrée de journal fait partie d'un sous-réseau. Utilisez-la pour savoir, par exemple, si une requête provient d'une source interne ou externe. Exemple :

ip_in_net([FIELD], [SUBNET])

[FIELD] est un champ de valeur de chaîne d'entrée de journal qui contient une adresse ou une plage d'adresses IP. Le champ peut être répété, auquel cas un seul des champs répétés doit posséder une adresse ou une plage d'adresses contenue dans le sous-réseau.

[SUBNET] est une constante de type chaîne d'une adresse IP ou d'une plage d'adresses IP. C'est une erreur si [SUBNET] n'est pas une adresse IP ni une plage d'adresses IP légitime, comme décrit plus loin dans cette section.

Exemple : la requête suivante teste une adresse IP dans la charge utile des entrées de journal à partir du journal my_log :

    logName = "projects/my_project/logs/my_log" AND
    ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

Informations : Si, dans une entrée de journal, [FIELD] est manquant, défini par défaut, ou s'il ne contient pas d'adresse ou de plage d'adresses IP légitime, la fonction renvoie la valeur "false". Pour en savoir plus sur les champs manquants et définis par défaut, consultez la section Champs non renseignés sur cette page.

Exemples d'adresses IP et de plages compatibles :

  • IPv4 : 10.1.2.3
  • Sous-réseau IPv4 : 10.1.2.0/24
  • CIDR IPv6 : 1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • Sous-réseau CIDR IPv6 : 1:2::/48

Rechercher par heure

Dans l'interface, vous pouvez définir des limites spécifiques concernant la date et l'heure des entrées de journal à afficher. Par exemple, si vous ajoutez les conditions suivantes à votre requête, la visionneuse de journaux affiche exactement les entrées de journal dans la période de 30 minutes indiquée, et vous ne pourrez pas faire défiler l'écran en dehors de cette plage de dates :

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

Lorsque vous rédigez une requête avec un horodatage, vous devez mettre en forme les dates et les heures comme indiqué ci-dessus.

Vous devez également sélectionner l'option Aucune limite dans le sélecteur de période situé sous la zone de requête de recherche.

Vous pouvez également rechercher des entrées de journal à l'aide des raccourcis timestamp. Par exemple, vous pouvez saisir une date avec un opérateur de comparaison pour obtenir toutes les entrées de journal créées après un jour précis :

  timestamp > "2016-11-29"

Utiliser des expressions régulières

Vous pouvez utiliser des expressions régulières pour créer des requêtes et des filtres pour les récepteurs, les métriques et partout où les filtres de journal sont utilisés. Vous pouvez utiliser des expressions régulières dans le générateur de requêtes et avec l'outil de ligne de commande gcloud command-line tool.

Une expression régulière est une séquence de caractères définissant une recherche. Le langage de requête utilise la syntaxe RE2. Pour obtenir une explication complète de la syntaxe RE2, accédez au wiki RE2 sur GitHub.

Les requêtes utilisant des expressions régulières présentent les caractéristiques suivantes :

  • Seuls les champs de type chaîne peuvent être mis en correspondance avec une expression régulière.

  • Les chaînes ne sont pas normalisées. Par exemple, kubernetes n'est pas considéré comme identique à KUBERNETES. Pour en savoir plus, consultez la section Opérateurs de comparaison.

  • Les requêtes sont sensibles à la casse et ne sont pas ancrées par défaut.

  • Les opérateurs booléens peuvent être utilisés entre plusieurs expressions régulières à droite de l'opérateur de comparaison d'expressions régulières, =~ et !~.

Une requête avec une expression régulière possède la structure suivante :

Correspondance avec un modèle :

jsonPayload.message =~ "regular expression pattern"

Aucune correspondance avec un modèle :

jsonPayload.message !~ "regular expression pattern"

Les opérateurs =~ et !~ transforment la requête en une requête avec des expressions régulières. Le modèle que vous essayez de mettre en correspondance doit être entre guillemets doubles. Pour rechercher des modèles qui contiennent des guillemets doubles, vous pouvez les échapper avec une barre oblique inverse.

Exemples d'interrogation de journaux à l'aide d'expressions régulières

Type de requête Exemple
Requête standard sourceLocation.file =~ "foo"
Requête avec une recherche non sensible à la casse labels.subnetwork_name =~ "(?i)foo"
Requête contenant des guillemets jsonPayload.message =~ "field1=\"bar.*\""
Requête utilisant une valeur booléenne or labels.pod_name =~ "(foo|bar)"
Requête utilisant des ancres logName =~ "/my%2Flog$"
Requête ne correspondant pas à un modèle labels.pod_name !~ "foo"
Requête utilisant un opérateur booléen labels.env =~ ("^prod.*server" OR "^staging.*server")

Trouver des entrées de journal rapidement

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

  • Exécutez une requête à l'aide de champs indexés.
  • Réduisez le nombre d'entrées de journal à rechercher.

Utiliser les champs indexés

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.

Optimiser vos requêtes

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 dans la section Compute Engine un journal nommé "activity". En examinant de plus près les entrées du journal des activités d'administration, vous constatez que le journal s'appelle en réalité "cloudaudit.googleapis.com/activity".

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"   # WRONG!

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

    logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

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 :

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

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 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 de journaux avancée de 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.

NOT textPayload: "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.

Dépannage

Navigation à l'aide du clavier

Si vous utilisez un clavier pour saisir une requête avancée dans la zone de requête de recherche et que vous devez accéder aux autres menus de la page, appuyez sur ESC pour quitter le mode d'édition, puis appuyez sur TAB pour accéder aux autres options.

Problèmes de syntaxe

Si vous rencontrez des problèmes avec les expressions de vos requêtes avancées, 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"
    
  • L'outil de ligne de commande gcloud exige 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 de 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"'
    
  • Les expressions de recherche dans les requêtes de base de la visionneuse de journaux sont différentes des expressions de recherche dans les requêtes de journaux avancées. Pour en savoir plus, consultez la page Différences entre les requêtes de base et avancées.

  • 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.