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:
Name | Type | Description |
---|
language | string | The client SDK language used to generate the span. It can be one of the following: cpp , dotnet , go , jvm , javascript , php , python , ruby . |
env | string | The value of DD_ENV environment variable or user defined env for the running process. |
version | string | The value of DD_VERSION environment variable or user defined version for the running process. |
span.kind | string | The 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. |
component | string | The 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:
Name | Type | Description |
---|
network.client.ip | string | The IP address of the client that initiated the inbound connection. |
network.destination.ip | string | The IP address to where the outbound connection is being made. |
network.host.ip | string | The local host IP address. |
network.client.port | number | The port of the client that initiated the connection. |
network.destination.port | number | The remote port number of the outbound connection. |
network.client.name | string | The hostname of the client that initiated the inbound connection. |
network.destination.name | string | The remote hostname or similar to where the outbound connection is being made. |
network.host.name | string | The local hostname. |
network.client.transport | string | The transport protocol used to make the inbound connection. |
network.destination.transport | string | The 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:
Name | Description |
---|
http.status_code | Type: string The HTTP response status code. |
http.url | Type: string The URL of the HTTP request, including the obfuscated query string. For more information on obfuscation, see Configure Data Security. |
http.version | Type: string The version of HTTP used for the request. |
http.method | Type: string The port of the client that initiated the connection. |
http.route | Type: string The matched route (path template). Example: /users/:userID |
http.client_ip | Type: string The IP address of the original client behind all proxies, if known. Discovered from headers such as X-Forwarded-For . |
http.useragent | Type: string The user agent header received with the request. |
http.request.content_length | Type: number The size of the request payload body in bytes. |
http.response.content_length | Type: number The size of the response payload body in bytes. |
http.request.content_length_uncompressed | Type: number The size of the uncompressed request payload body after transport decoding. |
http.response.content_length_uncompressed | Type: 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:
Name | Type | Description |
---|
db.system | string | Identifier for the database management system (DBMS product being used). |
db.connection_string | string | The connection string used to connect to the database. |
db.user | string | The username that accessed the database |
db.instance | string | The name of the database being connected to. |
db.statement | string | The database statement being executed. |
db.operation | string | The name of the operation being executed. Examples: SELECT , findAndModify , HMSET |
db.sql.table | number | The name of the primary table that the operation is acting upon, including the database name (if applicable). |
db.row_count | number | The number of rows/results from the query or operation. |
Additional attributes for specific database technologies use the prefix db.<db.system>
.
Message queue
The following span tags can be used to describe spans corresponding to messaging systems:
Name | Type | Description |
---|
messaging.system | string | The identifier of the messaging system. |
messaging.destination | string | The message destination name. |
messaging.destination_kind | string | The kind of message destination. |
messaging.protocol | string | The name of the transport protocol. |
messaging.protocol_version | string | The version of the transport protocol. |
messaging.url | string | The connection string to the messaging system. |
messaging.message_id | string | A value used by the messaging system as an identifier for the message, represented as a string. |
messaging.conversation_id | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. |
messaging.message_payload_size | number | The size of the uncompressed message payload in bytes. |
messaging.operation | string | A 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_id | string | The identifier for the consumer receiving a message. |
Additional attributes for specific messaging systems 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:
Name | Type | Description |
---|
rpc.system | string | The identifier of the remote system. |
rpc.service | string | The name of the service being called. |
rpc.method | string | The name of the method being called. |
Errors
The following span tags can be used to describe errors associated with spans:
Name | Type | Description |
---|
error.type | string | The error type or kind (or code in some cases). |
error.message | string | A concise, human-readable, one-line message explaining the event. |
error.stack | string | The stack trace or the complementary information about the error. |
Further reading
Additional helpful documentation, links, and articles: