Overview
Span links are an OpenTelemetry concept and a part of the OpenTelemetry Tracing API. Datadog supports span links for:
Span links correlate one or more spans together that are causally related but don’t have a typical parent-child relationship. These links may correlate spans within the same trace or across different traces.
Span links help trace operations in distributed systems, where workflows often deviate from linear execution patterns. They are useful to trace the flow of operations in systems that execute requests in batches or process events asynchronously.
Datadog supports both forward and backward span links, allowing users to visualize and navigate span relationships across traces in both directions.
- Forward Links: A span can be linked to another span that occurs later in time, whether it belongs to the same trace or a different one. This enables you to navigate from earlier operations to subsequent ones across traces.
- Backward Links: Similarly, a span can be linked to a span that occurred earlier in time, either within the same trace or across different traces. This allows you to trace back from later operations to previous ones.
Common use cases
Span links are most applicable in fan-in scenarios, where multiple operations converge into a single span. The single span links back to multiple converging operations.
For example:
Scatter-Gather and Map-Reduce: Here, span links trace and correlate multiple parallel processes that converge into a single combined process. They connect the results of these parallel processes to their collective outcome.
Message Aggregation: In systems like Kafka Streams, span links connect each message in a group of messages to their aggregated result, showing how individual messages contribute to the final output.
Transactional Messaging: In scenarios where multiple messages are part of a single transaction, such as in message queues, span links trace the relationship between each message and the overarching transactional process.
Event Sourcing: Span links in event sourcing track how multiple change messages contribute to the current state of an entity.
Creating span links
If your application is instrumented with:
Minimum support
Note*: This section documents minimum support for generating span links with Datadog APM client libraries (with the OpenTelemetry API). Span links generated by the OpenTelemetry SDK are sent to Datadog through OTLP Ingest.
Agent v7.52.0 or greater is required to generate span links using Datadog tracing libraries. Support for span links was introduced in the following releases:
| Language | Minimum tracing library version |
|---|
| C++/Proxy | Not yet supported |
| Go | 1.61.0 |
| Java | 1.26.0 |
| .NET | 2.53.0 |
| Node | 5.3.0 |
| PHP | 0.97.0 |
| Python | 2.5.0 |
| Ruby | 2.0.0 |
Viewing span links
You can view span links from the Trace Explorer in Datadog.
Further reading
Additional helpful documentation, links, and articles:
