Span Links Beta Documentation

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

@@ -348,3 +348,4 @@ Traces can be excluded based on their resource name, to remove synthetic traffic
 [8]: /tracing/trace_collection/trace_context_propagation/java/
 [9]: /tracing/security
 [10]: /tracing/guide/ignoring_apm_resources/
+[11]: /tracing/trace_explorer/trace_view

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

@@ -417,6 +417,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.
@@ -735,3 +774,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

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

@@ -25,6 +25,7 @@ The following OpenTelemetry features implemented in the Datadog library as noted
 | [Span processors][2]                  | Unsupported                                          | 
 | [Span Exporters][3]                   | Unsupported                                            |
 | Trace/span [ID generators][4]         | ID generation is performed by `ddtrace`.           |
+| [Span links][12]                      | Requires `dd-trace-java` version 1.24.0 or greater. |
 
 
 ## Configuring OpenTelemetry to use the Datadog tracing library
@@ -46,4 +47,5 @@ Datadog combines these OpenTelemetry spans with other Datadog APM spans into a s
 [5]: https://opentelemetry.io/docs/instrumentation/java/manual/
 [8]: https://opentelemetry.io/docs/instrumentation/java/automatic/
 [9]: /tracing/trace_collection/trace_context_propagation/java/
-[11]: /tracing/trace_collection/dd_libraries/java/?tab=springboot#add-the-java-tracer-to-the-jvm
+[11]: /tracing/trace_collection/dd_libraries/java/?tab=springboot#add-the-java-tracer-to-the-jvm
+[12]: https://opentelemetry.io/docs/instrumentation/java/manual/#create-spans-with-links

content/en/tracing/trace_explorer/trace_view.md

@@ -110,6 +110,29 @@ 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.0">Java tracer v.1.24.0+</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][1].
+
+To add custom instrumentation for span links, read the following documentation for your application's language:
+* [PHP][2]
+* [Java][3]
+
+[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
+
 {{% /tab %}}
 {{< /tabs >}}