Span Links Beta Documentation (#20717)

* Add Span Links (Beta) tab to Trace Explorer docs.

* Add sections to custom instrumentation for PHP and Java.

* Update code snippets and trace view screenshot.

* Missing period.

* Fix code snippets per Alexandre

* Remove Java from DD lib custom instrumentation. Note in OTel instrumentation instead.

* Change OTel context propagation support (unrelated to span links).

* Make link to trace explorer more precise. Remove from Java.

* Add new Span Links page to Sending Traces to Datadog.

* Reorganize and clean up Span Links page.

* Redo Trace View section now that we have a full span links page.

* Apply feedback from review.

* Adjust headings.

* Remove fan-out use cases.

config/_default/menus/menus.en.yaml

@@ -1790,6 +1790,11 @@ main:
     parent: tracing_trace_collection
     identifier: tracing_naming_convention
     weight: 111
+  - name: Span Links
+    url: tracing/trace_collection/span_links
+    parent: tracing_trace_collection
+    identifier: tracing_span_links
+    weight: 112
   - name: APM Metrics Collection
     url: tracing/metrics/
     parent: tracing

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

@@ -422,6 +422,45 @@ function doRiskyThing() {
 {{% /tab %}}
 {{< /tabs >}}
 
+## 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-php/releases/tag/0.87.2">PHP tracer v0.87.2+</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 span link from an existing span:
+
+```php
+$spanA = \DDTrace\start_trace_span();
+$spanA->name = 'spanA';
+\DDTrace\close_span();
+
+$spanB = \DDTrace\start_trace_span();
+$spanB->name = 'spanB';
+// Link spanB to spanA
+$spanB->links[] = $spanA->getLink();
+\DDTrace\close_span();
+```
+
+To link a span using distributed tracing headers:
+
+```php
+$spanA = \DDTrace\start_trace_span();
+$spanA->name = 'spanA';
+$distributedTracingHeaders = \DDTrace\generate_distributed_tracing_headers();
+\DDTrace\close_span();
+
+$spanB = \DDTrace\start_trace_span();
+$spanB->name = 'spanB';
+// Link spanB to spanA using distributed tracing headers
+$spanB->links[] = \DDTrace\SpanLink::fromHeaders($distributedTracingHeaders);
+\DDTrace\close_span();
+```
+
+You can view span links from the [Trace View][10] in APM.
+
 ## 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.
@@ -740,3 +779,4 @@ While this [has been deprecated][7] if you are using PHP 7.x, you still may use
 [7]: https://laravel-news.com/laravel-5-6-removes-artisan-optimize
 [8]: /tracing/trace_collection/opentracing/php#opentracing
 [9]: /tracing/trace_collection/trace_context_propagation/php
+[10]: /tracing/trace_explorer/trace_view?tab=spanlinksbeta#more-information

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

@@ -31,6 +31,7 @@ The following OpenTelemetry features implemented in the Datadog library as noted
 | [Span Exporters][4]                               | Unsupported                                                                                 |
 | Trace/span [ID generators][5]                     | ID generation is performed by the tracing library, with support for [128-bit trace IDs][6]. |
 | [Metrics][7], [Baggage][8] and [Context][9] API   | Unsupported                                                                                 |
+| [Span links ][14] (Beta)                          | Requires `dd-trace-java` version 1.24.0 or greater.                                         |
 
 ## Configuring OpenTelemetry to use the Datadog tracing library
 
@@ -146,3 +147,5 @@ public void myMethod(@SpanAttribute("parameter1") String parameter1,
 [10]: https://opentelemetry.io/docs/instrumentation/java/manual/
 [11]: /tracing/trace_collection/dd_libraries/java/?tab=springboot#add-the-java-tracer-to-the-jvm
 [12]: /tracing/trace_collection/single-step-apm/
+[13]: /tracing/trace_collection/single-step-apm/
+[14]: https://opentelemetry.io/docs/instrumentation/java/manual/#create-spans-with-links

content/en/tracing/trace_collection/span_links/_index.md

@@ -0,0 +1,66 @@
+---
+title: Span Links
+kind: documentation
+further_reading:
+    - link: 'https://opentelemetry.io/docs/concepts/signals/traces/#span-links'
+      tag: 'Documentation'
+      text: 'OpenTelemetry Span Links'
+    - link: '/tracing/trace_collection/otel_instrumentation/'
+      tag: 'Documentation'
+      text: 'Custom Instrumentation with the OpenTelemetry API'
+    - link: '/tracing/trace_collection/custom_instrumentation/'
+      tag: 'Documentation'
+      text: 'Custom Instrumentation with Datadog Libraries'
+---
+
+<div class="alert alert-info">Span link support is in beta.</a></div>
+
+## Overview
+
+Span links are an [OpenTelemetry concept][5] and a part of the [OpenTelemetry Tracing API][2]. Datadog supports span links for:
+
+- Applications instrumented with [OpenTelemetry SDKs][6].
+- Applications instrumented with Datadog client libraries using the OpenTelemetry API.  
+  **Note**: This beta release only supports the [PHP client library][1].
+
+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][3].
+- The PHP Datadog library, follow the [Adding span links][1] examples.
+
+## Viewing span links
+
+You can view span links from the [Trace Explorer][4] in Datadog.
+
+## Further reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: /tracing/trace_collection/custom_instrumentation/php/#adding-span-links-beta
+[2]: https://opentelemetry.io/docs/specs/otel/trace/api/#link
+[3]: https://opentelemetry.io/docs/instrumentation/java/manual/#create-spans-with-links
+[4]: /tracing/trace_explorer/trace_view/?tab=spanlinksbeta#more-information
+[5]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links
+[6]: https://opentelemetry.io/docs/specs/otel/trace/sdk/
+
+

content/en/tracing/trace_explorer/trace_view.md

@@ -110,6 +110,26 @@ 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">Span link support is in beta.</div>
+
+[Span links][4] correlate one or more spans together that are causally related but don't have a typical parent-child relationship.
+
+Click 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%;">}}
+
+**Note**: Span links only display when the corresponding spans are ingested and indexed, for example, with a [retention filter][1].
+
+To learn more about span links and how to add them with custom instrumentation, read [Span Links][4].
+
+[1]: /tracing/trace_pipeline/trace_retention/
+[2]: /tracing/trace_collection/custom_instrumentation/php#adding-span-links-beta
+[3]: /tracing/trace_collection/otel_instrumentation/java#requirements-and-limitations
+[4]: /tracing/trace_collection/span_links/
+
 {{% /tab %}}
 {{< /tabs >}}