Span Tags Semantics

Overview

Datadog tracing libraries provide out-of-the-box support for instrumenting a variety of libraries. These instrumentations generate spans to represent logical units of work in distributed systems. Each span consists of span tags to provide additional information on the unit of work happening in the system. The naming convention describes the name and content that can be used in span events.

Span tag naming convention

Core

The following span tags are the core concepts for describing the instrumentation used and the kind of operation performed:

NameTypeDescription
languagestringThe client SDK language used to generate the span. It can be one of the following: cpp, dotnet, go, jvm, javascript, php, python, ruby.
envstringThe value of DD_ENV environment variable or user defined env for the running process.
versionstringThe value of DD_VERSION environment variable or user defined version for the running process.
span.kindstringThe string representing the type of work unit handled by the span. It can be one of the following: server, client, producer, consumer or internal.
More information in the OpenTelemetry SpanKind documentation.
componentstringThe name of the library/integration that created the span.

Network communications

The following span tags can be used to describe work units corresponding to network communications:

NameTypeDescription
network.client.ipstringThe IP address of the client that initiated the inbound connection.
network.destination.ipstringThe IP address to where the outbound connection is being made.
network.host.ipstringThe local host IP address.
network.client.portnumberThe port of the client that initiated the connection.
network.destination.portnumberThe remote port number of the outbound connection.
network.client.namestringThe hostname of the client that initiated the inbound connection.
network.destination.namestringThe remote hostname or similar to where the outbound connection is being made.
network.host.namestringThe local hostname.
network.client.transportstringThe transport protocol used to make the inbound connection.
network.destination.transportstringThe transport protocol used to make the outbound connection.

HTTP requests

The following span tags can be used to describe the HTTP client and server spans:

NameDescription
http.status_codeType: string
The HTTP response status code.
http.urlType: string
The URL of the HTTP request, including the obfuscated query string. For more information on obfuscation, see Configure Data Security.
http.versionType: string
The version of HTTP used for the request.
http.methodType: string
The port of the client that initiated the connection.
http.routeType: string
The matched route (path template).
Example: /users/:userID
http.client_ipType: string
The IP address of the original client behind all proxies, if known. Discovered from headers such as X-Forwarded-For.
http.useragentType: string
The user agent header received with the request.
http.request.content_lengthType: number
The size of the request payload body in bytes.
http.response.content_lengthType: number
The size of the request payload body in bytes.
http.request.content_length_uncompressedType: number
The size of the uncompressed request payload body after transport decoding.
http.response.content_length_uncompressedType: number
The size of the uncompressed response payload body after transport decoding.
http.request.headers.*Type: string
The request HTTP headers. None are collected by default, but can be optionally configured with DD_TRACE_HEADER_TAGS.
To learn more about how to collect headers, see the corresponding Library configuration.
http.response.headers.*Type: string
The response HTTP headers. None are collected by default, but can be optionally configured with DD_TRACE_HEADER_TAGS.
To learn more about how to collect headers, see the corresponding Library configuration.

Database

The following span tags can be used to describe database spans:

NameTypeDescription
db.systemstringIdentifier for the database management system (DBMS product being used).
db.connection_stringstringThe connection string used to connect to the database.
db.userstringThe username that accessed the database
db.instancestringThe name of the database being connected to.
db.statementstringThe database statement being executed.
db.operationstringThe name of the operation being executed.
Examples: SELECT, findAndModify, HMSET
db.sql.tablenumberThe name of the primary table that the operation is acting upon, including the database name (if applicable).
db.row_countnumberThe number of rows/results from the query or operation.

Additional attributes for specific database technologies will use the prefix db.<db.system>.

Message Queue

The following span tags can be used to describe spans corresponding to messaging systems:

NameTypeDescription
messaging.systemstringThe identifier of the messaging system.
messaging.destinationstringThe message destination name.
messaging.destination_kindstringThe kind of message destination.
messaging.protocolstringThe name of the transport protocol.
messaging.protocol_versionstringThe version of the transport protocol.
messaging.urlstringThe connection string to the messaging system.
messaging.message_idstringThe name of the primary table that the operation is acting upon, including the database name (if applicable).
messaging.conversation_idstringThe number of rows/results from the query or operation.
messaging.message_payload_sizenumberThe size of the uncompressed message payload in bytes.
messaging.operationstringA string identifying the kind of message consumption.
Examples: send (a message sent to a producer), receive (a message is received by a consumer), or process (a message previously received is processed by a consumer).
messaging.consumer_idstringThe identifier for the consumer receiving a message.

Additional attributes for specific database technologies will use the prefix messaging.<messaging.system>.

Remote procedure calls

The following span tags can be used to describe spans corresponding to remote procedure calls such as RMI or gRPC:

NameTypeDescription
rpc.systemstringThe identifier of the remote system.
rpc.servicestringThe name of the service being called.
rpc.methodstringThe name of the method being called.

Errors

The following span tags can be used to describe errors associated with spans:

NameTypeDescription
error.messagestringThe error type or kind (or code in some cases).
error.typestringA concise, human-readable, one-line message explaining the event.
error.stackstringThe stack trace or the complementary information about the error.

Further reading