[mcculls]

What Does This Do

Add capture controls to the Context API and preserve execution-unit flags across context switches. Disabling capture returns a no-op continuation, while explicit attachment and swapping remain available. Checkpoint handles let coroutine and fiber integrations save context and flags without changing the active context or retaining a trace.

Motivation

Instrumentations need to suppress incidental asynchronous propagation and restore execution state when switching between logical tasks. The new context manager needs these controls as part of its API, with clear ownership of saved state and trace-retaining continuations.

Additional Notes

• Same-context swaps deliberately leave flags unchanged, including when using a checkpoint handle. Context identity determines whether a switch occurred; a checkpoint does not force a flag reset or rollback when the underlying context is already current. Saved flags take effect when switching from a different context. The unit tests cover both ordinary contexts and checkpoint handles under this rule.
• Scope restoration follows actual attachment. Attaching a different context preserves the current capture flag, and closing that scope restores its entry flag. Reattaching the current context produces a no-op scope and does not roll back flag changes. New tests cover flag changes during resumed work and an ignored out-of-order close followed by normal unwinding.
• Checkpoints and continuations have separate lifetimes. A checkpoint saves state for swapping but does not keep a trace open. Capture the original context first when trace retention is required, and release that continuation when its owner ends. The documentation makes this distinction explicit.
• The legacy shim retains its existing scope-based behavior during migration. Capture controls delegate to its async-propagation flag. Handles returned by legacy swaps retain the scope stack and its flag; the legacy checkpoint() remains a pass-through. This PR does not redesign flag storage outside legacy scopes or require legacy behavior to match every edge of the new manager's contract. The API documentation describes the target behavior as the legacy manager is retired.

[datadog-official]

🎯 Code Coverage (details)
• Patch Coverage: 85.45%
• Overall Coverage: 59.79% (-0.20%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 6991387 | Docs | 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.01 s	14.03 s	[-0.9%; +0.8%] (no difference)
startup:insecure-bank:tracing:Agent	12.96 s	13.05 s	[-1.5%; -0.0%] (maybe better)
startup:petclinic:appsec:Agent	17.11 s	17.10 s	[-0.8%; +1.0%] (no difference)
startup:petclinic:iast:Agent	16.89 s	17.13 s	[-2.0%; -0.8%] (maybe better)
startup:petclinic:profiling:Agent	16.70 s	16.76 s	[-1.5%; +0.8%] (no difference)
startup:petclinic:sca:Agent	17.15 s	16.91 s	[+0.7%; +2.2%] (maybe worse)
startup:petclinic:tracing:Agent	16.15 s	16.29 s	[-1.8%; +0.1%] (no difference)

Commit: 69913875 · 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.

[mcculls]

Splitting into smaller PRs