feat(tracing): add span link support by MilanGarnier · Pull Request #330 · DataDog/dd-trace-cpp

MilanGarnier · 2026-06-30T12:28:31Z

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

pr-commenter · 2026-06-30T12:36:31Z

Benchmarks

Benchmark execution time: 2026-07-15 09:33:18

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

Found 1 performance improvements and 1 performance regressions! Performance is the same for 6 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_TraceID_ParseHex/128bit

🟩 execution_time [-2.711ns; -2.672ns] or [-2.157%; -2.126%]

scenario:BM_TraceTinyCCSource

🟥 execution_time [+3.253ms; +3.414ms] or [+4.355%; +4.570%]

xlamorlette-datadog

This is only a first very light and superficial review, I should review in detail in a few days.

spanlink

zacharycmontoya · 2026-07-14T21:59:20Z

+
+  // Populate tracestate/flags from the linked trace's sampling decision, if
+  // one has already been made. Do not force a decision here
+  if (auto context = linked.trace_segment().w3c_link_context(*linked.data_)) {


If you end up taking my suggestion to pass in a context, then we can just copy over the tracestate and trace flags from the input SpanContext. There will be no need to get information from a trace segment. As a result, we could remove the w3c_link_context call you added to trace segment

zacharycmontoya · 2026-07-14T22:06:23Z

+        pack_resource, "trace_id", pack_trace_id, "span_id", pack_span_id,
+        "parent_id", pack_parent_id, "start", pack_start, "duration",
+        pack_duration, "error", pack_error, "meta", pack_meta, "metrics",
+        pack_metrics, "type", pack_type, "span_links", pack_span_links);


Is there a reason for splitting the behavior when there are no span links? I imagine it would be okay to run this even if we have an empty array of span links

In other tracers the field is omitted when empty, I was following the same logic. I'm also not satisfied with how it looks that way, the other option I had was using a magic number for the number of fields and several msg_pack_suffix to avoid splitting the logic.

e.g. Go uses :

spanLinks []SpanLink `msg:"span_links,omitempty"`

zacharycmontoya · 2026-07-14T22:17:32Z

+namespace datadog::tracing {
+
+// Convenience alias: the map type used for span link user attributes.
+using SpanLinkAttributes = std::unordered_map<std::string, std::string>;


@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)?

zacharycmontoya · 2026-07-14T22:39:21Z

+  // The linked context is either another active span or a previously extracted
+  // propagation context, both keyed by `parent_id`.
+  auto linked_it = active_spans_.find(*parent_id);
+  if (linked_it != active_spans_.cend()) {


Going down the path of mirroring the OpenTelemetry C++ API, we could implement a GetContext() public API on the Span class that would return a SpanContext object with the pertinent details of that Span, rather than having to do context injection to surface the information

…ributes only

zacharycmontoya · 2026-07-15T16:16:23Z

 TEST_SPAN_LINK("minimal link encodes only trace_id and span_id") {
  SpanLink link;
-  link.trace_id = TraceID(0x1122334455667788ULL);  // high == 0
+  link.trace_id = TraceID(0x1122334455667788ULL, 0xBBBBBBBBBBBBBBBBULL);


I actually preferred leaving the high-bits as 0 to ensure that we always emit the trace_id_high. Can you add a case where we test the high-bits being 0?

MilanGarnier added 8 commits June 30, 2026 10:39

add span link struct and test

fad515b

enable span link tests

0796973

implement Span::add_link

0fecaca

add span link to msg pack encoding

f254562

add spn link test for the Span class

58cf95d

implenent add_link endpoint for parametric tests

84a7ef4

flatten array

65382c4

cleaner spanlink construction

ecfb7cc

This comment has been minimized.

Sign in to view

add extracted context struct

eecfe93

cleaning up (move logic to span.cpp)

c4ae457

MilanGarnier changed the title ~~feat(tracing): add support for span links~~ feat(tracing): add span link support Jun 30, 2026

format

86d189e

MilanGarnier force-pushed the milan.garnier/span-links-support branch from cbb3ed8 to 86d189e Compare June 30, 2026 13:23

MilanGarnier temporarily deployed to dev June 30, 2026 13:25 — with GitHub Actions Inactive

MilanGarnier temporarily deployed to dev June 30, 2026 13:28 — with GitHub Actions Inactive

MilanGarnier temporarily deployed to dev June 30, 2026 13:35 — with GitHub Actions Inactive

MilanGarnier force-pushed the milan.garnier/span-links-support branch 2 times, most recently from 003399b to 28432fe Compare June 30, 2026 13:38

MilanGarnier temporarily deployed to dev July 2, 2026 08:56 — with GitHub Actions Inactive

MilanGarnier temporarily deployed to dev July 2, 2026 09:38 — with GitHub Actions Inactive

MilanGarnier temporarily deployed to dev July 2, 2026 09:41 — with GitHub Actions Inactive

case insensitive lookup for headers

5311345

MilanGarnier temporarily deployed to dev July 6, 2026 09:14 — with GitHub Actions Inactive

xlamorlette-datadog reviewed Jul 6, 2026

View reviewed changes

MilanGarnier added 8 commits July 6, 2026 11:46

nit: nested namespace syntax

f62084f

clearer variable names

9ac8c2b

get rid of magic values in span_data::msgpack

f736ab5

Cleaner msgpack_encode for span_link.cpp

0da2fea

split RequestHandler::on_add_link

64882ca

make storedLinkContexts outside of on_extract_headers function

a1a3484

bugfix: do not force sampling decision when writing tracestate in

0b3959a

spanlink

avoid collisions when adding links consecutively (parent_id=0)

f033eef

zacharycmontoya reviewed Jul 14, 2026

View reviewed changes

Comment thread include/datadog/span.h Outdated

zacharycmontoya reviewed Jul 14, 2026

View reviewed changes

Comment thread src/datadog/span_link.cpp Outdated

zacharycmontoya reviewed Jul 14, 2026

View reviewed changes

MilanGarnier added 3 commits July 15, 2026 09:58

move span link into private types, expose spancontext and spanlinkatt…

a035447

…ributes only

always store trace_id_high

6762038

fix typo in parametric server

58fcb18

zacharycmontoya reviewed Jul 15, 2026

View reviewed changes

Uh oh!

Conversation

MilanGarnier commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional Notes

Uh oh!

This comment has been minimized.

pr-commenter Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks

Explanation

More details about the CI and significant changes

scenario:BM_TraceID_ParseHex/128bit

scenario:BM_TraceTinyCCSource

Uh oh!

xlamorlette-datadog left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zacharycmontoya Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zacharycmontoya Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

MilanGarnier Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zacharycmontoya Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

zacharycmontoya Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zacharycmontoya Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MilanGarnier commented Jun 30, 2026 •

edited

Loading

pr-commenter Bot commented Jun 30, 2026 •

edited

Loading

zacharycmontoya Jul 14, 2026 •

edited

Loading

MilanGarnier Jul 15, 2026 •

edited

Loading

zacharycmontoya Jul 14, 2026 •

edited

Loading