Parsing

Présentation

Datadog analyse automatiquement les logs au format JSON. Pour les autres formats, Datadog vous permet d’enrichir vos logs à l’aide du parser Grok. Comparée à l’utilisation exclusive d’expressions régulières, la syntaxe Grok simplifie l’analyse des logs. Le parser Grok vous permet d’extraire des attributs à partir de messages texte semi-structurés.

Grok propose des patterns réutilisables pour analyser des entiers, des adresses IP, des hostnames, etc.

Vous pouvez rédiger des règles de parsing à l’aide de la syntaxe %{MATCHER:EXTRACT:FILTER} :

• Matcher : une règle (éventuellement une référence à la règle d’un autre token) qui décrit la valeur attendue (number, word, notSpace, etc.).

• Extract (facultatif) : un identifiant représentant la destination d’enregistrement pour le morceau de texte correspondant au Matcher.

• Filter (facultatif) : un post-processeur de la correspondance permettant de la transformer.

Exemple d’un log non structuré standard :

john connected on 11/08/2017

Avec la règle de parsing suivante :

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

Une fois le traitement terminé, le log structuré suivant est généré :

Remarque :

• Si vous cumulez plusieurs règles de parsing dans un seul parser Grok :
  • Une seule d’entre elles peut renvoyer un log donné. La première qui correspond en totalité est celle qui effectue le parsing.
  • Chaque règle peut se référer à des règles de parsing définies en amont dans la liste.
• Les noms des règles au sein d’un même parser Grok doivent être uniques.
• Les noms des règles doivent contenir uniquement des caractères alphanumériques, ainsi que les caractères _ et .. Ils doivent commencer par un caractère alphanumérique.

Matcher 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 carrés de processeur Grok, vous trouverez une section Advanced Settings :

• Utilisez le champ Extract from pour appliquer votre processeur Grok sur un attribut donné plutôt que sur l’attribut message par défaut.

• Utilisez le champ Helper Rules afin de définir les tokens pour vos règles de parsing. Les règles d’auxiliaires vous aident à factoriser les patterns Grok dans vos règles d’analyse, ce qui est utile lorsque plusieurs règles d’un même parser Grok utilisent les mêmes tokens.

Exemple d’un log non structuré standard :

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 :

• Key/value
• Parsing de dates
• Patterns conditionnels
• Attribut facultatif
• JSON imbriqué
• Regex

Key/value

Le filtre key/value correspond à keyvalue([separatorStr[, characterWhiteList [, quotingStr]]]), où :

• separatorStr définit le séparateur. Valeur par défaut : =.
• characterWhiteList définit des caractères supplémentaires non échappés. Valeur par défaut : \\w.\\-_@. Uniquement utilisé pour les valeurs sans guillemets (par exemple, key=@valueStr).
• quotingStr définit des guillemets. Par défaut, ce paramètre permet de détecter les guillemets (<>, "", etc.).

Remarque : si vous définissez un filtre keyvalue sur un objet data et que ce filtre n’est pas mis en correspondance, un JSON vide {} est renvoyé (par exemple, entrée : key:=valueStr, règle de parsing : rule_test %{data::keyvalue("=")}, sortie : {}).

Utilisez des filtres tels que keyvalue() pour mapper plus facilement des chaînes à des attributs :

Log :

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 le log. Si vous ajoutez un attribut d’extraction my_attribute dans votre pattern de règles, vous obtenez :

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

Log :

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

Règle :

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

Si le log contient des caractères spéciaux dans une valeur d’attribut, tels que le caractère / dans une URL, ajoutez-les à la liste blanche de la règle de parsing :

Log :

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

Règle :

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

Autres exemples :

Exemple avec plusieurs QuotingString : lorsque des QuotingString sont définies, le comportement par défaut est ignoré, et seul le guillemet défini est autorisé. Le filtre keyvalue met toujours en correspondance des entrées sans guillemet, peu importe la valeur de quotingStr. Lorsque des guillemets sont utilisés, le paramètre characterWhiteList est ignoré, puisque tout le contenu entre les guillemets est extrait.

Log :

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

Règle :

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

Résultat :

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

Parsing de dates

Le matcher de date convertit votre timestamp au format EPOCH (unité de mesure : millisecondes).

¹ Utilisez ce format si vous effectuez vos propres localisations et que vos timestamps ne sont pas au fuseau UTC. Les identifiants de fuseaux horaires sont extraits de la base de données TZ. Pour en savoir plus, consultez les noms de la base de données TZ.

Remarque : le parsing d’une date ne définit pas sa valeur comme étant la date officielle du log. Pour cela, utilisez le remappeur de dates de log dans un processeur ultérieur.

Pattern conditionnel

Il arrive que vos logs se présentent dans deux formats différents, avec un unique attribut comme seule différence. Ces cas peuvent être traités avec une seule règle, en utilisant des instructions conditionnelles avec (<REGEX_1>|<REGEX_2>).

Log :

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

Règle : Notez que « id » est un nombre entier et non une chaîne grâce au matcher « integer » de la règle.

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

Résultats :

Attribut facultatif

Certains logs contiennent des valeurs qui n’apparaissent que de temps en temps. Dans ce cas, vous pouvez rendre l’extraction d’attributs facultative avec ()? afin de l’extraire uniquement lorsque l’attribut est présent dans votre logs.

Log :

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 : vous devrez généralement inclure l’espace dans la partie facultative afin de ne pas obtenir deux espaces, ce qui empêcherait la règle de fonctionner.

JSON imbriqué

Utilisez le filtre json pour effectuer le parsing d’un objet JSON imbriqué après un préfixe de texte brut :

Log :

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

Utilisez le matcher regex pour identifier une sous-chaîne de votre message de log en fonction de règles littérales regex.

Log :

john_1a2b3c4 connected on 11/08/2017

Règle : Nous cherchons ici l’ID à extraire.

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

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Apprendre à traiter vos logsDOCUMENTATION Comment étudier un problème de parsing de log ?FAQ Parsing de log : bonnes pratiques à adopterFAQ Contrôler le volume de logs indexés par DatadogDOCUMENTATION