fix(libdd-trace-utils): apply SpanLink flags masking when v0.5 json encoding

[brettlangdon]

What does this PR do?

A tracer flags a SpanLink with a 32-bit flags value. Bit 31 is a sentinel: it marks that the tracer explicitly set the sampling decision, as opposed to leaving flags at its default of zero. The remaining bits carry the sampling decision itself (bit 0: kept or dropped).

Motivation

v0.4 and v0.5 disagree on whether the wire value includes this sentinel.

• In v0.4's native msgpack encoding, dd-trace-py adds the sentinel bit before it writes flags. A kept link becomes 0x8000_0001; a link the tracer explicitly dropped becomes 0x8000_0000.
• v0.5 has no native span-link field, so it encodes links as a JSON array under meta["_dd.span_links"]. dd-trace-py's v0.5 JSON encoder never adds the sentinel. A kept link's flags in this JSON is plain 1; the sentinel bit never appears there.

libdatadog's v0.5 encoder builds this JSON from the same SpanLink struct that v0.4 uses, so flags may already carry the sentinel bit. Before this fix, the v0.5 serializer wrote that raw value straight into the JSON, so a kept link produced "flags": 2147483649 instead of 1 — a value no v0.5 producer would ever emit, and one that downstream consumers checking against small integers would not recognize as "kept".

This PR masks bit 31 off the value the v0.5 serializer writes into flags, while it still decides whether to emit the flags key at all from the raw, unmasked value. Deciding presence from the masked value would break the case of a link the tracer explicitly dropped: raw 0x8000_0000 masks to 0, indistinguishable from "flags never set" if presence were decided post-mask. With this fix, an explicitly dropped link still emits "flags": 0; a link that never set flags emits no flags key at all.

Additional Notes

Anything else we should know when reviewing?

How to test the change?

• Added span_link_flags_sentinel_bit_masked_test: covers the unset, kept, and explicitly-dropped states of the sentinel bit.
• cargo test -p libdd-trace-utils, cargo fmt --check, and cargo clippy -D warnings pass.

[datadog-datadog-prod-us1]

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 99.33%
• Overall Coverage: 75.06% (+0.04%)

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

[dd-octo-sts]

Artifact Size Benchmark Report

aarch64-alpine-linux-musl

Artifact	Baseline	Commit	Change
/aarch64-alpine-linux-musl/lib/libdatadog_profiling.so	8.07 MB	8.07 MB	0% (0 B) 👌
/aarch64-alpine-linux-musl/lib/libdatadog_profiling.a	87.84 MB	87.84 MB	+0% (+704 B) 👌

aarch64-unknown-linux-gnu

Artifact	Baseline	Commit	Change
/aarch64-unknown-linux-gnu/lib/libdatadog_profiling.so	10.88 MB	10.88 MB	0% (0 B) 👌
/aarch64-unknown-linux-gnu/lib/libdatadog_profiling.a	98.97 MB	98.98 MB	+0% (+672 B) 👌

libdatadog-x64-windows

Artifact	Baseline	Commit	Change
/libdatadog-x64-windows/debug/dynamic/datadog_profiling_ffi.dll	26.21 MB	26.21 MB	0% (0 B) 👌
/libdatadog-x64-windows/debug/dynamic/datadog_profiling_ffi.lib	89.92 KB	89.92 KB	0% (0 B) 👌
/libdatadog-x64-windows/debug/dynamic/datadog_profiling_ffi.pdb	188.66 MB	188.66 MB	0% (0 B) 👌
/libdatadog-x64-windows/debug/static/datadog_profiling_ffi.lib	985.57 MB	985.57 MB	+0% (+96 B) 👌
/libdatadog-x64-windows/release/dynamic/datadog_profiling_ffi.dll	8.56 MB	8.56 MB	0% (0 B) 👌
/libdatadog-x64-windows/release/dynamic/datadog_profiling_ffi.lib	89.92 KB	89.92 KB	0% (0 B) 👌
/libdatadog-x64-windows/release/dynamic/datadog_profiling_ffi.pdb	25.22 MB	25.22 MB	0% (0 B) 👌
/libdatadog-x64-windows/release/static/datadog_profiling_ffi.lib	50.23 MB	50.23 MB	+0% (+102 B) 👌

