Span Links Beta Documentation

content/en/tracing/trace_collection/custom_instrumentation/java.md

@@ -250,6 +250,25 @@ class SomeClass {
     }
 }
 ```
+### Adding span links (Beta)
+
+<div class="alert alert-info">Support for span links is in beta and requires the <a href="https://github.com/DataDog/dd-trace-java/releases/tag/v1.24.1">Java tracer v.1.24.1+</a></div>
+
+Span links associate one or more spans together that don't have a typical parent-child relationship. They may associate spans within the same trace or spans across different traces.
+
+Span links help trace operations in distributed systems, where workflows often deviate from linear execution patterns. Additionally, span links are useful to trace the flow of operations in systems that execute requests in batches or process events asynchronously.
+
+To add a link span from another span:
+
+```java
+span.addLink(Link.fromSpanContext(otherSpanData));
+```
+
+To add a link span from distributed headers:
+```java
+SpanContext remoteSpanContext = extractContextFromHeaders(distributedTracingHeaders);
+span.addLink(Link.fromSpanContext(remoteSpanContext));
+```
 
 ### Extending tracers
 

content/en/tracing/trace_collection/custom_instrumentation/php.md

@@ -417,6 +417,24 @@ function doRiskyThing() {
 {{% /tab %}}
 {{< /tabs >}}
 
+## Adding span links (Beta)
+
+Span links associate one or more spans together that don't have a typical parent-child relationship. They may associate spans within the same trace or spans across different traces.
+
+Span links help trace operations in distributed systems, where workflows often deviate from linear execution patterns. Additionally, span links are useful to trace the flow of operations in systems that execute requests in batches or process events asynchronously.
+
+To add a link span from another span:
+
+```php
+$span->links[] = $otherSpanData->getLink(); 
+```
+
+To add a link span from distributed headers:
+```php
+$span->links[] = SpanLink::fromHeaders($distributedTracingHeaders);
+```
+
+
 ## Context propagation for distributed traces
 
 You can configure the propagation of context for distributed traces by injecting and extracting headers. Read [Trace Context Propagation][9] for information.

content/en/tracing/trace_explorer/trace_view.md

@@ -110,6 +110,30 @@ Click **View in ASM** to investigate further using [Datadog Application Security
 {{< img src="tracing/visualization/trace/trace_security.png" alt="Trace Attack Attempts" style="width:90%;">}}
 
 [1]: /security/application_security/how-appsec-works/
+{{% /tab %}}
+{{% tab "Span Links (Beta)" %}}
+
+<div class="alert alert-info"><strong>Beta</strong>: Span link are automatically supported if you use the <a href="https://docs.datadoghq.com/opentelemetry/otel_collector_datadog_exporter/?tab=onahost">OpenTelemetry Collector Datadog Exporter</a>, <a href="https://github.com/DataDog/dd-trace-php/releases/tag/0.87.2">PHP tracer v0.87.2+</a>, or <a href="https://github.com/DataDog/dd-trace-java/releases/tag/v1.24.1">Java tracer v.1.24.1+</a>.</div>
+
+Span links associate one or more spans together that don't have a typical parent-child relationship. They may associate spans within the same trace or spans across different traces.
+
+Span links help trace operations in distributed systems, where workflows often deviate from linear execution patterns. Additionally, span links are useful to trace the flow of operations in systems that execute requests in batches or process events asynchronously.
+
+Click on a span in the flame graph to display spans connected with span links.
+
+{{< img src="tracing/span_links/span_links_tab.png" alt="Span Links tab" style="width:90%;">}}
+
+If you see a message that says **Linked spans were not ingested**, make sure the linked spans are part of a [retention filter][2].
+
+To add custom instrumentation for span links, read the Datadog libraries documentation for your application's language:
+* [PHP][3]
+* [Java][4]
+
+[1]: /tracing/trace_collection/custom_instrumentation/
+[2]: /tracing/trace_pipeline/trace_retention/
+[3]: /tracing/trace_collection/custom_instrumentation/php
+[4]: /tracing/trace_collection/custom_instrumentation/java
+
 {{% /tab %}}
 {{< /tabs >}}