Aperçu

Créez des règles grok personnalisées pour analyser le message complet ou un attribut spécifique de votre événement brut. En tant que meilleure pratique, il est recommandé d’utiliser au maximum 10 règles d’analyse dans un processeur grok.

Cliquez sur Analyser mes événements pour démarrer un ensemble de trois règles d’analyse pour les événements circulant dans le pipeline sous-jacent. Affinez la nomination des attributs à partir de là, et ajoutez de nouvelles règles pour d’autres types d’événements si nécessaire. Cette fonctionnalité nécessite que les événements correspondants soient indexés et effectivement en cours de traitement ; vous pouvez temporairement désactiver ou réduire les filtres d’exclusion pour que cela fonctionne pour vous.

Cliquez sur un échantillon pour le sélectionner et déclencher son évaluation par rapport à la règle de parsing. Le résultat s’affiche alors en bas de l’écran.

Jusqu’à cinq échantillons peuvent être enregistrés avec le processeur, et chaque échantillon peut avoir jusqu’à 5000 caractères de longueur. Tous les échantillons affichent un statut (correspondance ou non correspondance), ce qui met en évidence si l’une des règles d’analyse du parseur grok correspond à l’échantillon.

Syntaxe Grok

Le parseur Grok extrait des attributs de messages texte semi-structurés. Grok est livré avec des modèles réutilisables pour analyser des entiers, des adresses IP, des noms d’hôtes, et plus encore. Ces valeurs doivent être envoyées au parseur grok sous forme de chaînes.

Vous pouvez écrire des règles d’analyse avec la syntaxe %{MATCHER:EXTRACT:FILTER} :

• Correspondant : Une règle (éventuellement une référence à une autre règle de jeton) qui décrit ce à quoi s’attendre (nombre, mot, non espace, etc.).

• Extraire (optionnel) : Un identifiant représentant la destination de capture pour le morceau de texte correspondant au Correspondant.

• Filtre (optionnel) : Un post-traitement de la correspondance pour la transformer.

Exemple pour un événement non structuré classique :

john connected on 11/08/2017

Avec la règle de parsing suivante :

MyParsingRule %{word:user} connected on %{date("MM/dd/yyyy"):date}

Après traitement, l’événement structuré suivant est généré :

Remarque :

• Si vous avez plusieurs règles d’analyse dans un seul parseur Grok :
  • Une seule peut correspondre à un événement donné. La première qui correspond, de haut en bas, est celle qui effectue l’analyse.
  • Chaque règle peut référencer des règles d’analyse définies au-dessus d’elle dans la liste.
• Vous devez avoir des noms de règles uniques au sein du même parseur Grok.
• Le nom de la règle doit contenir uniquement : des caractères alphanumériques, _ et .. Il doit commencer par un caractère alphanumérique.
• Les propriétés avec des valeurs nulles ou vides ne sont pas affichées.
• Le matcher regex applique un ^ implicite, pour correspondre au début d’une chaîne, et un $, pour correspondre à la fin d’une chaîne.
• Certains événements peuvent produire de grands espaces vides. Utilisez \n et \s+ pour tenir compte des nouvelles lignes et des espaces vides.

Correspondant et filtre

Voici la liste de tous les matchers et de tous les filtres implémentés en natif par Datadog :

Paramètres avancés

En bas de vos tuiles de processeur Grok, il y a une section Paramètres avancés :

Analyse d’un attribut de texte spécifique

Utilisez le champ Extraire de pour appliquer votre processeur Grok sur un attribut de texte donné au lieu de l’attribut par défaut message.

Par exemple, considérez un événement contenant un command.line attribut qui doit être analysé comme une paire clé-valeur. Vous pourriez analyser cet événement comme suit :

Utilisation de règles d’aide pour factoriser plusieurs règles d’analyse

