feat(tracing): add span link support

[MilanGarnier]

Description

Adds OpenTelemetry-style span links to dd-trace-cpp.

• ExtractedContext struct (include/datadog/extracted_context.h)
• SpanLink struct (include/datadog/span_link.h): 128-bit trace_id, span_id, optional tracestate, string attributes, optional flags.
• msgpack serialization (src/datadog/span_link.cpp): per-link map with the exact field names and omission rules used by dd-trace-go / dd-trace-py / dd-trace-rs (trace_id, trace_id_high only when non-zero, span_id, attributes only when non-empty, tracestate only when non-empty, flags with high bit set when present).
• SpanData::span_links (src/datadog/span_data.h/.cpp): std::vector<SpanLink> field; the span encoder emits a span_links array only when non-empty (matches omitempty behaviour of other tracers).
• Span::add_link(const SpanLink&) (include/datadog/span.h, src/datadog/span.cpp): public API to attach a link to a live span.
• Parametric endpoint POST /trace/span/add_link (test/system-tests/): wires up the cross-language system-test client contract.

Motivation

This feature is supported by all other tracers and is a dependency for future implementations, such as DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT config (planned).

Additional Notes

• Unit tests in test/test_span_link.cpp and test/test_span.cpp exercise serialization and the public API end-to-end.
• System tests : parametric tests enabled in Enable span links parametric tests for cpp system-tests#7238
  Jira ticket: APMAPI-1941

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-07-22 11:46:56

Comparing candidate commit dbee998 in PR branch milan.garnier/span-links-support with baseline commit fbbbe47 in branch main.

Found 0 performance improvements and 1 performance regressions! Performance is the same for 7 metrics, 0 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

• 🟩 = significantly better candidate vs. baseline
• 🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

scenario:BM_HexPadded_uint64/NoPadding

• 🟥 execution_time [+2.110ns; +2.194ns] or [+3.915%; +4.070%]

[zacharycmontoya]

@xlamorlette-datadog I want the add_link API to be able to accept a map where the attribute values could be one of many types (see https://github.com/open-telemetry/opentelemetry-cpp/blob/4e20f690352ce6c2793efcb6448e51363a2cad18/api/include/opentelemetry/common/attribute_value.h). Is there any easy way to for us to build that forward compatability right now, or should we just tackle that when we get to the point that we can record attributes in general to have a variety of primitive types (rather than strings)?

[xlamorlette-datadog]

Since span_link.h is no more public, I suppose this is no more an issue.

[zacharycmontoya]

This is still an issue because the public span API for creating a span link exposes a std::unordered_map<std::string, std::string> as a parameter:

void add_link(const SpanContext& context, const SpanLinkAttributes& attributes = {});

Is it possible for us to keep this API today and then later overload it with a more permissive map? I know you're on PTO right now so we might want to take the change now and then update this in a follow-up PR

[xlamorlette-datadog]

Here are some technical comments.
Please get approval from @zacharycmontoya who understands the functionality way much better than me.

[xlamorlette-datadog]

Since span_link.h is no more public, I suppose this is no more an issue.

[zacharycmontoya]

LGTM. I have left some comments but non are blocking, just nice-to-haves like keeping all the add_link API changes in this PR and utilizing the API in the behavior extract PR. There was one outstanding question I had about the unordered_map parameter we are accepting because in the future it should be more permissive and allow different types for the values, but I think we can address that later.

[MilanGarnier]

Thanks! I cherry picked most api changes from PROPAGATION_BEHAVIOR_EXTRACT (except a few changes in parametric test server which were tied with propagation behavior changes) and resolved your other comments !