Syntaxe de requête CloudWatch Logs Insights - Amazon CloudWatch Logs

Syntaxe de requête CloudWatch Logs Insights

CloudWatch Logs Insights prend en charge un langage de requête que vous pouvez utiliser pour interroger vos groupes de journaux. Vous pouvez inclure une ou plusieurs commandes de requête séparées par des barres verticales de type Unix (|) dans vos requêtes.

CloudWatch Logs Insights prend en charge différentes fonctions et opérations, y compris, mais sans se limiter aux fonctions générales, aux opérations arithmétiques et de comparaison et aux expressions régulières. Pour plus d’informations, consultez la section Opérations et fonctions prises en charge.

Note

CloudWatch Logs Insights part du principe que vous maîtrisez les expressions régulières. CloudWatch Logs Insights prend en charge Hyperscan, une bibliothèque de correspondance d'expressions régulières multiples. Pour plus d'informations sur Hyperscan et sur la syntaxe qu'il suit, consultez le site web Hyperscan.

CloudWatch Logs Insights prend également en charge les commentaires et ignore les lignes d'une requête qui commencent par le signe de hachage (#).

CloudWatch Logs Insights génère automatiquement des champs qui commencent par le symbole @. Pour plus d’informations sur les champs que CloudWatch Logs génère automatiquement, consultez la section Journaux et champs découverts pris en charge du Guide de l'utilisateur Amazon CloudWatch..

Commandes de requête CloudWatch Logs Insights

Le tableau suivant répertorie les commandes de requête prises en charge et inclut des exemples basiques. Pour obtenir des exemples de requêtes générales et de requêtes pour d'autres types de journaux, consultez la section Exemples de requêtes du Guide de l'utilisateur Amazon CloudWatch Logs.

Commande Description Exemple(s)

display

Spécifie les champs à afficher dans les résultats de la requête. Si vous spécifiez cette commande plusieurs fois dans votre requête, seuls les champs spécifiés dans la dernière occurrence sont utilisés.

L'exemple suivant utilise le champ @message et crée les champs éphémères loggingType et loggingMessage à utiliser dans la requête. Il filtre les événements qui contiennent ERROR comme valeur pour loggingType, puis n'affiche que le champ loggingMessage de ces événements dans les résultats.

fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage

fields

Extrait les champs spécifiés des événements du journal pour les afficher.

Vous pouvez utiliser les fonctions et les opérations d'une commande fields pour modifier les valeurs de champ à afficher et pour créer de nouveaux champs à utiliser dans le reste de la requête.

L'exemple suivant affiche les champs foo-bar, action et la valeur absolue de la différence entre f3 et f4 pour tous les événements du journal du groupe de journaux.

fields `foo-bar`, action, abs(f3-f4)

L'exemple suivant crée et affiche un champ éphémère opStatus. La valeur de opStatus pour chaque entrée du journal est la concaténation des valeurs des champs Operation et StatusCode, avec un trait d'union entre ces valeurs.

fields concat(Operation, '-', StatusCode) as opStatus

filter

Filtre les résultats d'une requête en fonction d'une ou de plusieurs conditions. Vous pouvez utiliser une variété d'opérateurs et d'expressions dans la commande filter. Pour plus d'informations, consultez Correspondances et expressions régulières dans la commande filter.

L'exemple suivant extrait les champs f1, f2 et f3 pour tous les événements du journal dont la valeur du champ duration est supérieure à 2000.

fields f1, f2, f3 | filter (duration>2000)

L'exemple suivant est également une requête valide, mais les résultats n'affichent pas des champs distincts. Au lieu de cela, les résultats affichent @timestamp et toutes les données de journaux dans le champ @message pour tous les événements du journal dont la durée est supérieure à 2000.

filter (duration>2000)

L'exemple suivant extrait les champs f1 et f2 pour tous les événements du journal où f1 a pour valeur 10 ou f3 est supérieur à 25.

