Syntaxe de filtre et de modèle - Amazon CloudWatch Logs

Syntaxe de filtre et de modèle

Vous pouvez utiliser des filtres de métriques pour rechercher des termes, des expressions ou des valeurs dans vos événements du journal et les faire correspondre. Lorsqu'un filtre de métrique trouve l'un des termes, expressions ou valeurs dans vos événements du journal, vous pouvez augmenter la valeur de la métrique CloudWatch. Par exemple, vous pouvez créer un filtre de métrique pour rechercher et dénombrer l'apparition du mot ERROR dans vos événements du journal.

Vous pouvez également choisir d'attribuer des dimensions et une unité à la métrique. Par exemple, si votre métrique compte le mot ERROR dans vos événements du journal, vous pouvez également définir ErrorCode comme une dimension afin de voir non seulement le nombre total d'événements du journal qui incluent ERROR, mais aussi les données filtrées en fonction du code d'erreur signalé.

Note

Si vous spécifiez une unité, assurez-vous de spécifier l'unité correcte lorsque vous créez le filtre. La modification ultérieure de l'unité du filtre n'aura aucun effet.

Les filtres de métriques peuvent également extraire des valeurs numériques des évènements du journal, délimités par des espaces, comme la latence des demandes web. Dans ces exemples, vous pouvez augmenter la valeur de la métrique par la valeur numérique réelle extraite du journal.

Vous pouvez aussi utiliser des opérateurs conditionnels et des caractères génériques pour créer des correspondances parfaites. Avant de créer un filtre de métrique, vous pouvez tester vos modèles de recherche dans la console CloudWatch. Les sections suivantes expliquent plus en détail la syntaxe du filtre de métrique.

Établissement de correspondances de termes dans les événements du journal

Pour rechercher un terme dans les événements du journal, utilisez-le comme modèle de filtre de métrique. Vous pouvez spécifier plusieurs termes dans un modèle de filtre de métrique, mais ils doivent tous figurer dans un événement du journal à des fins de correspondance. Les filtres de métriques sont sensibles à la casse.

Les termes des filtres de métriques qui incluent des caractères non alphanumériques ou des traits de soulignement doivent être placés entre guillemets doubles ("").

Pour exclure un terme, faites-le précéder d'un signe moins (-).

Exemple 1 : correspondre à tout

Le modèle de filtre «   » correspond à tous les événements du journal.

Exemple 2 : terme unique

Le modèle de filtre « ERROR » correspond aux messages d'événements du journal qui contiennent ce terme, à l'image des exemples suivants :

  • [ERROR] A fatal exception has occurred

  • Exiting with ERRORCODE: -1

Exemple 3 : inclure et exclure un terme

Dans l'exemple précédent, si vous remplacez le modèle de filtre par « ERROR -Exiting », le message d'événement de journal « Exiting with ERRORCODE: -1 » est exclu.

Exemple 4 : plusieurs termes

Le modèle de filtre « ERROR Exception » correspond aux messages d'événements du journal qui contiennent les deux termes, à l'image des exemples suivants :

  • [ERROR] Caught IllegalArgumentException

  • [ERROR] Unhandled Exception

Le modèle de filtre « Failed to process the request » correspond aux messages d'événements du journal qui contiennent tous les termes, à l'image des exemples suivants :

  • [WARN] Failed to process the request

  • [ERROR] Unable to continue: Failed to process the request

Critère spécial OR

Vous pouvez faire correspondre des termes de filtres textuels à l'aide des critères spéciaux OR. Utilisez un point d'interrogation pour OR, par exemple ?term.

Observez les trois exemples ci-dessous d'événement de journal ERROR correspond aux exemples 1 et 2. ?ERROR ?WARN correspond aux exemples 1, 2 et 3, car tous incluent le mot ERROR ou le mot WARN. ERROR WARN correspond uniquement à l'exemple 1, car il est le seul contenant ces deux mots. ERROR - WARN correspond à l'exemple 2, car il correspond à une chaîne qui contient le terme ERROR, mais pas WARN.

  1. ERROR WARN message

  2. ERROR message

  3. WARN message

Vous pouvez faire correspondre des termes à l'aide des critères spéciaux OR dans des filtres délimités par des espaces. Avec des filtres délimités par des espaces, w1 signifie le premier mot de l'événement de journal, w2 signifie le deuxième mot, etc. Pour les exemples de modèles ci-dessous, [w1=ERROR, w2] correspond aux modèles 1 et 2, car ERROR est le premier mot, et [w1=ERROR || w1=WARN, w2] correspond aux modèles 1, 2 et 3. [w1!=ERROR&&w1!=WARN, w2] ne correspond à aucune des lignes, car elles contiennent toutes ERROR ou WARN.

  1. message ERROR WARN

  2. message ERROR

  3. message WARN

