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

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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 journaux d'évènements et les faire correspondre. Lorsqu'un filtre de métrique trouve l'un des termes, expressions ou valeurs dans vos événements de journaux, vous pouvez augmenter la valeur de la métrique CloudWatch Par exemple, vous pouvez créer un filtre de métrique pour rechercher et compter l'occurrence du mot ERROR dans vos événements de journaux.

Les filtres de métriques peuvent également extraire des valeurs numériques de vos journaux d'évènements, délimitées par des espaces, comme la latence des requêtes web. Dans ces exemples, vous pouvez augmenter la valeur de vos métriques par la valeur numérique réelle extraite du journal.

Vous pouvez utiliser des opérateurs conditionnels et des caractères génériques pour créer des correspondances exactes. 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 des filtres de métriques.

Etablissement de correspondances de termes dans les événements de journaux

Pour rechercher un terme dans les événements de journaux, 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 de journal pour qu'il y ait une 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 à l'intérieur de 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 de journaux.

Exemple 2 : terme unique

Le modèle de filtre « ERROR » correspond aux messages d'événements de journaux 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 de journaux qui contiennent les deux termes, à l'image des exemples suivants :

  • [ERROR] Intercepté IllegalArgumentException

  • [ERROR] Unhandled Exception

Le modèle de filtre « Failed to process the request » correspond aux messages d'événements de journaux 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 du critère spécial OR. Utilisez un point d'interrogation pour OR, par exemple ?term.

Observez les trois exemples d'événements de journaux ci-dessous. ERROR correspond aux exemples 1 et 2. ?ERROR ?WARN correspond aux exemples 1, 2 et 3, car ils incluent tous le mot ERROR ou le mot WARN. ERROR WARN correspond uniquement à l'exemple 1, car il s'agit du seul exemple 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 du critère spécial 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, et ainsi de suite. Pour les exemples de modèles ci-dessous, [w1, w2] correspond aux modèles 1 et 2, car ERROR est le premier mot, et [w1 || w1, w2] correspond aux modèles 1, 2 et 3. [w1 ERREUR&&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 du critère spécial 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"}

Etablissement de correspondances dans les événements de journaux JSON

Vous pouvez extraire des valeurs d'événements de journaux JSON. Pour extraire ces valeurs, 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 de journaux JSON doivent correspondre exactement au filtre métrique. Vous pouvez créer des filtres de métriques dans des événements de journaux JSON pour indiquer ce qui suit :

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

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

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

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

Vous pouvez utiliser des filtres de métriques pour extraire des valeurs d'événements de journaux 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 le décompte chaque fois que le texte correspondant est trouvé dans un journal, ou vous pouvez extraire des valeurs numériques à partir du journal et les utiliser pour augmenter la valeur des métriques.

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

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

{ SELECTOR EQUALITY_OPERATOR STRING }

Le filtre de métrique doit être placé dans des 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 du 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 signalé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 !=

STRING

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. correspond à l'événement* EventId et à EventName. Ev*ent correspond uniquement à la chaîne 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 placés entre guillemets pour être valides.

Exemples de filtres de métrique JSON

Voici un exemple 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" }

Filtrez sur le type d'événement . UpdateTrail

{ $.sourceIPAddress != 123.123.* }

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

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

Filtre sur la première entrée qui arrayKey est « value ». Cela sera faux si arrayKey n'est pas un tableau.

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

Filtre sur la deuxième entrée objectList ayant une propriété appelée id = 2. Cela sera faux si objectList n'est pas un tableau. Cela sera faux si les éléments de ne objectList sont pas des objets ou n'ont pas de propriété id.

{ $.SomeObject IS NULL }

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

{ $.SomeOtherObject NOT EXISTS }

Filtre selon l'absence SomeOtherObject d'existant. Cela sera uniquement vrai si l'objet spécifié n'existe pas dans les données de journaux.

{ $.ThisFlag IS TRUE }

Filtres sur ThisFlag 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 de OR (||) et AND (&&). Les parenthèses sont autorisées et la syntaxe suit l'ordre standard 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 de 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 : <, >, >=, <=, =, !=

Les filtres numériques ont une syntaxe de type

{ SELECTOR NUMERIC_OPERATOR NUMBER }

Le filtre de métrique doit être placé dans des 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 du 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 signalé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 de journaux délimitées par des espaces

Vous pouvez utiliser des filtres de métriques pour extraire des valeurs d'événements de journaux 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. Exemples :

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 (...). Exemples :

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

Vous pouvez également ajouter des conditions à vos champs afin que seuls les événements de journaux qui correspondent à toutes les conditions correspondent aux filtres. Exemples :

[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 ET logique et || comme opérateur OU 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 correspondent 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, ceci sera 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 de 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 de journaux, 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 métrique est regroupée et signalée chaque minute.

Si des journaux sont ingérés pendant une période d'une minute, mais qu'aucun profil n'est détecté, la valeur spécifiée comme valeur par défaut (le cas échéant) est rapportée. Par contre, si aucun événement de journal n'est ingéré pendant une période d'une minute, aucune valeur n'est rapporté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 rapportées plus souvent, ce qui évite les métriques irrégulières quand 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 de journaux au cours de la première minute, la valeur de métrique pour cette minute est égale à 2. S'il n'y a pas de correspondance dans les enregistrements de journaux publiés au cours de la deuxième minute, la valeur par défaut 0 est utilisée pour les deux enregistrements de journaux et la valeur de métrique pour cette minute est égale à 0.

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

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'adresse https://console.aws.amazon.com/cloudwatch/.

  2. Dans le volet de navigation, sélectionnez Groupes de journaux.

  3. Choisissez Actions, Créer un filtre de métriques.

  4. Pour Modèle de filtre, tapez { $.latency = * }, puis choisissez Suivant.

  5. Pour Nom de la métrique, tapez myMetric.

  6. Pour Valeur de la métrique, saisissez $.latency.

  7. Dans Valeur par défaut entrez 0, puis choisissez Suivant. La spécification d'une valeur par défaut garantit que les données sont signalées même pendant les périodes où aucun événement de journal ne correspond au filtre. Cela empêche les mesures ponctuelles ou manquantes lorsque les journaux sont ingérés mais ne correspondent pas au filtre.

  8. Choisissez Créer un filtre de métriques.

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

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