Overview

Span links are an OpenTelemetry concept and a part of the OpenTelemetry Tracing API. Datadog supports span links for:

• Applications instrumented with OpenTelemetry SDKs.
• Applications instrumented with Datadog client libraries using the OpenTelemetry API.

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.

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:

• The OpenTelemetry SDK, follow the OpenTelemetry manual instrumentation documentation for your language. For example, Create spans with links for Java.
• The PHP Datadog library, follow the Adding span links examples.

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:

Viewing span links

You can view span links from the Trace Explorer in Datadog.

Further reading

Additional helpful documentation, links, and articles:

OpenTelemetry Span LinksDOCUMENTATION Custom Instrumentation with the OpenTelemetry APIDOCUMENTATION Custom Instrumentation with Datadog LibrariesDOCUMENTATION