Vous pouvez faire correspondre des termes à l'aide des critères spéciaux OR dans des filtres JSON. Pour les exemples de modèles ci-dessous, {$.foo = bar} correspond au modèle 1, {$.foo = baz } correspond au modèle 2 et {$.foo = bar || $.foo = baz } correspond aux modèles 1 et 2.

  1. {"foo": "bar"}

  2. {"foo": "baz"}

Établissement de correspondances dans les événements du journal JSON

Vous pouvez extraire des valeurs d'événements du journal JSON. Pour extraire ces valeurs des événements du journal JSON, vous devez créer un filtre de métrique basé sur chaîne. Les chaînes contenant une notation scientifique ne sont pas prises en charge. Les éléments dans les données d'événements du journal JSON doivent correspondre exactement au filtre métrique. Vous pouvez créer des filtres de métriques dans des événements du journal JSON pour indiquer ce qui suit :

  • Un certain événement se produit. Par exemple, eventName est « UpdateTrail »).

  • L'adresse IP se trouve à l'extérieur d'un sous-réseau connu. Par exemple, sourceIPAddress ne se trouve pas dans une plage de sous-réseaux connus.

  • Une combinaison de deux ou plusieurs autres conditions est remplie. Par exemple, eventName est « UpdateTrail » et recipientAccountId est 123456789012.

Utilisation de filtres de métriques pour extraire des valeurs à partir d'événements du journal JSON

Vous pouvez utiliser des filtres de métriques pour extraire des valeurs d'événements du journal JSON. Un filtre de métrique vérifie les journaux entrants et modifie une valeur numérique lorsque le filtre trouve une correspondance dans les données du journal. Lorsque vous créez un filtre de métrique, vous pouvez simplement augmenter un nombre chaque fois que le texte correspondant est trouvé dans un journal. Vous pouvez également extraire des valeurs numériques du journal et les utiliser pour augmenter la valeur de la métrique.

Correspondance des termes JSON à l'aide des filtres de métrique

La syntaxe de filtre de métrique pour les événements du journal JSON utilise le format suivant :

{ SELECTOR EQUALITY_OPERATOR STRING }

Le filtre de métrique doit être mis entre accolades { }, pour indiquer qu'il s'agit d'une expression JSON. Le filtre de métrique contient les éléments suivants :

SELECTOR

Spécifie la propriété JSON à vérifier. Les sélecteurs de propriétés commencent toujours par le symbole dollar ($), qui indique la racine de JSON. Les sélecteurs de propriétés sont des chaînes alphanumériques qui prennent également en charge les caractères « - » et « _ ». Les éléments du tableau sont indiqués par la syntaxe [NUMBER] et doivent suivre une propriété. Exemples : $.eventId, $.users[0], $.users[0].id, $.requestParameters.instanceId.

EQUALITY_OPERATOR

Peut être = ou !=

CHAÎNE

Une chaîne avec ou sans guillemets. Vous pouvez utiliser le caractère générique astérisque « * » pour n'importe quel texte avant ou après un terme de recherche, ou au niveau de ce terme. Par exemple, *Event correspond à PutEvent et GetEvent. Event* correspond à EventId et EventName. Ev*ent correspond uniquement à la chaîne réelle Ev*ent. Les chaînes composées intégralement de caractères alphanumériques n'ont pas besoin de guillemets. Les chaînes ayant des caractères Unicode et autres comme @, $, \, etc. doivent être mises entre guillemets pour être valides.

Exemples de filtres de métrique JSON

Voici un exemple de JSON :

{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ { "name": "a", "id": 1 }, { "name": "b", "id": 2 } ], "SomeObject": null, "ThisFlag": true }

Les filtres suivants correspondent :

{ $.eventType = "UpdateTrail" }

Filtre de type d'événement égal à UpdateTrail.

{ $.sourceIPAddress != 123.123.* }

Filtre d'adresse IP en dehors du préfixe de sous-réseau 123.123.

{ $.arrayKey[0] = "value" }

Filtre de première entrée d'arrayKey égale à « value ». Si arrayKey n’est pas un tableau, ce sera faux.

{ $.objectList[1].id = 2 }

Filtre de la deuxième entrée d'objectList avec une propriété appelée id = 2. Si objectList n’est pas un tableau, ce sera faux. Si les éléments d'objectList ne sont pas des objets ou qu’ils ne comportent aucune propriété id, ce sera faux.

{ $.SomeObject IS NULL }

Filtre de SomeObject défini sur null. Cela sera uniquement vrai si l'objet spécifié est défini sur null.

{ $.SomeOtherObject NOT EXISTS }

Filtre de SomeOtherObject inexistant. Cela sera uniquement vrai si l'objet spécifié n'existe pas dans les données du journal.

{ $.ThisFlag IS TRUE }

Filtres de ThisFlag étant TRUE. Cela fonctionne aussi pour les filtres booléens qui recherchent la valeur FALSE.

Conditions combinées JSON

Vous pouvez associer plusieurs conditions dans une expression composée à l'aide des opérateurs OR (||) et AND (&&). Les parenthèses sont autorisées et la syntaxe suit l'ordre normalisé des opérations () > && > ||.

{ "user": { "id": 1, "email": "John.Stiles@example.com" }, "users": [ { "id": 2, "email": "John.Doe@example.com" }, { "id": 3, "email": "Jane.Doe@example.com" } ], "actions": [ "GET", "PUT", "DELETE" ], "coordinates": [ [0, 1, 2], [4, 5, 6], [7, 8, 9] ] }
Examples
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }

Correspond au JSON ci-dessus.

{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }

Ne correspond pas au JSON ci-dessus.

{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch && $.actions[2] = nomatch }

Correspond au JSON ci-dessus.

{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch) && $.actions[2] = nomatch }

Ne correspond pas au JSON ci-dessus.

Considérations spéciales JSON

SELECTOR doit pointer vers un nœud de valeur (chaîne ou nombre) du JSON. S'il pointe vers un tableau ou un objet, le filtre ne sera pas appliqué, car le format du journal ne correspond pas au filtre. Par exemple, {$.users = 1} et {$.users != 1} échouent tous deux pour correspondre à un événement de journal où users est un tableau :

{ "users": [1, 2, 3] }
Comparaisons numériques

La syntaxe de filtre de métrique prend en charge la correspondance précise pour des comparaisons numériques. Les comparaisons numériques suivantes sont prises en charge : <, >, >=, <=, =, !=

La syntaxe des filtres numériques est de type

{ SELECTOR NUMERIC_OPERATOR NUMBER }

Le filtre de métrique doit être mis entre accolades { }, pour indiquer qu'il s'agit d'une expression JSON. Le filtre de métrique contient les éléments suivants :

SELECTOR

Spécifie la propriété JSON à vérifier. Les sélecteurs de propriétés commencent toujours par le symbole dollar ($), qui indique la racine de JSON. Les sélecteurs de propriétés sont des chaînes alphanumériques qui prennent également en charge les caractères « - » et « _ ». Les éléments du tableau sont indiqués par la syntaxe [NUMBER] et doivent suivre une propriété. Exemples : $.latency, $.numbers[0], $.errorCode, $.processes[4].averageRuntime.

NUMERIC_OPERATOR

Peut être l'un des types suivants : =, !=, <, >, <= ou >=.

NUMBER

Un nombre entier avec un signe + ou - facultatif, un nombre décimal avec un signe + ou - facultatif, ou un nombre en notation scientifique, qui est un nombre entier ou un nombre décimal avec un signe + ou - facultatif, suivi de « e » et suivi d'un nombre entier avec un signe + ou - facultatif.

Exemples :

{ $.latency >= 500 } { $.numbers[0] < 10e3 } { $.numbers[0] < 10e-3 } { $.processes[4].averageRuntime <= 55.5 } { $.errorCode = 400 } { $.errorCode != 500 } { $.latency > +1000 }

Utilisation de filtres de métriques pour extraire des valeurs d'événements du journal délimitées par des espaces

Vous pouvez utiliser des filtres de métriques pour extraire des valeurs d'événements du journal délimitées par des espaces. Les caractères entre une paire de crochets [] ou deux guillemets doubles ("") sont traités comme un champ unique. Par exemple :

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] "GET /apache_pb.gif HTTP/1.0" 200 1534 127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] "GET /apache_pb.gif HTTP/1.0" 500 5324 127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] "GET /apache_pb.gif HTTP/1.0" 200 4355

Pour spécifier un modèle de filtre de métrique qui analyse les événements délimités par des espaces, ce modèle doit spécifier les champs avec un nom, séparé par des virgules, avec le modèle tout entier entre crochets. Par exemple : [ip, user, username, timestamp, request, status_code, bytes].

Si vous ne connaissez pas le nombre de champs, vous pouvez utiliser la notification raccourcie avec les points de suspension (...). Par exemple :

[..., status_code, bytes] [ip, user, ..., status_code, bytes] [ip, user, ...]

Vous pouvez également ajouter des conditions à vos champs afin que seuls les événements du journal qui correspondent à toutes les conditions correspondent aux filtres. Par exemple :

[ip, user, username, timestamp, request, status_code, bytes > 1000] [ip, user, username, timestamp, request, status_code = 200, bytes] [ip, user, username, timestamp, request, status_code = 4*, bytes] [ip, user, username, timestamp, request = *html*, status_code = 4*, bytes]

Vous pouvez utiliser && comme opérateur AND logique et || comme opérateur OR logique, comme dans les exemples suivants :

[ip, user, username, timestamp, request, status_code = 4* && bytes > 1000] [ip, user, username, timestamp, request, status_code = 403 || status_code = 404, bytes]

CloudWatch Logs prend en charge les champs conditionnels numériques et de chaîne. Pour les champs de type chaîne, vous pouvez utiliser les opérateurs = ou != opérateurs avec un astérisque (*).

Pour les champs numériques, vous pouvez utiliser les opérateurs>, <, >=, <=, = et !=.

Si vous utilisez un filtre délimité par des espaces, les champs extraits sont mappés aux noms des champs délimités par des espaces (comme indiqué dans le filtre) à la valeur de chacun de ces champs. Si vous n'utilisez pas de filtre délimité par des espaces, cette valeur est vide.

Exemple de filtre :

[..., request=*.html*, status_code=4*,]

Exemple d'événement de journal pour ce filtre :

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534

Champs extraits pour le modèle de filtre et d'événement du journal :

{ "$status_code": "404", "$request": "GET /products/index.html HTTP/1.0", "$7": "1534", "$4": "10/Oct/2000:13:25:15 -0700", "$3": "frank", "$2": "-", "$1": "127.0.0.1" }

Configuration de la façon dont la valeur de métrique change lorsque des correspondances sont trouvées

Lorsqu'un filtre de métrique trouve l'un des termes, expressions ou valeurs de correspondance dans vos événements du journal, il augmente le nombre dans la métrique CloudWatch en fonction de la quantité que vous spécifiez comme valeur de métrique. La valeur de la métrique est agrégée et signalée toutes les minutes.

Si des journaux sont ingérés pendant une période d'une minute, mais qu'aucune correspondance n'est trouvée, la valeur spécifiée comme valeur par défaut (le cas échéant) est indiquée. Par contre, si aucun événement du journal n'est ingéré pendant une période d'une minute, aucune valeur n'est indiquée.

La spécification d'une valeur par défaut, même si cette valeur est 0, permet de s'assurer que des données sont indiquées plus souvent, ce qui évite les métriques irrégulières lorsqu’aucune correspondance n'est trouvée.

Par exemple, supposons qu'un groupe de journaux publie deux enregistrements toutes les minutes, avec une valeur de métrique égale à 1 et une valeur par défaut égale à 0. Si des correspondances sont trouvées dans les deux enregistrements du journal au cours de la première minute, la valeur de la métrique pour cette minute est égale à 2. S’il n’existe aucune correspondance dans les enregistrements du journal publiée au cours de la deuxième minute, la valeur par défaut 0 est utilisée pour les deux enregistrements du journal et la valeur de la métrique pour cette minute est égale à 0.

Si vous ne spécifiez aucune valeur par défaut, aucune donnée n'est indiquée pour les périodes sans correspondance de modèle.

Si vous attribuez des dimensions à une métrique créée par un filtre de métrique, vous ne pouvez pas attribuer une valeur par défaut pour cette métrique.

Publication de valeurs numériques trouvées dans des entrées de journal

Au lieu de seulement compter le nombre d'éléments correspondants trouvés dans les journaux, vous pouvez également utiliser le filtre de métrique pour publier des valeurs en fonction des valeurs numériques trouvées dans les journaux. La procédure suivante montre comment publier une métrique avec la latence trouvée dans la demande JSON metricFilter: { $.latency = * } metricValue: $.latency.

