Attributs et alias

Attributs et alias

Présentation

La centralisation des logs issus de diverses technologies et applications a tendance à générer des dizaines voire des centaines d’attributs différents dans un environnement de Log Management. C’est notamment le cas lorsque de nombreuses équipes travaillent au sein d’un même environnement.

Par exemple, l’IP d’un client peut contenir divers attributs de logs : clientIP, client_ip_address, remote_address, client.ip, etc. Les attributs exec_time, request_latency ou encore request.time_elapsed peuvent désigner le délai d’exécution d’une requête.

Utilisez les attributs et les alias afin d’unifier votre environnement de logs.

Types d’attributs et alias

Les attributs déterminent les facettes des logs et les tags, qui servent à filtrer le Log Explorer et à y effectuer des recherches.

  • Les attributs réservés sont automatiquement ingérés.

  • Les attributs standard constituent la base de la convention de nommage de votre organisation. Un ensemble d’attributs standard par défaut est disponible dans l’app. Néanmoins, cette liste peut être personnalisée afin de créer une convention de nommage pour votre équipe.

  • Vous pouvez utiliser des alias après avoir implémenté une convention de nommage avec des attributs standard, ou encore pour créer une facette standard unique provenant de plusieurs sources de logs. Il est par exemple possible de surveiller les clients qui souffrent le plus de latence dans une infrastructure hybride basée sur Apache et Amazon Cloud Front à l’aide de la facette standard Network Client IP et de la duration standard. Les alias permettent d’implémenter une convention de nommage sans avoir à modifier la pile technique d’une équipe.

Attributs réservés

Vous trouverez ci-dessous la liste des attributs réservés qui sont automatiquement ingérés avec les logs :

Remarque : si vous recueillez également des traces ou des métriques, nous vous conseillons de configurer le tagging de service unifié. Cette configuration lie entre elles les données de télémétrie de Datadog à l’aide de trois tags standard : env, service et version. Consultez la documentation dédiée pour en savoir plus.

AttributDescription
hostLe nom du host d’origine, tel que défini dans les métriques. Nous récupérons automatiquement les tags de host correspondants à partir du host associé dans Datadog. Nous les appliquons ensuite à vos logs. L’Agent définit automatiquement cette valeur.
sourceCet attribut correspond au nom de l’intégration, à savoir la technologie à l’origine du log. Lorsqu’il a pour valeur le nom d’une intégration, Datadog installe automatiquement les parsers et les facettes correspondants. Par exemple : nginx, postgresql, etc.
statusCet attribut correspond au niveau ou à la gravité d’un log. Il est utilisé pour définir des patterns et possède une disposition dédiée dans l’interface de log Datadog.
serviceLe nom de l’application ou du service qui génère les événements de log. Il est utilisé pour passer des logs à l’APM. Assurez-vous donc de définir la même valeur lorsque vous utilisez les deux produits.
trace_idCet attribut correspond à l’ID de la trace. Il sert à mettre en corrélation votre log avec sa trace.
messagePar défaut, Datadog ingère la valeur de l’attribut message en la considérant comme le corps de l’entrée de log. Cette valeur est alors mise en avant et affichée sur la page Live Tail. Elle est également indexée afin de pouvoir effectuer des recherches en texte intégral.

Attributs standard

Les intégrations de logs reposent nativement sur un ensemble d’attributs standard fourni par défaut.

Les administrateurs de votre organisation peuvent ajuster la liste des attributs standard :

Le tableau des attributs standard est doté d’un ensemble d'attributs standard prédéfinis. Vous pouvez ajouter vos propres attributs à cette liste et modifier ou supprimer des attributs standard existants :

Un attribut standard est défini par les éléments suivants :

  • Path : le chemin de l’attribut transformé en attribut standard, tel qu’il apparaît dans votre fichier JSON (p. ex., network.client.ip).
  • Type (string, integer, double, boolean) : le type de l’attribut utilisé pour convertir les éléments de la liste de remappage.
  • Aliasing list : la liste des attributs pour lesquels un alias est créé, séparés par des virgules.
  • Description : la description lisible de l’attribut.

Le volet des attributs standard s’affiche lorsque vous ajoutez un nouvel attribut standard ou que vous modifiez un attribut existant :

Liste des attributs standard par défaut

La liste des attributs standard par défaut comporte plusieurs catégories fonctionnelles :

Réseau

Les attributs suivants sont liés aux données de communication réseau. Tous les champs et toutes les métriques sont précédés par network.

