Les fichiers de log contiennent une multitude de données précieuses sur vos applications et vos opérations. Malheureusement, ces fichiers de log étant bien souvent laissés à l’abandon, l’utilité des données qu’ils contiennent n’est que rarement reconnue. Grâce à sa fonctionnalité de parsing des métriques et des événements en provenance des logs, l’Agent Datadog peut vous aider à remédier à ce problème en représentant graphiquement les données en temps réel et en continu.

Parsing de métriques

L’Agent Datadog peut analyser les métriques issues de vos fichiers de log :

• à partir du format de log canonique de Datadog, sans programmation supplémentaire
• à partir de n’importe quel autre format de log, avec une fonction de parsing de log personnalisée

Format de log canonique de Datadog

Les logs Datadog sont formatés comme suit :

metric unix_timestamp value [attribute1=v1 attributes2=v2 ...]

Par exemple, imaginons que le contenu de /var/log/web.log est :

me.web.requests 1320786966 157 metric_type=counter unit=request
me.web.latency 1320786966 250 metric_type=gauge unit=ms

Pour que Datadog soit en mesure de lire les métriques, il vous suffit d’ajouter cette ligne au fichier de configuration de votre Agent (généralement /etc/dd-agent/datadog.conf) :

dogstreams: /var/log/web.log

Vous pouvez également spécifier plusieurs fichiers de log de cette manière :

dogstreams: /var/log/web.log, /var/log/db.log, /var/log/cache.log

Parsing de formats de log personnalisés

Si vous souhaitez parser un format de log différent, par exemple pour un logiciel tiers ou obsolète, vous pouvez utiliser une fonction Python personnalisée pour extraire les champs appropriés du log. Pour ce faire, spécifiez votre fichier de log dans le fichier de configuration de votre Agent au format suivant :

dogstreams: /var/log/web.log:parsers:parse_web

parsers:parse_web indique que la fonction Python personnalisée se trouve dans un paquet appelé parsers dans le PYTHONPATH de l’Agent, et que le paquet parsers a une fonction appelée parse_web. Le PYTHONPATH de l’Agent est défini dans le script de démarrage de l’Agent, /etc/init.d/datadog-agent, dans la configuration du superviseur pour la version de l’Agent.

Si le parser ne se trouve pas dans le PYTHONPATH de l’Agent, vous pouvez utiliser une autre syntaxe pour configurer votre parser de lignes :

dogstreams: /chemin/vers/log1:/chemin/vers/mon/module_parsing.py:custom_parser

Dans ce format, l’Agent tente d’importer une fonction appelée custom_parser à partir de /chemin/vers/mon/parsers_module.py.

Si votre parser de logs personnalisé ne fonctionne pas, vérifiez tout d’abord les logs du Collector de l’Agent :

• Si l’Agent n’est pas en mesure d’importer votre fonction, recherchez Could not load Dogstream line parser.

• Si tout fonctionne comme prévu, vous devriez voir dogstream: parsing {nom du fichier} with {nom de la fonction} (requested {texte option de configuration}).

Rédaction de fonctions de parsing

Les fonctions de parsing personnalisées doivent :

• accepter deux paramètres : un objet logger Python (pour le debugging) et un paramètre de chaîne spécifiant la ligne à parser.

• renvoyer un tuple ou une liste de tuples sous la forme :

  (metric (str), timestamp (unix timestamp), value (float), attributes (dict))

  Les attributs doivent au minimum comprendre la clé metric_type, qui spécifie si la métrique donnée est de type counter ou gauge.

  Si la ligne ne correspond pas, la valeur renvoyée doit être None.

Collecte de métriques

Imaginons que vous recueillez des métriques à partir de logs qui ne sont pas formatés canoniquement, mais intelligemment délimités par un caractère unique. Les logs se présentent de la manière suivante :

user.crashes|2016-05-28 20:24:43.463930|24|LotusNotes,Outlook,Explorer

Vous pouvez définir un parser de logs comme suit afin de recueillir une métrique à partir des données loguées dans votre compte Datadog :

import time
from datetime import datetime
...
def my_log_parser(logger, test):
    metric_name, date, metric_value, extras = line.split('|')
    # Convertir la date ISO 8601 en timestamp Unix, en supposant que la chaîne du timestamp
    # est dans le même fuseau horaire que la machine qui effectue le parsing.
    date = datetime.strptime(date, "%Y-%m-%d %H:%M:%S.%f")
    tags = extras.split(',')
    date = time.mktime(date.timetuple())
    metric_attributes = {
        'tags': tags,
        'metric_type': 'gauge',
    }
    return (metric_name, date, metric_value, metric_attributes)

Ensuite, modifiez votre fichier datadog.conf en ajoutant l’option dogstream comme suit :

dogstreams: /chemin/vers/monfichier.log:/chemin/vers/mylogparser.py:my_log_parser
# (Remarque : si vous utilisez Windows, remplacez chaque / par la séquence d'échappement \\)

Cet exemple permettrait de recueillir une métrique de type gauge appelée user.crashes avec une valeur égale à 24, les noms des trois applications étant ajoutés sous forme de tag à la fin.

Avertissement : le nombre de fois qu’une même métrique peut être recueillie à chaque analyse du fichier de log est limité. En effet, l’Agent écrase une métrique loguée dès que la même métrique est à nouveau recueillie, même si ses attributs (comme ses tags) sont différents. Ce problème ne se présente pas lorsque les métriques recueillies à partir des logs ont des timestamps suffisamment différents, mais il est généralement conseillé de recueillir chaque métrique toutes les 10 secondes environ. Les métriques recueillies sous des noms différents ne sont pas écrasées.

