Span Tag 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. Naming conventions describe the name and content that can be used in span events.

To find a comprehensive list of all span tags, reserved attributes, and naming conventions, see Default Standard Attributes.

Span tag naming conventions

There are a variety of span tags to describe work happening in the system. For example, there are span tags to describe the following domains:

  • Reserved: Attributes that are always present on all spans.
  • Core: Instrumentation used and the kind of operation.
  • Network communications: Work units corresponding to network communications.
  • HTTP requests: HTTP client and server spans.
  • Database: Database spans.
  • Message queue: Messaging system spans.
  • Remote procedure calls: Spans corresponding to remote procedure calls such as RMI or gRPC.
  • Errors: Errors associated with spans.

For more information, see Default Standard Attributes.

Span tags and span attributes

Span tags and span attributes are similar but distinct concepts:

Span tags

Span tags are the context around the span. Some examples include:

  • Host tags: hostname, availability-zone, cluster-name
  • Container tags: container_name, kube_deployment, pod_name

Tags are usually enriched from other data sources like tags sourced from host, container, or service catalog. These tags are added to the span to describe the context. For example, tags might describe the properties of the host and the container the span is coming from, or the properties of the services the span is emitted from.

To find span tags in Datadog, go to the Infrastructure tab in the Trace side panel:

Span tags on Infrastructure tab.

Span attributes

Span attributes are the content of the span. Some example include:

  • http.url
  • http.status_code
  • error.message

To query span attributes, use the the @ character followed by the attribute name in the search box. For example, @http.url.

To find span attributes in Datadog, go to the Info tab in the Trace side panel:

Span attributes on Info tab.

Further reading