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 [cpp@milan.garnier/span-links-support] system-tests#7238
  Jira ticket: APMAPI-1941

[datadog-datadog-prod-us1-2]

🎯 Code Coverage (details)
• Patch Coverage: 97.30%
• Overall Coverage: 91.74% (+0.06%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 5c93eca | Docs | Datadog PR Page | Give us feedback!}

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-07-02 09:01:18

Comparing candidate commit 5c93eca in PR branch milan.garnier/span-links-support with baseline commit d7ea3a8 in branch main.

Found 2 performance improvements and 3 performance regressions! Performance is the same for 3 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.338ns; +2.425ns] or [+4.345%; +4.508%]

scenario:BM_HexPadded_uint64/WorstCasePadding

• 🟥 execution_time [+1.329ns; +1.519ns] or [+2.701%; +3.089%]

scenario:BM_Hex_uint64

• 🟩 execution_time [-0.957ns; -0.935ns] or [-4.041%; -3.949%]

scenario:BM_TraceID_ParseHex/128bit

• 🟩 execution_time [-4.033ns; -3.905ns] or [-3.205%; -3.103%]

scenario:BM_TraceTinyCCSource

• 🟥 execution_time [+3.106ms; +3.254ms] or [+4.166%; +4.365%]

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1a36ade09f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6c2f121762

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Preserve header case-insensitivity when storing link context

When the parametric client passes valid HTTP headers with normal casing such as Traceparent, Tracestate, or X-Datadog-Sampling-Priority, extraction above succeeds because utils::HeaderReader::lookup lowercases names, but this new copy loop compares the raw JSON name only against lowercase literals. The stored link_contexts_ then loses flags/tracestate/sampling priority, so a later /trace/span/add_link emits an incomplete span link for the same extracted context.

Useful? React with 👍 / 👎.