Utilisez le champ Règles d’aide pour définir des tokens pour vos règles d’analyse. Les règles d’aide vous aident à factoriser les motifs Grok à travers vos règles d’analyse. Ceci est utile lorsque vous avez plusieurs règles dans le même parseur Grok qui utilisent les mêmes tokens.

Exemple pour un événement non structuré classique :

john id:12345 connected on 11/08/2017 on server XYZ in production

Utilisez la règle de parsing suivante :

MyParsingRule %{user} %{connection} %{server}

Avec les auxiliaires suivants :

user %{word:user.name} id:%{integer:user.id}
connection connected on %{date("MM/dd/yyyy"):connect_date}
server on server %{notSpace:server.name} in %{notSpace:server.env}

Exemples

Voici des exemples d’utilisation des parsers :

• Valeur clé ou logfmt
• Analyse des dates
• Modèles alternés
• Attribut optionnel
• JSON imbriqué
• Regex
• Listes et tableaux
• Format Glog
• XML
• CSV

Valeur clé ou logfmt

Ceci est le filtre de base clé-valeur : keyvalue([separatorStr[, characterAllowList[, quotingStr[, delimiter]]]]) où :

• separatorStr : définit le séparateur entre les clés et les valeurs. Par défaut, c’est =.
• characterAllowList : définit des caractères de valeur supplémentaires non échappés en plus de la valeur par défaut \\w.\\-_@. Utilisé uniquement pour les valeurs non citées (par exemple, key=@valueStr).
• quotingStr : définit les guillemets, remplaçant la détection par défaut des guillemets : <>, "", ''.
• delimiter : définit le séparateur entre les différentes paires clé-valeur (par exemple, | est le délimiteur dans key1=value1|key2=value2). Par défaut, c’est (espace normal), , et ;.

Utilisez des filtres tels que keyvalue pour mapper plus facilement des chaînes à des attributs pour les formats keyvalue ou logfmt :

Événement :

user=john connect_date=11/08/2017 id=123 action=click

Règle :

rule %{data::keyvalue}

Vous n’avez pas besoin de spécifier le nom de vos paramètres car ils sont déjà contenus dans l’événement. Si vous ajoutez un attribut extract my_attribute dans votre modèle de règle, vous verrez :

Si = n’est pas le séparateur par défaut entre vos clés et valeurs, ajoutez un paramètre dans votre règle de parsing avec un séparateur.

Événement :

user: john connect_date: 11/08/2017 id: 123 action: click

Règle :

rule %{data::keyvalue(": ")}

Si l’événement contient des caractères spéciaux dans une valeur d’attribut, comme / dans une URL par exemple, ajoutez-le à la liste blanche dans la règle de parsing :

Événement :

url=https://app.datadoghq.com/event/stream user=john

Règle :

rule %{data::keyvalue("=","/:")}

Autres exemples :

Exemple de chaîne de citation multiple : Lorsque plusieurs chaînes de citation sont définies, le comportement par défaut est remplacé par un caractère de citation défini. La clé-valeur correspond toujours aux entrées sans aucun caractère de citation, quel que soit ce qui est spécifié dans quotingStr. Lorsque des caractères de citation sont utilisés, le characterAllowList est ignoré car tout ce qui se trouve entre les caractères de citation est extrait.

Événement :

key1:=valueStr key2:=</valueStr2> key3:="valueStr3"

Règle :

rule %{data::keyvalue(":=","","<>")}

Résultat :

{"key1": "valueStr", "key2": "/valueStr2"}

Remarque :

• Les valeurs vides (key=) ou les valeurs null (key=null) ne sont pas affichées dans le JSON de sortie.
• Si vous définissez un filtre clévaleur sur un data objet, et que ce filtre n’est pas respecté, alors un JSON vide {} est retourné (par exemple, entrée : key:=valueStr, règle de parsing : rule_test %{data::keyvalue("=")}, sortie : {}).
• Définir "" comme quotingStr conserve la configuration par défaut pour la citation.