Nom completTypeDescription
network.client.ipstringL’adresse IP du client à l’origine de la connexion TCP.
network.destination.ipstringL’adresse IP à laquelle le client est connecté.
network.client.portnumberLe port du client à l’origine de la connexion.
network.destination.portnumberLe port TCP auquel le client s’est connecté.
network.bytes_readnumberLe nombre total d’octets transmis depuis le client vers le serveur lorsque le log est envoyé.
network.bytes_writtennumberLe nombre total d’octets transmis depuis le serveur vers le client lorsque le log est envoyé.

Des intégrations comme Apache, Varnish, AWS ELB, Nginx ou encore HAProxy reposent sur ces attributs.

Géolocalisation

Les attributs suivants sont liés à la géolocalisation des adresses IP utilisées dans les communications réseau. Tous les champs sont précédés par network.client.geoip ou network.destination.geoip.

Nom completTypeDescription
network.client.geoip.country.namestringLe nom du pays.
network.client.geoip.country.iso_codestringCode ISO du pays (par exemple : US pour les États-Unis, FR pour la France)
network.client.geoip.continent.codestringCode ISO du continent (EU, AS, NA, AF, AN, SA, OC)
network.client.geoip.continent.namestringNom du continent (Europe, Australia, North America, Africa, Antartica, South America, Oceania)
network.client.geoip.subdivision.namestringNom du premier niveau de division du pays (par exemple : California aux États-Unis ou le département de la Sarthe en France)
network.client.geoip.subdivision.iso_codestringCode ISO du premier niveau de division du pays (par exemple : CA aux États-Unis ou le département SA en France)
network.client.geoip.city.nameStringLe nom de la ville (par exemple : Paris, New York)

Requêtes HTTP

Ces attributs sont liés aux données couramment utilisées dans les accès et requêtes HTTP. Tous les attributs sont précédés par http.

Des intégrations comme Apache, Rails, AWS CloudFront ou encore des serveurs d’application Web reposent sur ces attributs.

Attributs courants
Nom completTypeDescription
http.urlstringL’URL de la requête HTTP.
http.status_codenumberLe code de statut de la réponse HTTP.
http.methodstringIndique l’action à effectuer pour une ressource donnée.
http.refererstringLe champ d’en-tête HTTP qui identifie l’adresse de la page Web liée à la ressource demandée.
http.request_idstringL’ID de la requête HTTP.
http.useragentstringLe user-agent tel qu’il est envoyé (format brut). Consultez les informations ci-dessous pour en savoir plus.
http.versionstringLa version HTTP utilisée pour la requête.
Attributs liés aux détails de l’URL

Ces attributs fournissent des informations sur les éléments parsés de l’URL HTTP. Ils sont généralement générés à l’aide du parser d’URL. Tous les attributs sont précédés par http.url_details.

Nom completTypeDescription
http.url_details.hoststringLa partie de l’URL correspondant au host HTTP.
http.url_details.portnumberLa partie de l’URL correspondant au port HTTP.
http.url_details.pathstringLa partie de l’URL correspondant au chemin HTTP.
http.url_details.queryStringobjectLes parties de l’URL correspondant à la chaîne de requête HTTP, décomposées en attributs key/value de paramètres de requête.
http.url_details.schemestringLe nom du protocole de l’URL (HTTP ou HTTPS).
Attributs user-agent

Ces attributs fournissent des informations sur la signification des attributs user-agent. Ils sont généralement générés à l’aide du parser de user-agent. Tous les attributs sont précédés par http.useragent_details.

Nom completTypeDescription
http.useragent_details.os.familystringLa famille du système d’exploitation indiquée par le user-agent.
http.useragent_details.browser.familystringLa famille de navigateurs indiquée par le user-agent.
http.useragent_details.device.familystringLa famille d’appareils indiquée par le user-agent.

Code source

Ces attributs sont liés aux données utilisées lorsqu’un log ou une erreur est généré(e) via un logger dans une application personnalisée. Tous les attributs sont précédés par logger ou error.

Nom completTypeDescription
logger.namestringLe nom du logger.
logger.thread_namestringLe nom du thread actuel lorsque le log est envoyé.
logger.method_namestringLe nom de la méthode de la classe.
logger.versionstringLa version du logger.
error.kindstringLe type ou la catégorie d’erreur (ou le code dans certains cas).
error.messagestringUn message d’une ligne lisible et concis décrivant l’événement.
error.stackstringLa stack trace ou les informations complémentaires relatives à l’erreur.

Des intégrations comme Java, NodeJs, .NET, Golang ou encore Python reposent sur ces attributs.

Base de données

Les attributs liés à une base de données sont précédés par db.

