Ce guide explique comment créer des filtres de journaux avancés, c'est-à-dire des expressions destinées à isoler un ensemble d'entrées à partir d'un nombre quelconque de journaux. Les filtres de journaux avancés peuvent être utilisés dans la visionneuse de journaux, dans l'API Stackdriver Logging ou dans l'interface de ligne de commande.
Pour plus d'options de filtrage de base, consultez la page Filtres de journaux de base.
Pour obtenir la liste des filtres recommandés pour la recherche de journaux, accédez à la page Bibliothèque de filtres avancés.
Présentation
Un filtre de journaux avancé est une expression booléenne qui délimite un sous-ensemble parmi toutes les entrées de journal d'un projet. Il est destiné à :
- 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 filtres de journaux avancés
Pour utiliser les filtres de journaux avancés dans la visionneuse de journaux, procédez comme suit :
Accédez à la page Stackdriver Logging > Journaux (Visionneuse de journaux) dans la console GCP :
Sélectionnez un projet GCP existant en haut de la page, ou créez un projet.
À l'aide des menus déroulants, sélectionnez la ressource pour laquelle vous souhaitez afficher les journaux.
Cliquez sur la flèche du menu déroulant (▾) tout à droite de la zone de recherche de filtre, puis sélectionnez Convert to advanced filter (Convertir en filtre avancé).
L'interface des filtres de journaux avancés ci-dessous s'affiche :
Cette interface se distingue par l'absence de menus de sélection de journal et la présence du bouton Submit Filter (Envoyer le filtre). La visionneuse de journaux affiche les entrées de journal qui remplissent toutes les conditions spécifiées dans le filtre.
Voici un exemple simple de filtre de journaux avancé :
resource.type = "gce_instance" AND
severity >= ERROR AND
NOT textPayload:robot
Ce filtre va renvoyer les entrées de journal de Compute Engine d'un degré de gravité au moins équivalent à 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 par le type LogEntry.
Suggestions et mise en surbrillance lors de la saisie
Lorsque vous créez un filtre de journaux avancé dans la visionneuse de journaux, des suggestions d'entrée de journal spécifiques s'affichent. Ces suggestions proviennent à la fois de la langue de filtrage et de l'ensemble des entrées de journal chargées par la visionneuse de journaux. Pour valider une suggestion, appuyez sur TAB
. Si vous ne voyez pas de suggestions, essayez d'appuyer sur CTRL
+SPACE
. Les différentes parties d'une expression de filtre sont mises en surbrillance dans différentes couleurs. Si l'expression est rouge vif, le filtre que vous avez saisi est erroné ou incomplet.
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. Il s'agit alors de texte sans guillemets, illustré par 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 un filtre de journaux avancé dans la zone de filtre de recherche, vous pouvez appuyer sur ESC
pour quitter le mode d'édition, puis sur TAB
pour accéder aux autres options, telles que les menus déroulants de sélecteur de période, la flèche déroulante (▾) située à droite de la zone de recherche de filtre ou le bouton Submit Filter (Envoyer le filtre).
Syntaxe des filtres de journaux avancés
Cette section explique la structure des filtres de journaux avancés et le processus de mise en correspondance.
Syntaxe
La syntaxe des filtres de journaux avancés 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 propose un aperçu rapide de la syntaxe des filtres de journaux avancés. Certains détails n'y figurent pas, ils sont expliqués dans les sections suivantes.
Un filtre de journaux avancé est une chaîne qui contient une expression :
expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
Une comparaison est soit une valeur unique, soit une expression booléenne :
"The cat in the hat"
resource.type = "gae_app"
La première ligne est un exemple de comparaison qui est une valeur unique. Ces types de comparaisons sont des restrictions globales. Chaque champ d'une entrée de journal est comparé à la valeur à l'aide de l'opérateur has (contient). Pour cet exemple, si un champ de LogEntry, ou sa charge utile, contient la phrase "The cat in the hat", 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. Par exemple,
resource.type
.[OP] : est un opérateur de comparaison. Par exemple,
=
:[VALUE] : est un nombre, une chaîne, une fonction ou une expression entre parenthèses. Par exemple,
"gae_app"
.
Les sections suivantes donnent plus de détails sur les filtres 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 filtres de journaux avancés suivants sont équivalents :
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] : nom du chemin d'accès à un champ d'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"
Pour plus d'informations, consultez la section sur les identificateurs de chemin d'accès à un champ.
[OP] : est un opérateur de comparaison, soit l'un des suivants :
= # equal != # not equal > < >= <= # numeric ordering : # "has" matches any substring in the log entry field
[VALUE] : est un nombre, une chaîne, une fonction ou une 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 = ("siamese" OR "shorthair")
jsonPayload.animal : ("nice" AND "pet")
La première comparaison vérifie que le champ cat
(chat) a la valeur "siamese" (siamois) ou "shorthair" (à poils ras). 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 constitue (ou débute) la partie gauche de la comparaison, doit être un champ défini de 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 d'accès est
labels
, alors l'identificateur suivant,[KEY]
, doit être l'une des clés des paires valeur/clé apparaissant dans le champlabels
.logName : le champ
logName
étant une chaîne, vous ne pouvez pas le faire suivre de noms de sous-champs.
Pour plus d'informations sur l'utilisation des identificateurs de chemin d'accès qui référencent des objets ou des tableaux, consultez la section Types d'objets et de tableaux.
Types de ressources surveillées
Pour des recherches plus rapides, précisez un type de ressource surveillée. Pour une liste des types de ressources, consultez la page Types de ressources surveillées.
Par exemple, les machines virtuelles (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 les recherches à 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 un filtre et que ce champ n'apparaît pas dans une entrée de journal, le champ est manquant, non défini ou défini par défaut :
Si le champ fait partie de la charge utile de l'entrée de journal (
jsonPayload
ouprotoPayload
) ou s'il figure dans une étiquette de la sectionlabels
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 du filtre.
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:*
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 chaînestring
est également considérée comme un scalaire. Les champs pouvant être convertis en (ou à partir de) chaîne, tels queDuration
etTimestamp
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
contenait la valeur précédente,jsonPayload.x.age
aurait alors la valeur24
.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 à la valeur[VALUE]
et les résultats sont joints à l'aide de l'opérateurOR
. Par exemple, sijsonPayload.shoeSize
est un champ de tableau qui contient{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 une liste des types scalaires, voir la liste des 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 filtre 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. |
Timestamp |
Une chaîne au format RFC 3339. Exemple : "2014-10-02T15:01:23.045Z". Dans les expressions de filtre, les horodatages 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 d'entiers de différentes tailles, tels que int32
et uint64
. Lorsque vous écrivez une valeur à convertir en un type d'entier 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"
deprotoPayload
. Consultez la section Mappage JSON pour plus d'informations.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 qui ont pour valeurs
true
oufalse
sont de typebool
. - 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 champs dont les valeurs sont des nombres sans guillemets sont de type
Les types
Duration
etTimestamp
ne sont reconnus que par 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 partrue
>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 délais,"1s"
>"999ms"
.Timestamp
: l'égalité signifie le même instant temporel. Si a et b sont des valeursTimestamp
, 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.
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 si sa charge utile, contient la restriction globale.
Si c'est le cas, la comparaison réussit.
Le filtre de journaux avancé le plus simple écrit 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 un filtre plus intéressant. Par exemple, si vous souhaitez afficher toutes les entrées de journal comportant un champ contenant cat
et un champ contenant soit hat
soit bat
, écrivez le filtre 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 la recherche d'une valeur particulière dans un journal.
Par exemple, si vous recherchez dans un journal d'activité des entrées contenant n'importe quelle mention de GCE_OPERATION_DONE
, utilisez le filtre suivant :
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. Consultez la section Trouver des entrées de journal rapidement.
Fonctions
Vous pouvez utiliser les fonctions intégrées comme restrictions globales dans les filtres avancés :
function = identifier ( [ argument { , argument } ] )
où argument
est une valeur, un nom de champ ou une expression entre parenthèses.
Les fonctions sont décrites dans les sections suivantes.
sample
La fonction sample
sélectionne une partie du nombre total d'entrées de journal :
sample([FIELD], [FRACTION])
[FIELD]
est le nom d'un champ de 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 : Le filtre suivant renvoie 25 % des entrées 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 ou des sectionslabels
de l'entrée de journal, l'entrée de journal n'est pas sélectionnée pour l'échantillon, même si[FRACTION]
égale 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 plus d'informations sur les champs non renseignés et ceux définis par défaut, consultez la section Champs non renseignés.
Pour exclure de l'échantillon les entrées de journal dotées de champs par défaut, utilisez l'opérateur "le champ existe", :*
. Le filtre suivant 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 : Le filtre suivant teste une adresse IP dans la charge utile des entrées 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 plus d'informations sur les champs non renseignés et ceux définis par défaut, consultez la section Champs non renseignés.
Des exemples d'adresses et de plages d'adresses IP prises en charge sont répertoriés ci-dessous :
- 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 des filtres de journaux avancés, vous pouvez définir des limites spécifiques de date et d'heure pour les entrées de journal à afficher. Par exemple, si vous ajoutez les conditions suivantes à votre filtre, 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 un filtre 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 recherche de filtre.
Trouver des entrées de journal rapidement
Lorsque vous filtrez ou interrogez des entrées de journal :
- Utilisez des champs indexés.
- Réduisez le nombre d'entrées de journal à rechercher.
Utiliser les champs indexés
Spécifiez les valeurs exactes des champs indexés. N'utilisez pas de correspondances de sous-chaîne. Les champs d'entrée de journal suivants sont indexés :
- logName
- resource.type
- Les libellés de ressources indexées parmi les resource.labels
- timestamp
Index de champs temporaires
Trois champs d'entrées de journal supplémentaires sont partiellement indexés pendant une durée limitée après réception des entrées par Stackdriver Logging. Pour résoudre rapidement les problèmes rencontrés dans le système, une recherche sur les champs suivants peut être utile. Stackdriver Logging peut modifier la façon dont il indexe ces trois champs à l'avenir, sans préavis :
severity : les degrés de gravité allant d'INFORMATION (100) à URGENCE (900) sont indexés. Pour tirer parti de l'index, veillez à ne rechercher que les valeurs comprises dans la plage indexée.
httpRequest.status : les valeurs d'état de 201 à 511 sont indexées. Pour tirer parti de l'index, veillez à ne rechercher que les valeurs comprises dans la plage indexée.
operation.id : toutes les valeurs de ces champs sont indexées. Pour tirer parti de l'index, recherchez ce champ à l'aide de l'opérateur d'égalité. n'utilisez pas de recherches de sous-chaînes.
Si vous recherchez régulièrement ces champs dans les entrées de journal récentes, pensez à limiter la période de recherche à l'aide du champ timestamp.
Réduire les journaux, les entrées de journal et les délais
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é, on remarque que 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
est 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 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. Un moyen rapide de déterminer les horodatages utiles au format RFC 3339 est d'utiliser la commande date
de Gnu/Linux :
$ 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 filtres suivants. Pour créer un horodatage compatible avec Stackdriver 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"
Consultez la section Index de champs temporaires pour un autre exemple d'utilisation des horodatages.
Minimiser les recherches globales et de sous-chaînes
Évitez de céder à la facilité lorsque vous saisissez des filtres 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 s'appellent 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 au filtre de journaux avancé de la zone de filtre 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 filtres :
resource.type=gae_app
Affiche les mêmes entrées de journal que l'interface de filtrage 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 liste des 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 en fonction 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 champlogName
doit contenirrequest_log
, dans n'importe quelle 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 utiliserOR
, maisAND
est implicite si vous omettez l'opérateur.
- 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 être paramétrées sur une gravité (
severity
) de niveauERROR
au minimum, ce qui équivaut à sélectionner ERROR dans le menu de gravité de l'interface de filtrage de base. Vous ne pouvez pas afficher les journaux de plusieurs types de ressources dans l'interface de filtrage 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 du journal,cloudaudit.googleapis.com/activity
, doit être saisi sous forme d'URL dans le nom du journal. L'utilisation de l'égalité dans la comparaison accélère la recherche. Pour plus d'informations, consultez la section Récupérer des 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 etphoenix
dans un autre.textPayload:(unicorn phoenix)
Affiche les entrées de journal dont le champ
textPayload
contient à la foisunicorn
etphoenix
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 la chaîne"unicorn phoenix"
, comme dans l'interface de filtrage de base.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 taper un filtre avancé dans la zone de filtre de recherche et que vous devez accéder aux autres menus de la page, appuyez sur ESC
pour quitter le mode d'édition, puis sur TAB
pour accéder aux autres options.
Problèmes de syntaxe
Si vous rencontrez des problèmes avec les expressions des filtres avancés, vérifiez les points suivants :
Votre filtre respecte les règles de syntaxe. Les parenthèses et les guillemets vont par paires.
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 filtres ci-dessous se ressemblent, mais ne sont pas équivalents :
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 erronée, en raison de l'opérateur de sous-chaîne intégré (
:
). La comparaison doit être saisie entre guillemets :insertId = abc:def # ILLEGAL! insertId = "abc:def"
gcloud logging exige que le filtre 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é du filtre avec des guillemets simples à la place :gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
Les expressions de recherche dans les filtres de base de la visionneuse de journaux sont différentes des expressions de recherche dans les filtres de journaux avancés. Pour en savoir plus, consultez la section Différences entre les filtres de base et les filtres avancés.
Si vous rédigez un filtre qui inclut un horodatage, vous devez sélectionner l'option Aucune limite dans le sélecteur de période situé sous la zone de recherche de filtre.