Nouvelles annonces sur les technologies sans serveur et réseau ainsi que sur le RUM (Real-User Monitoring) dévoilées à la conférence Dash ! Nouvelles annonces dévoilées à la conférence Dash !

Attributs standards

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 nombreux utilisateurs (chacun ayant ses propres habitudes) travaillent au sein de différentes équipes dans un même environnement.

Cette vaste quantité d’attributs peut poser problème. Par exemple, une adresse IP client peut avoir les attributs suivants dans vos logs : clientIP, client_ip_address, remote_address, client.ip, etc.

Dans ce contexte, le nombre d’attributs créés ou fournis peut prêter à confusion et rendre difficile la configuration ou la compréhension de l’environnement. L’identification des attributs correspondant aux logs pertinents peut également être fastidieuse, empêchant la mise en corrélation efficace d’un proxy Web avec des logs d’application Web (par exemple). Même si chaque technologie définit ses attributs de log respectifs d’une façon qui lui est propre, la signification d’une URL, d’une IP client ou d’une durée est universelle.

Les attributs standards sont conçus pour permettre à votre organisation de définir sa propre convention de nommage et de la faire adopter par un maximum d’utilisateurs et d’équipes fonctionnelles. Il convient de définir un sous-ensemble d’attributs qui bénéficiera des sémantiques partagées que tout le monde accepte d’utiliser.

Configurer des attributs standards

Les intégrations de logs reposent de façon native sur les attributs fournis par défaut, mais votre organisation peut choisir de compléter ou de modifier cette liste. Le tableau des attributs standards ainsi que les pipelines et les autres fonctions d’admission des logs (génération de métriques, archives, filtres d’exclusion, etc.) sont disponibles dans les pages de configuration des logs.

Pour appliquer ces attributs standards, les administrateurs ont la possibilité de copier un ensemble d’attributs non standards existant dans un ensemble d’attributs standards. De cette façon, il est possible de rendre conformes les sources de logs qui ne le sont pas, sans qu’aucune des informations existantes ne soit perdue.

Attributs standards dans le Log Explorer

Généralement, durant une période de transition, les attributs standards peuvent coexister avec leur version non standard dans votre organisation. Pour aider vos utilisateurs à sélectionner les attributs standards dans ce contexte, ces derniers sont identifiés comme tels dans le Log Explorer (par exemple dans la liste des facettes ainsi que dans les sélecteurs de mesure ou de groupe dans la section Analytics).

Si vous êtes un administrateur ou le responsable de la convention de nommage dans votre organisation, profitez de cette période de transition pour en discuter avec les autres utilisateurs et les inviter à utiliser les attributs standards.

Liste des attributs standards

La tableau des attributs standards propose un ensemble d’attributs standards prédéfinis. Vous pouvez ajouter vos propres attributs à cette liste et modifier ou supprimer des attributs standards existants :

Ajouter ou modifier des attributs standards

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

  • Path : le chemin des attributs standards, 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.
  • Description : la description lisible de l’attribut.
  • Remapping list : la liste des attributs non conformes qui doivent être remappés vers leur version standard, séparés par des virgules.

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

Tous les éléments des attributs standards peuvent être renseignés ou mis à jour.

Remarque : il est uniquement possible de mettre à jour ou d’ajouter des informations pour un attribut standard d’un log récemment ingéré.

Comportement de remappage des attributs standards

Une fois les logs traités dans les pipelines, la liste complète des attributs standards est appliquée à chaque log. Pour chaque entrée du tableau des attributs standards, si un attribut du log actuel correspond à un attribut de la liste de remappage, les opérations suivantes se produisent :

  • Le premier attribut qui correspond à la liste fournie est remappé, et sa valeur est remplacée par la nouvelle si celle-ci existe déjà.
  • Datadog applique le type d’attribut remappé. Si ce n’est pas possible, l’attribut est ignoré et la prochaine correspondance de la liste est utilisée.
  • L’attribut d’origine est conservé dans le log.

Remarque importante : par défaut, le type d’un attribut standard existant reste inchangé si la liste de remappage est vide. Ajoutez l’attribut standard à sa propre liste de remappage pour modifier son type.

Validation

Pour ajouter ou mettre à jour un attribut standard, suivez les règles suivantes :

  • Un attribut standard ne peut pas être ajouté dans la liste de remappage d’un autre attribut standard.
  • Un attribut personnalisé peut être remappé vers un seul attribut standard.
  • Pour respecter la structure JSON des logs, un attribut standard ne peut pas être l’enfant d’un autre (par exemple, user et user.name ne peuvent pas être tous les deux des attributs standards).

Liste des attributs standards par défaut

La liste des attributs standards par défaut est séparée en sept domaines fonctionnels :

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.namestringNom 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 obtenir plus d’informations.

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 du host HTTP de l’URL.
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 chaîne de requête HTTP de l’URL décomposées en attributs key/value des 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.
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 trace de pile 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.

Les intégrations Cassandra, MySQL, RDS, Elasticsearch, etc. 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 d’y faire appel ou tout du moins de configurer un remappage vers celui-ci.

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 sévérité 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.

Les intégrations Rsyslog, NxLog, Syslog-ng, Fluentd, Logstash, etc. reposent sur ces attributs.

Pour aller plus loin