Nom completTypeDescription
db.instancestringNom de l’instance de la base de données. Par exemple, dans Java, pour jdbc.url="jdbc:mysql://127.0.0.1:3306/customers", le nom de l’instance est customers.
db.statementstringUne déclaration de base de données pour le type de base de données fourni. Par exemple, "SELECT * FROM wuser_table"; pour mySQL et "SET mykey 'WuValue'" pour Redis.
db.operationstringL’opération effectuée (« query », « update », « delete », etc.).
db.userstringL’utilisateur à l’origine de l’opération.

Des intégrations comme Cassandra, MySQL, RDS ou encore Elasticsearch reposent sur ces attributs.

Performances

Attributs des métriques de performance.

Nom completTypeDescription
durationnumberToute durée en nanosecondes : le délai de réponse HTTP, le délai d’interrogation d’une base de données, la latence, etc.

Étant donné que cet attribut est affiché et utilisé comme mesure par défaut pour la recherche de traces, nous vous conseillons de remapper toutes les durées de vos logs sur cet attribut.

Attributs associés à l’utilisateur

Tous les attributs et toutes les mesures sont précédés par usr.

Nom completTypeDescription
usr.idstringL’identifiant de l’utilisateur.
usr.namestringLe nom courant de l’utilisateur.
usr.emailstringL’adresse e-mail de l’utilisateur.

Syslog shippers et log shippers

Ces attributs sont liés aux données ajoutées par un Agent syslog-shipper ou log-shipper. Tous les champs et toutes les métriques sont précédés par syslog.

Nom completTypeDescription
syslog.hostnamestringLe hostname.
syslog.appnamestringLe nom de l’application. Généralement remappé vers l’attribut réservé service.
syslog.severitynumberLa gravité du log. Généralement remappée vers l’attribut réservé status.
syslog.timestampstringLe timestamp du log. Généralement remappé vers l’attribut réservé date.
syslog.envstringLe nom de l’environnement d’où provient la source des logs.

Des intégrations comme Rsyslog, NxLog, Syslog-ng, Fluentd ou encore Logstash reposent sur ces attributs.

DNS

Tous les attributs et toutes les mesures sont précédés par dns.

Nom completTypeDescription
dns.idstringL’identificateur de la question DNS.
dns.question.namestringLe nom de domaine interrogé.
dns.question.typestringUn code de deux octets spécifiant le type de question DNS.
dns.question.classstringLa classe recherchée par la question DNS (p. ex. IN lorsque vous utilisez Internet).
dns.question.sizenumberLa taille de la question DNS en octets.
dns.answer.namestringL’adresse IP avec laquelle le DNS répond.
dns.answer.typestringUn code de deux octets spécifiant le type de réponse DNS.
dns.answer.classstringLa classe correspondant à la réponse du DNS.
dns.answer.sizenumberLa taille de la réponse du DNS en octets.
dns.flags.rcodestringLe code de réponse du DNS.

Événements

Tous les attributs sont précédés par evt.

Nom completTypeDescription
evt.namestringLe nom partagé entre les événements générés par une même activité (p. ex., authentification).
evt.outcomestringLe résultat de l’événement (p. ex., success, failure).

Alias

La création d’un alias pour un attribut source mappé avec un attribut cible permet aux logs de transmettre à la fois l’attribut source et cible.

Les utilisateurs peuvent interagir avec l’attribut à facette avec alias (l’attribut source) ou standard (l’attribut cible). Les utilisateurs sont cependant invités à utiliser la facette standard plutôt que celle avec un alias. Cela les incite à respecter la convention de nommage et réduit la création de ressources (comme des vues enregistrées ou des dashboards) à partir de contenu atypique.

Voici quelques informations supplémentaires concernant l’utilisation d’alias :

  • L’application d’alias s’effectue après le traitement des logs par les pipelines. Tout attribut extrait ou traité peut être utilisé comme source pour un alias.
  • Datadog applique le type d’attribut avec un alias. Si ce n’est pas possible, l’alias n’est pas créé.
  • Lorsqu’un log transmet déjà l’attribut cible, l’alias écrase la valeur.
  • Lorsque plusieurs attributs possèdent un alias vers un attribut standard, si le log transmet plusieurs de ces attributs source, un alias n’est appliqué qu’à un seul des attributs source.
  • Il est uniquement possible de modifier ou d’ajouter des informations pour un attribut standard d’un log récemment ingéré.
  • Il est impossible d’appliquer un alias à un attribut standard.
  • Un alias peut uniquement être créé vers un attribut standard.
  • Pour respecter la structure JSON des logs, il n’est pas possible qu’un attribut standard soit l’enfant d’un autre (par exemple, user et user.name ne peuvent pas être tous les deux des attributs standard).

Consultez la documentation à ce sujet pour en savoir plus.

Pour aller plus loin