fields f1, f2 | filter (f1=10 or f3>25)

L'exemple suivant renvoie les événements du journal où le champ statusCode a une valeur comprise entre 200 et 299.

fields f1 | filter statusCode like /2\d\d/

L'exemple suivant renvoie les événements du journal qui ont un statusCode de « 300 », « 400 » ou « 500 ».

fields @timestamp, @message | filter statusCode in [300,400,500]

Cet exemple final renvoie les événements du journal qui n'ont pas de champs Type avec les valeurs « foo », « bar » ou « 1 ».

fields @timestamp, @message | filter Type not in ["foo","bar",1]

stats

Calcule des statistiques d’agrégation basées sur les valeurs des champs du journal. Lorsque vous employez stats, vous pouvez également utiliser by pour spécifier un ou plusieurs critères à utiliser pour regrouper les données lors du calcul des statistiques.

Plusieurs opérateurs statistiques sont pris en charge, notamment sum(), avg(), count(), min() et max().

L'exemple suivant calcule la valeur moyenne de f1 pour chaque valeur unique de f2.

stats avg (f1) by f2

sort

Trie les événements du journal récupérés. L'ordre croissant (asc) et décroissant (desc) sont pris en charge.

L'exemple suivant trie les événements retournés par ordre décroissant en fonction de la valeur de f1, et affiche les champs f1, f2 et f3.

fields f1, f2, f3 | sort f1 desc

limit

Spécifie le nombre d'événements du journal renvoyés par la requête.

Vous pouvez l'utiliser pour limiter les résultats à un petit nombre afin de consulter un ensemble limité de résultats pertinents. Vous pouvez également utiliser limit avec un nombre compris entre 1 000 et 10 000 pour augmenter le nombre de lignes de résultats de la requête affichées dans la console à une quantité supérieure à la valeur par défaut de 1 000 lignes.

Si vous ne spécifiez pas de limite, la requête affiche par défaut un maximum de 1 000 lignes.

L'exemple suivant trie les événements par ordre décroissant en fonction de la valeur de @timestamp, et affiche les champs f1 et f2 pour les 25 premiers événements par ordre de tri. Dans ce cas, l'ordre de tri dépend de l'horodatage en commençant par le plus récent, donc les 25 événements les plus récents sont renvoyés.

sort @timestamp desc | limit 25 | display f1, f2

parse

Extrait les données d'un champ de journal et crée un ou plusieurs champs éphémères que vous pouvez traiter ultérieurement dans la requête. parse accepte à la fois les expressions glob et les expressions ordinaires.

Pour analyser les expressions glob, fournissez à la commande parse une chaîne de constantes (caractères entourés de guillemets simples ou doubles) où chaque élément variable du texte est remplacé par un astérisque (*). Ces données sont extraites dans des champs éphémères et se voient attribuer un alias après le mot clé as, dans l'ordre de position.

Placez des expressions régulières entre barres obliques (/). Dans l'expression, chaque partie de la chaîne correspondante qui doit être extraite est incluse dans un groupe de capture nommé. Voici un exemple d'un groupe de capture nommé (?<name>.*), où name est le nom et .* le modèle.

En utilisant cette seule ligne de journal à titre d'exemple :

25 May 2019 10:24:39,474 [ERROR] {foo=2, bar=data} The error was: DataIntegrityException

Les deux expressions parse suivantes exécutent chacune les opérations suivantes : les champs éphémères level, config et exception sont créés. level a la valeur ERROR, config a la valeur {foo=2, bar=data} et exception a la valeur DataIntegrityException. Le premier exemple utilise une expression glob et la seconde une expression ordinaire.

parse @message "[*] * The error was: *" as level, config, exception
parse @message /\[(?<level>\S+)\]\s+(?<config>\{.*\})\s+The error was: (?<exception>\S+)/