Parsing des dates

Le date matcher transforme votre horodatage au format EPOCH (unité de mesure millisecondes).

¹ Utilisez le timezone paramètre si vous effectuez vos propres localisations et que vos horodatages ne sont pas en UTC. Les formats pris en charge pour les fuseaux horaires sont :

• GMT, UTC, UT ou Z
• +h, +hh, +hh:mm, -hh:mm, +hhmm, -hhmm, +hh:mm:ss, -hh:mm:ss, +hhmmss ou -hhmmss. La plage maximale prise en charge est de +18:00 à -18:00 inclus.
• Les fuseaux horaires commençant par UTC+, UTC-, GMT+, GMT-, UT+ ou UT-. La plage maximale prise en charge est de +18:00 à -18:00 inclus.
• Identifiants de fuseaux horaires extraits de la base de données TZ. Pour plus d’informations, consultez noms de la base de données TZ.

Remarque : L’analyse d’une date ne définit pas sa valeur comme la date officielle de l’événement. Pour cela, utilisez le Remappeur de date d’événement dans un processeur ultérieur.

Modèle alternatif

Si vous avez des événements avec deux formats possibles qui diffèrent par un seul attribut, définissez une règle unique en utilisant l’alternance avec (<REGEX_1>|<REGEX_2>). Cette règle est équivalente à un OU booléen.

Événement :

john connected on 11/08/2017
12345 connected on 11/08/2017

Règle : Notez que “id” est un entier et non une chaîne.

MyParsingRule (%{integer:user.id}|%{word:user.firstname}) connected on %{date("MM/dd/yyyy"):connect_date}

Résultats :

Attribut optionnel

Certains événements contiennent des valeurs qui n’apparaissent qu’une partie du temps. Dans ce cas, rendez l’extraction d’attributs optionnelle avec ()?.

Événement :

john 1234 connected on 11/08/2017

Règle :

MyParsingRule %{word:user.firstname} (%{integer:user.id} )?connected on %{date("MM/dd/yyyy"):connect_date}

Remarque : Une règle ne correspondra pas si vous incluez un espace après le premier mot dans la section optionnelle.

JSON imbriqué

Utilisez le filtre json pour analyser un objet JSON imbriqué après un préfixe de texte brut :

Événement :

Sep 06 09:13:38 vagrant program[123]: server.1 {"method":"GET", "status_code":200, "url":"https://app.datadoghq.com/logs/pipelines", "duration":123456}

Règle :

parsing_rule %{date("MMM dd HH:mm:ss"):timestamp} %{word:vm} %{word:app}\[%{number:logger.thread_id}\]: %{notSpace:server} %{data::json}

Regex

Événement :

john_1a2b3c4 connected on 11/08/2017

Règle :

MyParsingRule %{regex("[a-z]*"):user.firstname}_%{regex("[a-zA-Z0-9]*"):user.id} .*

Liste en tableau

Utilisez le filtre array([[openCloseStr, ] separator][, subRuleOrFilter) pour extraire une liste dans un tableau dans un seul attribut. Le subRuleOrFilter est optionnel et accepte ces filtres.

Événement :

Users [John, Oliver, Marc, Tom] have been added to the database

Règle :

myParsingRule Users %{data:users:array("[]",",")} have been added to the database

Événement :

Users {John-Oliver-Marc-Tom} have been added to the database

Règle :

myParsingRule Users %{data:users:array("{}","-")} have been added to the database

Règle utilisant subRuleOrFilter :

myParsingRule Users %{data:users:array("{}","-", uppercase)} have been added to the database

Format Glog

Les composants Kubernetes enregistrent parfois au format glog ; cet exemple provient de l’élément Kube Scheduler dans la bibliothèque Pipeline.

Exemple d’événement :

W0424 11:47:41.605188       1 authorization.go:47] Authorization is disabled

Règles de parsing :