Parsing d’événements

Le parsing d’événements repose sur les mêmes fonctions de parsing personnalisées que celles décrites ci-dessus, à une exception près : si votre fonction de parsing personnalisée renvoie un dict (ou une list de dict), Datadog la traite comme un événement, et non comme une métrique.

Les champs d’événement sont les suivants (en gras si obligatoires) :

Les événements ayant la même clé d’agrégation sur une période de 24 heures sont regroupés sur le flux. La clé d’agrégation est une combinaison des champs suivants :

• event_type
• aggregation_key
• host

Pour obtenir un exemple de parser d’événements, consultez notre parser d’événements de compactage Cassandra fourni avec l’Agent.

Collecte d’événements

Imaginons que vous souhaitez recueillir des événements à partir de logs auxquels vous pouvez ajouter toutes sortes d’informations pertinentes. Ces logs sont intelligemment délimités par un caractère unique et se présentent de la façon suivante :

2016-05-28 18:35:31.164705|Crash_Report|Windows95|A terrible crash happened!|A crash was reported on Joe M's computer|LotusNotes,Outlook,InternetExplorer

Vous pouvez définir un parser de logs comme indiqué ci-dessous, afin de créer un événement à partir des données loguées dans votre flux d’événements Datadog :

import time
from datetime import datetime
...
def my_log_parser(logger, line):

    # Décomposer la ligne en champs
    date, report_type, system, title, message, extras = line.split('|')
    # Décomposer les extras en tags
    tags = extras.split(',')
    # Convertir la date ISO 8601 en timestamp Unix, en supposant que la chaîne timestamp
    # est dans le même fuseau horaire que la machine qui effectue son parsing.
    date = datetime.strptime(date, "%Y-%m-%d %H:%M:%S.%f")
    date = time.mktime(date.timetuple())
    logged_event = {
        'msg_title': title,
        'timestamp': date,
        'msg_text': message,
        'priority': 'normal',
        'event_type': report_type,
        'aggregation_key': system,
        'tags': tags,
        'alert_type': 'error'
    }
    return logged_event

Ensuite, modifiez votre fichier datadog.conf en ajoutant l’option dogstream comme suit :

dogstreams: /chemin/vers/monfichier.log:/chemin/vers/mylogparser.py:my_log_parser
# (Remarque : si vous utilisez Windows, remplacez chaque / par la séquence d'échappement \\)

Cette ligne de log spécifique parsée avec ce parser génère l’événement suivant dans Datadog :

Envoyer des paramètres supplémentaires à votre fonction de parsing personnalisée

Une fois votre parser personnalisé configuré pour envoyer une métrique ou des événements à votre plateforme, votre datadog.conf doit contenir une ligne comme celle-ci :

 dogstreams: /chemin/vers/log1:/chemin/vers/mon/parsers_module.py:custom_parser

Votre parser_module.py doit contenir une fonction définie comme :

def custom_parser(logger, line)

Vous pouvez changer la parité de votre fonction de façon à ce qu’elle accepte des paramètres supplémentaires, comme illustré dans cet exemple d’Agent.

Ainsi, si vous modifiez votre fichier de configuration comme suit :

dogstreams: /chemin/vers/log1:/chemin/vers/mon/parsers_module.py:custom_parser:customvar1:customvar2

Et votre fonction de parsing comme suit :

def custom_parser(logger, line, parser_state, *parser_args):

Vous obtenez un paramètre tuple dans parser_args, avec le format (<VARIABLE_CUSTOM_1>, <VARIABLE_CUSTOM_2>), prêt à être utilisé dans votre code à l’aide de parser_args[0] et parser_args1.

Remarque : le paramètre parser_state est facultatif, mais il doit figurer dans la signature de la fonction. Si vous avez un seul paramètre, vous devez utiliser parser_args1 pour le récupérer.

Par exemple, si vous utilisez le même parser que dans la documentation mais qu’au lieu d’extraire le nom de la métrique à partir du log, vous souhaitez le définir à l’aide de ce paramètre :

Le fichier de configuration contiendrait alors ce qui suit :

dogstreams: /Users/Documents/Parser/test.log:/Users/Documents/Parser/myparser.py:parse_web:logmetric

Dépannage

Personne n’étant à l’abri d’un bug, il est important de pouvoir visualiser le traceback de vos parsers de logs. Cela est possible si le niveau des logs de votre Agent est défini sur « DEBUG ». Le niveau de log de l’Agent peut être défini dans datadog.conf en supprimant la mise en commentaire de cette ligne et en la modifiant, puis en redémarrant l’Agent. Une fois ces modifications effectuées, le traceback associé aux erreurs dans votre parser de logs personnalisé se trouve dans le fichier collector.log. Il comprend généralement la chaîne « checks.collector(datadog.py:278) | Error while parsing line  » (voir le code de l’Agent dans lequel l’erreur est susceptible d’être générée).

Remarque : lorsque vous modifiez votre parser de logs personnalisé, vous devez redémarrer l’Agent pour appliquer vos modifications.

Si vous pensez que l’erreur n’est pas liée à la fonction de votre parser de logs personnalisé, n’hésitez pas à contacter l’assistance. Toutefois, commencez par définir le niveau de log sur « DEBUG » avant de lancer l’Agent quelques minutes en vous assurant que de nouveaux logs sont ajoutés à vos fichiers. Ensuite, exécutez la commande flare à partir de votre Agent. L’équipe d’assistance aura ainsi accès aux informations nécessaires pour dépanner efficacement le problème.