feat(sampling): Support for OpenTelemetry consistent tracestate sampling

[MilanGarnier]

What Does This Do

Adds OpenTelemetry consistent probability-sampling behavior on top of the
ot tracestate parsing introduced by #12405.

• Validates and normalizes rv and th.
• Generates probability state for loaded agent rates and sampling rules.
• Preserves inherited randomness and unknown fields across overrides.
• Keeps limiter outcomes distinct from raw probability decisions.
• Adds focused parsing, propagation, continuation, and sampling tests.

Motivation

Make Java tracer sampling decisions interoperable with OpenTelemetry
consistent probability sampling and provide the state needed for downstream
tracestate propagation.

Additional Notes

This is the second PR in a two-PR stack and depends on #12405.

This PR covers propagation and sampling only.
OTLP export (which should already work with this PR, but it can be optimized) will follow in a separate change.

Validation after rebasing the stack onto the current master:

• Focused dd-trace-core propagation and sampling tests passed.
• :dd-trace-core:compileTraceAgentTestJava passed.
• :dd-trace-core:spotlessCheck and git diff --check passed.

Prior validation of the feature branch:

• Java parametric system tests passed with 669 tests passed and 38 skipped.
• Java default system tests passed all 11 tests.
• The full :dd-trace-core:test run passed 4,277 of 4,278 tests. The remaining
  timing-sensitive PendingTraceBufferTest case passed in isolation.

Contributor Checklist

• Format the title according to the contribution guidelines.
• Assign the required type: and comp: labels.
• Keep OTLP export outside this propagation-only change.

Jira ticket: APMAPI-2171

[datadog-datadog-prod-us1-2]

🎯 Code Coverage (details)
• Patch Coverage: 86.70%
• Overall Coverage: 59.14% (+0.11%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: a0176c9 | Docs | View more details | Give us feedback!}

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.66 s	14.62 s	[-0.6%; +1.2%] (no difference)
startup:insecure-bank:tracing:Agent	13.58 s	13.63 s	[-1.1%; +0.3%] (no difference)
startup:petclinic:appsec:Agent	16.94 s	16.68 s	[+0.6%; +2.5%] (maybe worse)
startup:petclinic:iast:Agent	16.80 s	16.96 s	[-1.6%; -0.3%] (maybe better)
startup:petclinic:profiling:Agent	16.16 s	16.77 s	[-8.0%; +0.7%] (no difference)
startup:petclinic:sca:Agent	16.88 s	16.72 s	[+0.0%; +1.9%] (maybe worse)
startup:petclinic:tracing:Agent	16.07 s	15.81 s	[-2.7%; +6.0%] (no difference)

Commit: a0176c99 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[MilanGarnier]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0176c99c0

ℹ️ 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]

Defer OTel state materialization until propagation

perf: Every new local root trace after agent rates load, and every trace matching a sampling rule, reaches this call and immediately allocates a StringBuilder plus backing storage, a String, and a retained OtelTraceState, even when the trace never performs W3C injection or OTLP export. This adds several allocations to the per-trace hot path; defer string encoding until headerValue(W3C) or gate state creation when no compatible exporter is enabled, and verify the improvement with an allocation profile.

AGENTS.md reference: AGENTS.md:L79-L79

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve inherited OTel randomness during resampling

When current contains a valid inherited rv but the trace priority is still unset—for example, default compound extraction first selects Datadog headers without a sampling-priority header and then copies matching W3C tracestate—a local sampling rule reaches this line and unconditionally replaces the upstream randomness with a trace-ID hash. Consistent probability sampling requires randomness to remain stable across a trace; replacing it makes upstream and downstream thresholds and adjusted-count weights describe different cohorts. Reuse current.randomValue when present and base the probability decision on it, generating a value only when none was inherited.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve OTel state for compound Datadog extraction

With the default DATADOG, TRACECONTEXT extraction order, the first Datadog context owns the sampling priority while applyTraceContextToFirstContext copies only the later W3C tracestate. Its PropagationTags priority therefore remains UNSET, so this comparison fails and the UNKNOWN update reaches removeForNonProbabilityDecision(), deleting the inherited th even when the Datadog and W3C decisions agree. Dual headers emitted by one instrumented service consequently lose consistent-sampling state at the next Java hop; avoid reapplying extracted priorities as UNKNOWN or synchronize the merged propagation-tags priority first.

Useful? React with 👍 / 👎.