kube_scheduler %{regex("\\w"):level}%{date("MMdd HH:mm:ss.SSSSSS"):timestamp}\s+%{number:logger.thread_id} %{notSpace:logger.name}:%{number:logger.lineno}\] %{data:msg}

JSON extrait :

{
  "level": "W",
  "timestamp": 1587728861605,
  "logger": {
    "thread_id": 1,
    "name": "authorization.go"
  },
  "lineno": 47,
  "msg": "Authorization is disabled"
}

Analyse XML

Le parser de XML permet de transformer des messages au format XML en JSON.

Événement :

<book category="CHILDREN">
  <title lang="en">Harry Potter</title>
  <author>J K. Rowling</author>
  <year>2005</year>
</book>

Règle :

rule %{data::xml}

Résultat :

{
"book": {
  "year": "2005",
  "author": "J K. Rowling",
  "category": "CHILDREN",
  "title": {
    "lang": "en",
    "value": "Harry Potter"
  }
}
}

Notes :

• Si le XML contient des balises ayant à la fois un attribut et une valeur de chaîne entre les deux balises, un attribut value est généré. Par exemple : <title lang="en">Harry Potter</title> est converti en {"title": {"lang": "en", "value": "Harry Potter" } }.
• Les balises répétées sont automatiquement converties en tableaux. Par exemple : <bookstore><book>Harry Potter</book><book>Everyday Italian</book></bookstore> est converti en { "bookstore": { "book": [ "Harry Potter", "Everyday Italian" ] } }.

Parsing CSV

Utilisez le filtre CSV pour associer plus facilement les chaînes aux attributs lorsqu’elles sont séparées par un caractère donné (, par défaut).

Le filtre CSV est défini comme csv(headers[, separator[, quotingcharacter]]) où :

• headers : Définit les noms de clés séparés par ,. Les noms de clés doivent commencer par un caractère alphabétique et peuvent contenir tout caractère alphanumérique en plus de _.
• separator : Définit les séparateurs utilisés pour séparer les différentes valeurs. Un seul caractère est accepté. Par défaut : ,. Remarque : Utilisez tab pour le separator afin de représenter le caractère de tabulation pour les TSV.
• quotingcharacter : Définit le caractère de citation. Un seul caractère est accepté. Par défaut : "

Remarque :

• Les valeurs contenant un caractère séparateur doivent être citées.
• Les valeurs entre guillemets contenant un caractère de citation doivent être échappées avec un caractère de citation. Par exemple, "" dans une valeur citée représente ".
• Si l’événement ne contient pas le même nombre de valeurs que le nombre de clés dans l’en-tête, le parseur CSV associera les premières.
• Les entiers et les doubles sont automatiquement convertis si possible.

Événement :

John,Doe,120,Jefferson St.,Riverside

Règle :

myParsingRule %{data:user:csv("first_name,name,st_nb,st_name,city")}

Résultat :

{
  "user": {
    "first_name": "John",
    "name": "Doe",
    "st_nb": 120,
    "st_name": "Jefferson St.",
    "city": "Riverside"
  }
}

Autres exemples :

Utilisez le data matcher pour éliminer le texte inutile

Si vous avez un événement où, après avoir analysé ce qui est nécessaire et sachant que le texte après ce point peut être éliminé, vous pouvez utiliser le data matcher pour le faire. Pour l’exemple d’événement suivant, vous pouvez utiliser le data matcher pour éliminer le % à la fin.

Événement :

Usage: 24.3%

Règle :

MyParsingRule Usage\:\s+%{number:usage}%{data:ignore}

Résultat :

{
  "usage": 24.3,
  "ignore": "%"
}

Caractères de contrôle ASCII

Si vos événements contiennent des caractères de contrôle ASCII, ils sont sérialisés lors de l’ingestion. Ceci peut être géré en échappant explicitement la valeur sérialisée dans votre parseur grok.