Pour publier une métrique avec la latence trouvée dans une demande JSON

  1. Ouvrez la console CloudWatch à l'adress https://console.aws.amazon.com/cloudwatch/.

  2. Dans le panneau de navigation, choisissez Log groups (Groupes de journaux).

  3. Choisissez Actions, Create metric filter (Créer un filtre de métrique).

  4. Pour Filter Pattern (Modèle de filtre), tapez { $.latency = * }, puis choisissez Next (Suivant).

  5. Dans Metric Name (Nom de la métrique), tapez myMetric.

  6. Dans Metric Value (Valeur de la métrique), saisissez $.latency.

  7. Dans Default Value (Valeur par défaut), saisissez 0, puis choisissez Next (Suivant). La spécification d'une valeur par défaut garantit que les données soient indiquées même pendant les périodes où aucun événement du journal ne correspond au filtre. Cela empêche des métriques irrégulières ou manquantes lorsque les journaux sont ingérés, mais qu’ils ne correspondent pas au filtre.

  8. Choisissez Create metric filter (Créer un filtre de métrique).

L'événement du journal suivant publierait une valeur de 50 pour la métrique myMetric suite à la création du filtre.

{ "latency": 50, "requestType": "GET" }

Publication de dimensions avec vos métriques

Lorsque vous publiez une métrique générée à partir de valeurs trouvées dans des événements du journal JSON ou des événements du journal délimités par des espaces, vous pouvez également publier des dimensions avec la métrique. Vous pouvez publier jusqu'à trois dimensions avec une métrique générée par un filtre métrique. Pour obtenir plus d'informations sur les dimensions, consultez Dimensions.

Avertissement

Les métriques extraites des événements du journal sont facturées en tant que métriques personnalisées. Pour éviter des charges élevées inattendues, ne spécifiez pas de champs à cardinalité élevée tels que IPAddress ou requestID comme dimensions. Chaque valeur différente trouvée pour une dimension est traitée comme une métrique distincte et accumule des frais comme une métrique personnalisée distincte.

Pour éviter des frais élevés accidentels, Amazon peut désactiver un filtre métrique s'il génère 1000 paires nom/valeur différentes pour les dimensions que vous avez spécifiées dans un certain laps de temps.

Vous pouvez également configurer une alarme de facturation pour vous alerter si vos frais sont plus élevés que prévu. Pour plus d'informations, consultez Création d'une alarme de facturation permettant de surveiller les coûts AWS estimés.

Publication de dimensions avec des métriques à partir d'événements du journal JSON

Pour voir comment spécifier les dimensions d'un filtre de métrique pour les événements du journal JSON, commençons par examiner un exemple de filtre et un exemple d'un événement de journal pour le filtre.

Exemple de filtre :

{ $.eventType = "*" && $.sourceIPAddress != 123.123.*}

Exemple d'événements du journal:

{"eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ {"name": "a", "id": 1 }, {"name": "b", "id": 2 } ], "SomeObject": null, "ThisFlag": true }

Cet exemple de filtre incrémente la métrique chaque fois qu'un événement de journal comprend l'un des champs énumérés dans le filtre.

[ $.eventType, $.sourceIPAddress ]

Lorsque vous créez votre filtre de métrique, vous pouvez spécifier n'importe lequel des champs de votre filtre comme une dimension. Par exemple, pour définir le type d'événement comme une dimension, spécifiez ce qui suit comme dimension lorsque vous configurez votre filtre de métrique.

"EventType" : $.eventType

Cette métrique a une dimension nommée EventType, et les valeurs des dimensions sont les types d'événements trouvés dans les événements du journal, tels que UpdateTrail dans cet exemple d'événement du journal.

Publication de dimensions avec des métriques à partir d'événements du journal délimités par des espaces

Pour voir comment spécifier les dimensions d'un filtre de métrique pour les événements du journal délimités par des espaces, commençons par examiner un exemple de filtre et un exemple d'un événement de journal pour le filtre.

Exemple de filtre :

[ip, server, username, timestamp, request, status_code, bytes > 1000]

Exemple d'événements du journal:

127.0.0.1 Prod frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534

Cet exemple de filtre incrémente la métrique chaque fois qu'un événement de journal comprend l'un des champs énumérés dans le filtre. Pour l'exemple d'événement de journal présenté précédemment, le filtre trouve les champs et valeurs suivants.

{ "$status_code": "404", "$request": "GET /products/index.html HTTP/1.0", "$bytes": "1534", "$timestamp": "10/Oct/2000:13:25:15 -0700", "$username": "frank", "$server": "Prod", "$ip": "127.0.0.1" }

Lorsque vous créez votre filtre de métrique, vous pouvez spécifier n'importe lequel de ces champs comme dimension. Par exemple, pour définir le nom du serveur comme une dimension, vous devez spécifier la dimension suivante lorsque vous configurez votre filtre de métrique.

"Server" : $server

Cette métrique a une dimension nommée Server, et les valeurs des dimensions sont les noms de serveurs trouvés dans les événements du journal, tels que Prod dans cet exemple d'événement de journal.