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

Syntaxe de requête CloudWatch Logs Insights

Avec CloudWatch Logs Insights, vous utilisez un langage de requête pour interroger vos groupes de journaux. La syntaxe de la requête prend en charge différentes fonctions et opérations, y compris, mais sans se limiter aux fonctions générales, les opérations arithmétiques et de comparaison et les expressions régulières. Créez des requêtes contenant plusieurs commandes. Séparez les commandes avec le caractère barre verticale (|). Créez des requêtes contenant des commentaires. Affichez les commentaires avec le caractère dièse (#).

Note

CloudWatch Logs Insights découvre automatiquement des champs pour différents types de journaux et génère des champs commençant par le caractère @. Pour plus d'informations sur ces champs, consultez Journaux pris en charge et champs découverts dans le Guide de l'utilisateur Amazon CloudWatch.

Commandes de requête CloudWatch Logs Insights

Cette section contient une liste de commandes de requête prises en charge pour CloudWatch Logs Insights.

Note

Les exemples de requêtes de cette section ne fonctionneront pas pour tous les types de journaux. Pour obtenir des exemples de requêtes générales et de requêtes pour d'autres types de journaux, consultez Exemples de requêtes.

display

Utilisez la commande display pour afficher un ou plusieurs champs spécifiques dans les résultats de la requête.

Exemple : Afficher un champ

L'exemple de requête extrait les données du champ @message et crée les champs éphémères loggingType et loggingMessage. La requête renvoie les événements du journal dans lesquels les valeurs pour loggingType sont ERROR (ERREUR) et affiche uniquement les valeurs pour loggingMessage dans les résultats de la requête.

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

Exemple : Afficher plusieurs champs

Vous pouvez spécifier plusieurs champs dans la commande display. L'exemple de requête montre les valeurs pour loggingType et loggingMessage dans les résultats de la requête.

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

En tant que bonne pratique, utilisez la commande display une seule fois dans une requête. Si vous utilisez la commande display plusieurs fois dans une requête, les résultats de la requête affichent le champ spécifié dans la dernière occurrence de l'utilisation de la commande display.

fields

Utilisez la commande fields pour afficher des champs spécifiques dans les résultats de la requête.

Exemple : Afficher des champs spécifiques

La requête suivante renvoie 20 événements du journal et les affiche par ordre décroissant. Les valeurs pour @timestamp et @message sont affichés dans les résultats de la requête.

fields @timestamp, @message | sort @timestamp desc | limit 20
Astuce

Utilisez cette commande lorsque vous ne voulez pas utiliser la commande display. La commande fields prend en charge différentes fonctions et opérations pour modifier les valeurs des champs et créer de nouveaux champs qui peuvent être utilisés dans des requêtes.

filter

Utilisez la commande filter pour obtenir des événements du journal qui répondent à une ou plusieurs conditions.

Exemple : Filtrage des événements du journal à l'aide d'une condition

La requête suivante renvoie les événements du journal où la valeur de range est supérieure à 3 000. La requête limite les résultats à 20 événements du journal et trie les événements du journal par @timestamp et par ordre décroissant.

fields @timestamp, @message | filter (range>3000) | sort @timestamp desc | limit 20

Exemple : Filtrage des événements du journal à l'aide de plusieurs conditions

Vous pouvez utiliser les mots-clés and et or pour combiner plusieurs conditions.

La requête suivante renvoie les événements du journal où la valeur de range est supérieure à 3 000 et la valeur pour accountId est égale à 798 312 420 998. Comme la requête précédente, la requête limite les résultats à 20 événements du journal et trie les événements du journal par @timestamp et par ordre décroissant.

fields @timestamp, @message | filter (range>3000 and accountId=9876543210) | sort @timestamp desc | limit 20

stats

Utilisez la commande stats pour calculer des statistiques agrégées avec des valeurs des champs du journal.

sort

Utilisez la commande sort pour afficher les événements du journal dans l'ordre croissant (asc) ou décroissant (desc).

limit

Utilisez la commande limit pour spécifier le nombre d'événements de journal que vous voulez que votre requête retourne.

parse

Utilisez la commande parse pour extraire des données d'un champ de journal et créer un champ éphémère que vous pouvez traiter dans votre requête.

Directives d'utilisation des commandes de requête

Vous devez placer les champs des journaux nommés dans les requêtes qui incluent des caractères autres que le symbole @, le point (.) et des caractères non-alphanumériques entre guillemets inversés (`). Par exemple, le champ de journal foo-bar doit être placé entre accents graves (`foo-bar`), car il contient un caractère non alphanumérique, le trait d'union (-).

Utilisez la commande display pour afficher le ou les champs que vous souhaitez voir dans les résultats de la requête. La commande display affiche uniquement les champs que vous spécifiez. Si la requête contient plusieurs commandes display, les résultats de la requête affichent uniquement le ou les champs que vous avez spécifiés dans la commande display finale.

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

La valeur de isRes équivaut à 0 ou 1, selon que resolverArn est un champ découvert. Si les requêtes contiennent plusieurs commandes fields et n'incluent pas une commande display, vous afficherez tous les champs spécifiés dans les commandes fields.

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

La commande de filtre prend en charge l'utilisation d'expressions régulières. Vous pouvez utiliser les opérateurs de comparaison suivants (=, !=, <, <=, >, >=) et les opérateurs booléens (and, or et not).

Note

Nous supposons 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, consultez le site web Hyperscan.

Vous pouvez utiliser le mot-clé in pour tester des membres d'un ensemble et vérifier les éléments d'une matrice. Pour vérifier les éléments dans une matrice, insérez la matrice après in. Vous pouvez utiliser l'opérateur booléen not avec in. Vous pouvez créer des requêtes utilisant in pour renvoyer les événements du journal où les champs sont des correspondances de chaînes. Les champs doivent être des chaînes complètes. Par exemple, l'extrait de code suivant montre une requête qui utilise in pour renvoyer les événements du journal où le champ logGroup est le example_group de chaîne complète.

fields @timestamp, @message | filter logGroup in ["example_group"]

Vous pouvez utiliser les phrases avec des mots-clés like et not like pour faire correspondre des sous-chaînes. Vous pouvez utiliser l'opérateur d'expression régulière =~ pour faire correspondre des sous-chaînes. Pour faire correspondre une sous-chaîne avec like et not like, placez la sous-chaîne à faire correspondre entre guillemets simples ou doubles. Vous pouvez utiliser des modèles d'expression régulière avec like et not like. Pour faire correspondre une sous-chaîne avec l'opérateur d'expression régulière, placez la sous-chaîne que vous souhaitez faire correspondre entre des barres obliques. Les exemples suivants contiennent des extraits de code qui montrent comment faire correspondre des sous-chaînes à l'aide de la commande filter.

Exemples : faire correspondre des sous-chaînes

Les exemples suivants renvoient des événements du journal où f1 contient le mot Exception. Les trois exemples sont sensibles à la casse.

Le premier exemple fait correspondre une sous-chaîne avec like.

fields f1, f2, f3 | filter f1 like "Exception"

Le deuxième exemple fait correspondre une sous-chaîne avec like et un modèle d'expression régulière.

fields f1, f2, f3 | filter f1 like /Exception/

Le dernier exemple fait correspondre une sous-chaîne avec une expression régulière.

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

Exemple : faire correspondre des sous-chaînes avec des caractères de remplacement

Vous pouvez utiliser le symbole astérisque (*) comme caractère de remplacement dans les expressions régulières pour faire correspondre des sous-chaînes. L'exemple suivant renvoie des événements du journal où f1 contient des mots qui commencent par la lettreE. L'exemple est sensible à la casse.

fields f1, f2, f3 | filter f3 like /E*/
Note

Vous pouvez placer un point avant le symbole astérisque (.*) pour créer un quantificateur gourmand qui renvoie autant de correspondances que possible.

Exemple : exclure des sous-chaines des correspondances

L'exemple suivant montre une requête qui renvoie des événements du journal où f1 ne contient pas le mot Exception. L'exemple est sensible à la casse.

fields f1, f2, f3 | filter f1 not like "Exception"

Exemple : faire correspondre des sous-chaînes avec des modèles insensibles à la casse

Vous pouvez faire correspondre des sous-chaînes insensibles à la casse avec like et des expressions régulières. Placez le paramètre suivant (?i) avant la sous-chaîne à faire correspondre. L'exemple suivant montre une requête qui renvoie des événements du journal où f1 contient pas le mot Exception ou exception.

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

Utilisation d'alias dans les requêtes

Créez des requêtes contenant des alias. Utilisez des alias pour renommer des champs de journal ou lors de l'extraction des valeurs dans des champs éphémères. Utilisez le mot-clé as pour attribuer un champ de journal ou obtenir un alias. Vous pouvez utiliser plusieurs alias dans une requête. Vous pouvez utiliser des alias dans les commandes suivantes :

  • fields

  • parse

  • sort

  • stats

Les exemples suivants montrent comment créer des requêtes contenant des alias.

Example (Exemple)

La requête contient un alias dans la commande fields.

fields @timestamp, @message, accountId as ID | sort @timestamp desc | limit 20

La requête renvoie les valeurs des champs @timestamp, @message et accountId. Les résultats sont triés dans l'ordre décroissant et limités à 20. Les valeurs pour accountId sont répertoriés sous l'alias ID.

Example (Exemple)

La requête contient des alias dans les commandes sort et stats.

stats count(*) by duration as time | sort time desc

La requête compte le nombre de fois que le champ duration apparaît dans le groupe de journaux et trie les résultats dans l'ordre décroissant. Les valeurs pour duration sont répertoriés sous l'alias time.

Utilisation de commentaires dans les requêtes

CloudWatch Logs Insights prend en charge les commentaires dans les requêtes. Utilisez le caractère dièse (#) pour afficher les commentaires. Vous pouvez utiliser des commentaires pour ignorer les lignes des requêtes ou des requêtes de documents.

Exemple : requête

Lorsque la requête suivante est exécutée, la deuxième ligne est ignorée.

fields @timestamp, @message, accountId # | filter accountId not like "7983124201998" | sort @timestamp desc | limit 20

Opérations et fonctions prises en charge

CloudWatch Logs Insights prend en charge les opérations et fonctions suivantes.

Opérateurs arithmétiques

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

Opération Description

a + b

Addition

a - b

Soustraction

a * b

Multiplication

a / b

Division

a ^ b

Élévation à la puissance (2 ^ 3 renvoie 8)

a % b

Valeurs restantes ou module (10 % 3 renvoie 1)

Opérateurs booléens

Utilisez les opérateurs booléens and, or et not.

Note

Utilisez les opérateurs booléens uniquement dans les fonctions qui renvoient une valeur de TRUE (VRAI) ou FALSE (FAUX).

Opérateurs de comparaison

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

Opérateur Description

=

Égal à

!=

Non égal à

<

Inférieur à

>

Supérieure à

<=

Inférieur ou égal à

>=

Supérieur ou égal à

Opérations numériques

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. Utilisez des opérations numériques dans les commandes filter et fields et en tant qu'arguments pour d'autres fonctions.

Opération Type de résultat Description

abs(a: number)

nombre

Valeur absolue

ceil(a: number)

nombre

Arrondir 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 grand 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 Datetime

Utilisez les fonctions de date et heure dans les commandes fields et filter et en tant qu'arguments pour d'autres fonctions. Utilisez ces fonctions pour créer des compartiments de temps pour les requêtes avec des fonctions de regroupement. Utilisez des périodes qui se composent d'un numéro et de m pour les minutes ou h pour les heures. Par exemple, 10m correspond à 10 minutes et 1h correspond à une heure. Le tableau suivant contient une liste des différentes fonctions de date et heure que vous pouvez utiliser dans des commandes de requête. Le tableau répertorie le type de résultat de chaque fonction et contient une description de chaque fonction.

Astuce

Lorsque vous créez une commande de requête, vous pouvez utiliser le sélecteur d'intervalle pour sélectionner une période de temps à interroger. Par exemple, vous pouvez définir une période de temps entre des intervalles de 5 à 30 minutes, des intervalles de 1, 3 et 12 heures ou une période personnalisée. Vous pouvez également définir des périodes entre des dates spécifiques.

Fonction Type de résultat Description

bin(period: Period)

Horodatage

Arrondit la valeur de @timestamp à la période donnée, puis la tronque. Par exemple, bin(5m) arrondit la valeur de @timestamp à 5 minutes avant qu'elle ne se 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. Par exemple, toMillis(@timestamp) convertit l'horodatage 2022-01-14T13:18:031.000-08:00 à 1642195111000.

Note

Actuellement, CloudWatch Logs Insights ne prend pas en charge le filtrage des journaux avec des horodatages lisibles par l'humain.

Fonctions générales

Utilisez des fonctions générales dans les commandes fields et filter 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 d'adresse IP

Utilisez 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)

boolean

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

isValidIpV4(fieldName: string)

boolean

Renvoie true si le champ est une adresse IPv4 valide.

isValidIpV6(fieldName: string)

boolean

Renvoie true si le champ est une adresse IPv6 valide.

isIpInSubnet(fieldName: string, subnet: string)

boolean

Renvoie true si le champ est une adresse IPv4 ou IPv6 valide au sein du 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)

boolean

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)

boolean

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

Utilisez 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 journal dans le champ interrogé.

min(fieldName: LogField)

LogFieldValue

Valeur minimale des valeurs pour ce journal dans le champ interrogé.

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

Déviation standard 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

Utilisez 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 récent 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 ancien 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.

Fonctions de chaîne

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

Fonction Type de résultat Description

isempty(fieldName: string)

Nombre

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

isblank(fieldName: string)

Nombre

Renvoie 1 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 comporte la longueur de la sous-chaîne à récupérer. Par exemple, substr("xyZfooxyZ",3, 3) renvoie "foo".

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

chaîne

Remplace toutes les instances de searchValue dans fieldName: string par replaceValue.

Par exemple, la fonction replace(logGroup,"smoke_test","Smoke") recherche les événements du journal où le champ logGroup contient la valeur de chaîne smoke_test et remplace la valeur par la chaîne Smoke.

strcontains(str: string, searchValue: string)

nombre

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