libdatadog-x86-windows

Artifact	Baseline	Commit	Change
/libdatadog-x86-windows/debug/dynamic/datadog_profiling_ffi.dll	22.84 MB	22.84 MB	+0% (+512 B) 👌
/libdatadog-x86-windows/debug/dynamic/datadog_profiling_ffi.lib	91.33 KB	91.33 KB	0% (0 B) 👌
/libdatadog-x86-windows/debug/dynamic/datadog_profiling_ffi.pdb	193.44 MB	193.47 MB	+.01% (+32.00 KB) 🔍
/libdatadog-x86-windows/debug/static/datadog_profiling_ffi.lib	974.34 MB	974.34 MB	+0% (+96 B) 👌
/libdatadog-x86-windows/release/dynamic/datadog_profiling_ffi.dll	6.61 MB	6.61 MB	0% (0 B) 👌
/libdatadog-x86-windows/release/dynamic/datadog_profiling_ffi.lib	91.33 KB	91.33 KB	0% (0 B) 👌
/libdatadog-x86-windows/release/dynamic/datadog_profiling_ffi.pdb	27.12 MB	27.12 MB	0% (0 B) 👌
/libdatadog-x86-windows/release/static/datadog_profiling_ffi.lib	47.83 MB	47.83 MB	+0% (+96 B) 👌

x86_64-alpine-linux-musl

Artifact	Baseline	Commit	Change
/x86_64-alpine-linux-musl/lib/libdatadog_profiling.a	78.21 MB	78.21 MB	+0% (+104 B) 👌
/x86_64-alpine-linux-musl/lib/libdatadog_profiling.so	9.00 MB	9.00 MB	0% (0 B) 👌

x86_64-unknown-linux-gnu

Artifact	Baseline	Commit	Change
/x86_64-unknown-linux-gnu/lib/libdatadog_profiling.a	93.85 MB	93.85 MB	+0% (+56 B) 👌
/x86_64-unknown-linux-gnu/lib/libdatadog_profiling.so	10.97 MB	10.97 MB	0% (0 B) 👌

[pr-commenter]

Benchmarks

Comparison

Benchmark execution time: 2026-08-05 16:40:39

Comparing candidate commit 3e02c48 in PR branch brettlangdon/v05-span-link-flags with baseline commit 44f705f in branch main.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 139 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 ----------------------------------'

Benchmark execution time: 2026-08-05 16:40:46

Comparing candidate commit 3e02c48 in PR branch brettlangdon/v05-span-link-flags with baseline commit 44f705f in branch main.

Found 0 performance improvements and 4 performance regressions! Performance is the same for 71 metrics, 10 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:glob_matcher/ascii_exact_match/wall_time

• 🟥 execution_time [+4.062ns; +4.077ns] or [+15.054%; +15.109%]

scenario:glob_matcher/ascii_pattern_unicode_subject/wall_time

• 🟥 execution_time [+8.058ns; +8.176ns] or [+5.900%; +5.986%]

scenario:glob_matcher/unicode_pattern_ascii_subject/wall_time

• 🟥 execution_time [+9.603ns; +9.723ns] or [+10.594%; +10.726%]

scenario:glob_matcher/unicode_pattern_wildcard_match/wall_time

• 🟥 execution_time [+8.080ns; +8.195ns] or [+6.485%; +6.577%]

Candidate

Omitted due to size.

Baseline

Omitted due to size.

[bwoebi]

Looks correct to me, thanks for the improvement.

[bwoebi]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-08-06 13:46:03 UTC ℹ️ Start processing command /merge

---

2026-08-06 13:46:07 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in main is approximately 50m (p90).

---

2026-08-06 14:30:01 UTC ℹ️ MergeQueue: This merge request was merged