Sémantique des tags de span

Présentation

Les bibliothèques de tracing Datadog fournissent une prise en charge prête à l’emploi pour l’instrumentation d’un grand nombre de bibliothèques. Ces instrumentations génèrent des spans représentant les unités de travail logiques dans les systèmes distribués. Chaque span se compose de tags de span dont le but est de fournir des informations supplémentaires sur l’unité de travail en action dans le système. La convention de nommage décrit le nom et le contenu pouvant être utilisés dans les événements de span.

Convention de nommage des tags de span

Core

Les tags de span suivants constituent les concepts clés permettant de décrire l’instrumentation utilisée ainsi que le type d’opération exécutée :

NomTypeDescription
languagestringLe langage utilisé par le SDK du client pour générer la span. Il peut s’agir de l’une des valeurs suivantes : cpp, dotnet, go, jvm, javascript, php, python ou ruby.
envstringLa valeur de la variable d’environnement DD_ENV ou de la variable env définie par l’utilisateur pour le processus en cours d’exécution.
versionstringLa valeur de la variable d’environnement DD_VERSION ou de la variable version définie par l’utilisateur pour le processus en cours d’exécution.
span.kindstringLa chaîne représentant le type de l’unité de travail gérée par la span. Il peut s’agir de l’une des valeurs suivantes : server, client, producer, consumer ou internal.
Pour en savoir plus, consultez la documentation OpenTelemetry sur le SpanKind (en anglais).
componentstringLe nom de la bibliothèque ou de l’intégration qui a créé la span.

Communications réseau

Les tags de span suivants peuvent être utilisés pour décrire les unités de travail correspondant aux communications réseau :

NomTypeDescription
network.client.ipstringL’adresse IP du client à l’origine de la connexion entrante.
network.destination.ipstringL’adresse IP de destination de la connexion sortante.
network.host.ipstringL’adresse IP du host local.
network.client.portnumberLe port du client à l’origine de la connexion.
network.destination.portnumberLe numéro de port distant de la connexion sortante.
network.client.namestringLe hostname du client à l’origine de la connexion entrante.
network.destination.namestringLe hostname distant (ou équivalent) de destination de la connexion sortante.
network.host.namestringLe hostname local.
network.client.transportstringLe protocole de transport utilisé pour la connexion entrante.
network.destination.transportstringLe protocole de transport utilisé pour la connexion sortante.

Requêtes HTTP

Les tags de span suivants peuvent être utilisés pour décrire les spans de client et de serveur HTTP :

NomDescription
http.status_codeType : string
Le code de statut de la réponse HTTP.
http.urlType : string
L’URL de la requête HTTP, avec la chaîne de requête obfusquée. Pour en savoir plus sur l’obfuscation, consultez la documentation relative à la configuration de la sécurité des données.
http.versionType : string
La version HTTP utilisée pour la requête.
http.methodType : string
Le port du client à l’origine de la connexion.
http.routeType : string
La route correspondante (le modèle de chemin).
Exemple : /users/:userID
http.client_ipType : string
L’adresse IP du client d’origine derrière tous les proxies, si elle est disponible. Cette adresse est déterminée à partir des en-têtes tels que X-Forwarded-For.
http.useragentType : string
Le user-agent indiqué dans l’en-tête de la requête reçue.
http.request.content_lengthType : number
La taille en octets du corps de la charge utile de la requête.
http.response.content_lengthType : number
La taille en octets du corps de la charge utile de la réponse.
http.request.content_length_uncompressedType : number
La taille du corps de la charge utile de la requête sans compression après décodage du transport.
http.response.content_length_uncompressedType : number
La taille du corps de la charge utile de la réponse sans compression après décodage du transport.
http.request.headers.*Type : string
Les en-têtes HTTP de la requête. Par défaut, aucun en-tête n’est recueilli, mais vous pouvez utiliser la variable d’environnement DD_TRACE_HEADER_TAGS pour recueillir ceux qui vous intéressent.
Pour en savoir plus sur la collecte des en-têtes, consultez la configuration de la bibliothèque correspondante.
http.response.headers.*Type : string
Les en-têtes HTTP de la réponse. Par défaut, aucun en-tête n’est recueilli, mais vous pouvez utiliser la variable d’environnement DD_TRACE_HEADER_TAGS pour collecter ceux qui vous intéressent.
Pour en savoir plus sur la collecte des en-têtes, consultez la configuration de la bibliothèque correspondante.

Base de données

Les tags de span suivants peuvent être utilisés pour décrire les spans de base de données :

NomTypeDescription
db.systemstringL’identifiant du système de gestion de bases de données (solution SGBD utilisée).
db.connection_stringstringLa chaîne utilisée pour la connexion à la base de données.
db.userstringLe nom d’utilisateur utilisé pour accéder à la base de données.
db.instancestringLe nom de la base de données à laquelle la connexion est établie.
db.statementstringL’instruction de base de données en cours d’exécution.
db.operationstringLe nom de l’opération en cours d’exécution.
Exemples : SELECT, findAndModify ou HMSET
db.sql.tablenumberLe nom de la table principale à laquelle s’applique l’opération, y compris le nom de la base de données (le cas échéant).
db.row_countnumberLe nombre de lignes/résultats renvoyés par la requête ou l’opération.

Le préfixe db.<db.system> est appliqué aux attributs relatifs à des technologies de base de données spécifiques.

File d’attente de messages

Les tags de span suivants peuvent être utilisés pour décrire les spans correspondant aux systèmes de messagerie :

NomTypeDescription
messaging.systemstringL’identifiant du système de messagerie.
messaging.destinationstringLe nom de la destination du message.
messaging.destination_kindstringLe type de la destination du message.
messaging.protocolstringLe nom du protocole de transport.
messaging.protocol_versionstringLa version du protocole de transport.
messaging.urlstringLa chaîne de connexion au système de messagerie.
messaging.message_idstringLe nom de la table principale à laquelle s’applique l’opération, y compris le nom du système de messagerie (le cas échéant).
messaging.conversation_idstringLe nombre de lignes/résultats renvoyés par la requête ou l’opération.
messaging.message_payload_sizenumberLa taille en octets de la charge utile du message sans compression.
messaging.operationstringUne chaîne identifiant le type de consommation du message.
Exemples : send (un message est envoyé à un producteur), receive (un message est reçu par un consommateur) ou process (un message précédemment reçu est traité par un consommateur).
messaging.consumer_idstringL’identifiant du consommateur recevant un message.

Le préfixe messaging.<messaging.system> est appliqué aux attributs relatifs à des systèmes de messagerie spécifiques.

Appels de procédure à distance

Les tags de span suivants peuvent être utilisés pour décrire les spans correspondant à des appels de procédure à distance comme RMI ou gRPC :

NomTypeDescription
rpc.systemstringL’identifiant du système distant.
rpc.servicestringLe nom du service appelé.
rpc.methodstringLe nom de la méthode appelée.

Erreurs

Les tags de span suivants peuvent être utilisés pour décrire les erreurs associées aux spans :

NomTypeDescription
error.messagestringLe type ou la catégorie d’erreur (ou le code dans certains cas).
error.typestringUn message d’une ligne lisible et concis décrivant l’événement.
error.stackstringLa stack trace ou les informations complémentaires relatives à l’erreur.

Pour aller plus loin