L'exemple suivant utilise une expression régulière pour extraire les champs éphémères user2, method2 et latency2 à partir du champ du journal @message et renvoie la latence moyenne pour chaque combinaison unique de method2 et user2.

parse @message /user=(?<user2>.*?), method:(?<method2>.*?), latency := (?<latency2>.*?)/ | stats avg(latency2) by method2, user2

Directives d'utilisation des commandes de requête

  • Vous devez mettre tout champ du journal nommé dans une requête et qui inclut des caractères autres que le symbole @, le point (.) et des caractères alphanumériques entre guillemets inversés `. Par exemple, le champ foo-bar doit être mis entre guillemets inversés (`foo-bar`), car il contient un caractère non alphanumérique, le trait d'union (-).

  • Utilisez display et fields pour afficher les champs que vous souhaitez afficher dans les résultats de votre requête.

    display spécifie uniquement les champs que vous souhaitez afficher dans les résultats de votre requête. Si vous avez plusieurs commandes display, vous n’afficherez que les champs spécifiés dans la dernière commande display.

    Vous pouvez utiliser fields dans une requête avec le mot clé as pour créer de des champs éphémères qui utilisent des champs et des fonctions dans l'événement du journal. Par exemple, fields ispresent as isRes crée un champ éphémère nommé isRes. Vous pouvez utiliser le champ éphémère dans le reste de votre requête.

    La valeur de isRes est 0 ou 1, selon que resolverArn est un champ découvert ou non dans l'événement du journal. Si vous avez plusieurs commandes fields et que vous n'incluez pas display, vous afficherez tous les champs spécifiés dans les commandes fields.

Correspondances et expressions régulières dans la commande filter

Vous pouvez utiliser des expressions régulières, des opérateurs de comparaison (=, !=, <, <=, >, >=) et des opérateurs booléens (and, or et not) dans la commande filter.

Vous pouvez utiliser in pour tester l'appartenance définie. Insérez un tableau avec les éléments que vous souhaitez vérifier immédiatement après in. Vous pouvez utiliser not avec in. Les correspondances de chaînes qui utilisent in doivent être des correspondances de chaînes complètes

Vous pouvez utiliser like ou =~ pour filtrer les sous-chaînes. Pour une correspondance de sous-chaîne, mettez la sous-chaîne à faire correspondre entre guillemets doubles ou simples. Pour effectuer une correspondance par expression régulière, encadrez l'expression à faire correspondre avec des barres obliques. La requête renvoie uniquement les événements du journal qui correspondent à vos critères.

Exemples

Les trois exemples suivants renvoient tous les événements où f1 contient le mot Exception. Le premier exemple utilise une correspondance de sous-chaîne. Les deux derniers exemples utilisent des expressions régulières. Les trois exemples sont sensibles à la casse.

fields f1, f2, f3 | filter f1 like "Exception"
fields f1, f2, f3 | filter f1 like /Exception/
fields f1, f2, f3 | filter f1 =~ /Exception/

L'exemple suivant modifie la recherche de « Exception » pour qu'elle ne soit pas sensible à la casse.

fields f1, f2, f3 | filter f1 like /(?i)Exception/

L'exemple suivant utilise une expression régulière. Il renvoie tous les événements où f1 correspond exactement au mot Exception. La requête n'est pas sensible à la casse.

fields f1, f2, f3 | filter f1 =~ /^(?i)Exception$/

Utilisation d'alias dans les requêtes

Vous pouvez utiliser as pour créer un ou plusieurs alias dans une requête. Les alias sont pris en charge dans les commandes fields, stats et sort.

Vous pouvez créer des alias pour les champs du journal et pour les résultats des opérations et des fonctions.

Exemples

Les exemples suivants illustrent l'utilisation d'alias dans les commandes de requête.

fields abs(myField) as AbsoluteValuemyField, myField2

Renvoie la valeur absolue de myField comme AbsoluteValuemyField et renvoie également le champ myField2.

stats avg(f1) as myAvgF1 | sort myAvgF1 desc

Calcule la moyenne des valeurs de f1 en tant que myAvgF1 et les renvoie par ordre décroissant selon cette valeur.

Utilisation de commentaires dans les requêtes

Vous pouvez commenter les lignes d’une requête en utilisant le caractère #. Les lignes qui commencent par le caractère# sont ignorées. Cela peut être utile pour documenter votre requête ou ignorer temporairement une partie d'une requête complexe pour un appel, sans supprimer cette ligne.

Dans l'exemple suivant, la deuxième ligne de la requête est ignorée.

fields @timestamp, @message # | filter @message like /delay/ | limit 20

Opérations et fonctions prises en charge

Le langage de requête prend en charge de nombreux types d'opérations et de fonctions, comme indiqué dans les tableaux suivants.

Opérations de comparaison

Vous pouvez utiliser des opérations de comparaison dans la commande filter et en tant qu'arguments pour d'autres fonctions. Les opérations de comparaison acceptent tous les types de données en tant qu'arguments et renvoient un résultat booléen.

= != < <= > >=

Opérateurs booléens

Vous pouvez utiliser les opérateurs booléens and, or et not. Vous pouvez utiliser ces opérateurs booléens uniquement dans les fonctions qui renvoient une valeur booléenne.

Opérations arithmétiques

Vous pouvez utiliser des opérations arithmétiques dans les commandes filter et fields, et en tant qu'arguments pour d'autres fonctions. Les opérations arithmétiques acceptent les types de données numériques en tant qu'arguments numériques et renvoient des résultats numériques.

Opération Description

a + b

Addition

a - b

Soustraction

a * b

Multiplication

a / b

Division

a ^ b

Élévation à une puissance. 2 ^ 3 renvoie 8

a % b

Valeurs restante ou module. 10 % 3 renvoie 1

Opérations numériques

Vous pouvez utiliser des opérations numériques dans les commandes filter et fields, et en tant qu'arguments pour d'autres fonctions. Les opérations numériques acceptent les types de données numériques en tant qu'arguments numériques et renvoient des résultats numériques.

Opération Type de résultat Description

abs(a: number)

nombre

Valeur absolue.

ceil(a: number)

nombre

Arrondissez jusqu'au nombre entier supérieur suivant (le plus petit nombre entier supérieur à la valeur de a).

floor(a: number)

nombre

Arrondir jusqu'au nombre entier inférieur suivant (le plus petit nombre entier inférieur à la valeur de a).

greatest(a: number, ...numbers: number[])

nombre

Renvoie la valeur la plus grande.

least(a: number, ...numbers: number[])

nombre

Renvoie la valeur la plus petite.

log(a: number)

nombre

Journal naturel.

sqrt(a: number)

nombre

Racine carrée.

Fonctions générales

Vous pouvez utiliser des fonctions générales dans les commandes filter et fields, et en tant qu'arguments pour d'autres fonctions.

Fonction Type de résultat Description

ispresent(fieldName: LogField)

booléen

Renvoie true si le champ existe.

coalesce(fieldName: LogField, ...fieldNames: LogField[])

LogField

Renvoie la première valeur non nulle de la liste.

Fonctions de chaîne

Vous pouvez utiliser des fonctions de chaîne dans les commandes filter et fields, et en tant qu'arguments pour d'autres fonctions.

Fonction Type de résultat Description

isempty(fieldName: string)

booléen

Renvoie true si le champ est manquant ou est une chaîne vide.

isblank(fieldName: string)

booléen

Renvoie true si le champ est manquant, est une chaîne vide ou contient uniquement un espace.

concat(str: string, ...strings: string[])

chaîne

Concatène les chaînes.

ltrim(str: string)

ltrim(str: string, trimChars: string)

chaîne

Si la fonction ne possède pas de deuxième argument, elle supprime les espaces blancs à gauche de la chaîne. Si la fonction possède un deuxième argument de chaîne, elle ne supprime pas l'espace blanc. Au lieu de cela, elle supprime les caractères de trimChars à gauche de str. Par exemple, ltrim("xyZxyfooxyZ","xyZ") renvoie "fooxyZ".

rtrim(str: string)

rtrim(str: string, trimChars: string)

chaîne

Si la fonction ne possède pas de deuxième argument, elle supprime les espaces blancs à droite de la chaîne. Si la fonction possède un deuxième argument de chaîne, elle ne supprime pas l'espace blanc. Au lieu de cela, elle supprime les caractères de trimChars à droite de str. Par exemple, rtrim("xyZfooxyxyZ","xyZ") renvoie "xyZfoo".

trim(str: string)

trim(str: string, trimChars: string)

chaîne

Si la fonction ne possède pas de deuxième argument, elle supprime les espaces blancs aux deux extrémités de la chaîne. Si la fonction possède un deuxième argument de chaîne, elle ne supprime pas l'espace blanc. Au lieu de cela, il supprime les caractères de trimChars des deux côtés de str. Par exemple, trim("xyZxyfooxyxyZ","xyZ") renvoie "foo".

strlen(str: string)

nombre

Renvoie la longueur de la chaîne en points de code Unicode.

toupper(str: string)

chaîne

Convertit la chaîne en majuscules.

tolower(str: string)

chaîne

Convertit la chaîne en minuscules.

substr(str: string, startIndex: number)

substr(str: string, startIndex: number, length: number)

chaîne

Renvoie une sous-chaîne à partir de l'index spécifié par l'argument de nombre à la fin de la chaîne. Si la fonction comporte un second argument de nombre, elle contient la longueur de la sous-chaîne à récupérer. Par exemple, substr("xyZfooxyZ",3, 3) renvoie "foo".

replace(str: string, searchValue: string, replaceValue: string)

chaîne

Remplace toutes les instances de searchValue dans str par replaceValue. Par exemple, replace("foo","o","0") renvoie "f00".

strcontains(str: string, searchValue: string)

nombre

Renvoie 1 si str contient searchValue et 0 dans le cas contraire.

Fonctions Datetime

Vous pouvez utiliser des fonctions datetime dans les commandes filter et fields, et en tant qu'arguments pour d'autres fonctions. Vous pouvez utiliser ces fonctions pour créer des compartiments de temps pour les requêtes avec des fonctions d’agrégation.

Dans le cadre des fonctions datetime, vous pouvez utiliser des périodes qui se composent d'un nombre puis de m pour les minutes ou de h pour les heures. Par exemple, 10m correspond à 10 minutes, et 1h correspond à 1 heure.

Fonction Type de résultat Description

bin(period: Period)

Horodatage

Arrondit la valeur de @timestamp pour la période donnée, puis la tronque. Par exemple, bin(5m) arrondit la valeur de @timestamp à 5 minutes avant qu'il ne la tronque.

datefloor(timestamp: Timestamp, period: Period)

Horodatage

Tronque l'horodatage pour la période donnée. Par exemple, datefloor(@timestamp, 1h) tronque toutes les valeurs de @timestamp vers la valeur la plus basse de l'heure.

dateceil(timestamp: Timestamp, period: Period)

Horodatage

Arrondit l'horodatage pour la période donnée, puis la tronque. Par exemple, dateceil(@timestamp, 1h) tronque toutes les valeurs de @timestamp vers la valeur la plus élevée de l'heure.

fromMillis(fieldName: number)

Horodatage

Interprète le champ en entrée comme le nombre de millisecondes depuis l'époque Unix et le convertit en horodatage.

toMillis(fieldName: Timestamp)

nombre

Convertit l'horodatage trouvé dans le champ nommé en un nombre représentant les millisecondes depuis l'époque Unix.

Fonctions d'adresse IP

Vous pouvez utiliser les fonctions de chaîne d'adresse IP dans les commandes filter et fields, et en tant qu'arguments pour d'autres fonctions.

Fonction Type de résultat Description

isValidIp(fieldName: string)

booléen

Renvoie true si le champ est une adresse IPv4 ou IPv6 valide.

isValidIpV4(fieldName: string)

booléen

Renvoie true si le champ est une adresse IPv4 valide.

isValidIpV6(fieldName: string)

booléen

Renvoie true si le champ est une adresse IPv6 valide.

isIpInSubnet(fieldName: string, subnet: string)

booléen

Renvoie true si le champ est une adresse IPv4 ou IPv6 valide dans le sous-réseau v4 ou v6 spécifié. Lorsque vous spécifiez le sous-réseau, utilisez la notation CIDR telle que 192.0.2.0/24 ou 2001:db8::/32.

isIpv4InSubnet(fieldName: string, subnet: string)

booléen

Renvoie true si le champ est une adresse IPv4 valide dans le sous-réseau v4 spécifié. Lorsque vous spécifiez le sous-réseau, utilisez la notation CIDR telle que 192.0.2.0/24.

isIpv6InSubnet(fieldName: string, subnet: string)

booléen

Renvoie true si le champ est une adresse IP IPv6 valide dans le sous-réseau v6 spécifié. Lorsque vous spécifiez le sous-réseau, utilisez la notation CIDR telle que 2001:db8::/32.

Fonctions statistiques d'agrégation

Vous pouvez utiliser des fonctions d'agrégation dans la commande stats et en tant qu'arguments pour d'autres fonctions.

Fonction Type de résultat Description

avg(fieldName: NumericLogField)

nombre

Moyenne des valeurs dans le champ spécifié.

count()

count(fieldName: LogField)

nombre

Compte les événements du journal. count()(ou count(*)) compte tous les événements renvoyés par la requête, tandis que count(fieldName) compte tous les enregistrements qui incluent le nom du champ spécifié.

count_distinct(fieldName: LogField)

nombre

Renvoie le nombre de valeurs uniques pour le champ. Si le champ a une cardinalité très élevée (contient de nombreuses valeurs uniques), la valeur renvoyée par count_distinct n'est qu'une approximation.

max(fieldName: LogField)

LogFieldValue

Valeur maximale des valeurs pour ce champ de journal dans les journaux interrogés.

min(fieldName: LogField)

LogFieldValue

Valeur minimale des valeurs pour ce champ de journal dans les journaux interrogés.

pct(fieldName: LogFieldValue, percent: number)

LogFieldValue

Un centile indique la position relative d'une valeur dans un ensemble de données. Par exemple, pct(@duration, 95) renvoie la valeur @duration à laquelle 95 % des valeurs de @duration sont inférieures à cette valeur et 5 % des valeurs lui sont supérieures.

stddev(fieldName: NumericLogField)

nombre

Écart type des valeurs dans le champ spécifié.

sum(fieldName: NumericLogField)

nombre

Somme des valeurs dans le champ spécifié.

Fonctions statiques de non-agrégation

Vous pouvez utiliser des fonctions de non-agrégation dans la commande stats et en tant qu'arguments d'autres fonctions.

Fonction Type de résultat Description

earliest(fieldName: LogField)

LogField

Renvoie la valeur de fieldName à partir de l'événement de journal qui a l'horodatage le plus ancien dans les journaux interrogés.

latest(fieldName: LogField)

LogField

Renvoie la valeur de fieldName à partir de l'événement de journal qui a l'horodatage le plus récent dans les journaux interrogés.

sortsFirst(fieldName: LogField)

LogField

Renvoie la valeur de fieldName triée la première dans les journaux interrogés.

sortsLast(fieldName: LogField)

LogField

Renvoie la valeur de fieldName triée la dernière dans les journaux interrogés.