Deprecate AgentScope.Continuation and migrate call sites to ContextContinuation by mcculls · Pull Request #11951 · DataDog/dd-trace-java

mcculls · 2026-07-15T00:33:21Z

What Does This Do

Marks AgentScope.Continuation as @deprecated — it was a bridging interface extending both TraceScope.Continuation (public API) and ContextContinuation (modern context API).
Migrates internal call sites to use ContextContinuation directly:
- AgentTraceCollector.register/removeContinuation now accept ContextContinuation.
- AgentTracer.captureActiveSpan()/captureSpan() static methods return ContextContinuation (implementations still return AgentScope.Continuation for Tracer interface compat).
- ScopeContinuation gains resume()/release() to satisfy the ContextContinuation contract.
- State, ConcurrentState, Wrapper, VirtualThreadState, AdviceUtils, TPEHelper migrated from AgentScope.Continuation to ContextContinuation/ContextScope.
- ~85 instrumentation files updated: field types switched to ContextContinuation, activate() → resume(),

Motivation

AgentScope.Continuation mixes a legacy public-API contract with the modern context API, forcing internal code to depend on a bridging type it doesn't need. Moving internal call sites onto ContextContinuation directly clears the path to eventually removing the legacy interface, without changing behavior.

Additional Notes

This is a mechanical migration with no intended behavior change — AgentScope.Continuation remains available (deprecated) for public API / Tracer interface compatibility. No release note required.

Contributor Checklist

Format the title according to the contribution guidelines
Assign the type: and (comp: or inst:) labels in addition to any other useful labels
Avoid using close, fix, or any linking keywords when referencing an issue
Use solves instead, and assign the PR milestone to the issue
Update the CODEOWNERS file on source file addition, migration, or deletion
Update public documentation with any new configuration flags or behaviors
Once approved, use merge queue to merge the PR

Jira ticket: [PROJ-IDENT]

…for proper swapping over to ThreadLocalContextManager.

@deprecated

…ntinuation AgentScope.Continuation was a bridging interface that extended both TraceScope.Continuation (public API) and ContextContinuation (modern context API). It is now @deprecated — internal call sites migrate to ContextContinuation directly. Key changes: - AgentScope.Continuation marked @deprecated - AgentTraceCollector.register/removeContinuation now accept ContextContinuation - AgentTracer.captureActiveSpan()/captureSpan() static methods return ContextContinuation (implementations still return AgentScope.Continuation for Tracer interface compat) - ScopeContinuation gains resume()/release() for the ContextContinuation contract - State, ConcurrentState, Wrapper, VirtualThreadState, AdviceUtils, TPEHelper all migrated from AgentScope.Continuation to ContextContinuation/ContextScope - ~85 instrumentation files updated: field types use ContextContinuation, activate()→resume(), cancel()→release(), scope types use ContextScope Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4041cbed27

ℹ️ 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 · 2026-07-15T00:46:23Z

      StaticEventLogger.end("crashtracking");
    }

+    if (InstrumenterConfig.get().isLegacyContextManagerEnabled()) {


Preserve async propagation when legacy context is off

When DD_LEGACY_CONTEXT_MANAGER_ENABLED=false, this branch leaves Context.current() backed by the default ThreadLocalContextManager while AgentTracer.activeSpan()/captureActiveSpan() still read the ContinuableScopeManager. Context-tracking server advice attaches request spans with context.attach(), but executor propagation still captures via AdviceUtils.capture() → activeSpan(), so a request that submits work to an executor in non-legacy mode will see activeSpan == null and lose the parent span. Before this change the scope manager registered as the ContextManager, so those two views stayed in sync.

Useful? React with 👍 / 👎.

This is the first step in a series of migrations, split into several PRs to help with reviewing - this particular concern is addressed in a later PR which refactors AgentTracer internals. The important thing in this PR is that the legacy=true behaviour is not disturbed.

chatgpt-codex-connector · 2026-07-15T00:46:23Z

   */
  @Nonnull
-  public static AgentScope.Continuation captureActiveSpan() {
+  public static ContextContinuation captureActiveSpan() {


Preserve AgentTracer capture helper descriptors

Changing the public static helper return type removes the old JVM descriptor captureActiveSpan():AgentScope$Continuation; any precompiled custom instrumentation or extension compiled against the existing bootstrap API will now fail with NoSuchMethodError, and source assigning the result to AgentScope.Continuation no longer compiles. The same applies to captureSpan below, and keeping the old covariant return type would still let migrated internal call sites store the result as ContextContinuation because AgentScope.Continuation extends it.

Useful? React with 👍 / 👎.

This is internal API with no binary compatibility guarantees so we can (and should) change the type to remove dependency on a deprecated type.

chatgpt-codex-connector · 2026-07-15T00:46:23Z

+    public ContextScope attach(Context context) {
+      return noopScope();


Keep Context attach functional without a tracer

When tracing and CI Visibility are disabled, TracerInstaller leaves AgentTracer as the no-op tracer while context-tracking instrumentations are still installed; with the new legacy ContextManager shim, Context.attach() then delegates here and gets a NoopScope, so Context.current() remains root and any non-tracing context propagation is dropped. The no-op tracer needs to preserve the normal thread-local Context behavior, or the shim should only be installed once a real tracer exists.

Useful? React with 👍 / 👎.

The legacy behaviour is that methods become "no-ops" when no tracer is installed.

Once migration to the Context API is complete(and legacy=false) we will no longer have that restriction because the context propagation will be fully independent of the tracer. We don't need to support this feature in legacy mode though because the goal is for legacy mode to go away.

datadog-datadog-prod-us1

More details

The migration is behaviorally faithful: resume()/release() in ScopeContinuation are the new primary implementations with activate()/cancel() delegating to them, the (AgentScope) resume() cast is safe (both return paths give ContinuableScope or NoopScope), and ContinuableScopeManager's explicit installLegacyContextManager() call is correctly wired in Agent bootstrap, native-image activation, and all test bases. Two SQS test classes covering the non-legacy path are intentionally @Disabled pending the broader migration (APMLP-829).

Was this helpful? React 👍 or 👎

_{📊 Validated against 23 scenarios · Open Bits AI session}

_{🤖 Datadog Autotest · Commit 4041cbe · What is Autotest? · Any feedback? Reach out in #autotest}

dd-octo-sts · 2026-07-15T00:53:28Z

🟢 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.05 s	13.93 s	[+0.1%; +1.7%] (maybe worse)
startup:insecure-bank:tracing:Agent	12.93 s	12.95 s	[-0.9%; +0.6%] (no difference)
startup:petclinic:appsec:Agent	16.91 s	16.82 s	[-0.3%; +1.4%] (no difference)
startup:petclinic:iast:Agent	16.92 s	16.89 s	[-0.8%; +1.1%] (no difference)
startup:petclinic:profiling:Agent	16.52 s	16.68 s	[-2.2%; +0.2%] (no difference)
startup:petclinic:sca:Agent	16.87 s	16.86 s	[-0.9%; +1.1%] (no difference)
startup:petclinic:tracing:Agent	15.61 s	16.06 s	[-7.0%; +1.5%] (no difference)

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

pr-commenter · 2026-07-15T01:18:56Z

Kafka / consumer-benchmark

Parameters

	Baseline	Candidate
baseline_or_candidate	baseline	candidate
git_branch	master	mcculls/deprecate-agent-scope-continuation-1-migrate-call-sites
git_commit_date	1784055714	1784074080
git_commit_sha	`fbd28da`	`4041cbe`

See matching parameters

	Baseline	Candidate
ci_job_date	1784076531	1784076531
ci_job_id	1859790301	1859790301
ci_pipeline_id	124661604	124661604
cpu_model	Intel(R) Xeon(R) Platinum 8259CL CPU @ 2.50GHz	Intel(R) Xeon(R) Platinum 8259CL CPU @ 2.50GHz
jdkVersion	11.0.25	11.0.25
jmhVersion	1.36	1.36
jvm	/usr/lib/jvm/java-11-openjdk-amd64/bin/java	/usr/lib/jvm/java-11-openjdk-amd64/bin/java
jvmArgs	-Dfile.encoding=UTF-8 -Djava.io.tmpdir=/go/src/github.com/DataDog/apm-reliability/dd-trace-java/platform/src/consumer-benchmark/build/tmp/jmh -Duser.country=US -Duser.language=en -Duser.variant	-Dfile.encoding=UTF-8 -Djava.io.tmpdir=/go/src/github.com/DataDog/apm-reliability/dd-trace-java/platform/src/consumer-benchmark/build/tmp/jmh -Duser.country=US -Duser.language=en -Duser.variant
vmName	OpenJDK 64-Bit Server VM	OpenJDK 64-Bit Server VM
vmVersion	11.0.25+9-post-Ubuntu-1ubuntu122.04	11.0.25+9-post-Ubuntu-1ubuntu122.04

Summary

Found 0 performance improvements and 1 performance regressions! Performance is the same for 2 metrics, 0 unstable metrics.

scenario	Δ mean throughput
scenario:only-tracing-dsm-enabled-benchmarks/KafkaConsumerBenchmark.benchConsume	worse [-11233.058op/s; -3130.904op/s] or [-5.805%; -1.618%]

See unchanged results

scenario	Δ mean throughput
scenario:not-instrumented/KafkaConsumerBenchmark.benchConsume	same
scenario:only-tracing-dsm-disabled-benchmarks/KafkaConsumerBenchmark.benchConsume	same

mcculls and others added 2 commits July 14, 2026 23:37

Rework shim between ContextManager and legacy scope manager to allow …

0f9aaf6

…for proper swapping over to ThreadLocalContextManager.

mcculls requested review from a team as code owners July 15, 2026 00:33

mcculls added the comp: core Tracer core label Jul 15, 2026

mcculls requested review from a team as code owners July 15, 2026 00:33

mcculls added tag: no release notes Changes to exclude from release notes type: refactoring labels Jul 15, 2026

mcculls requested review from PerfectSlayer, ValentinZakharov and mtoffl01 and removed request for a team July 15, 2026 00:33

mcculls marked this pull request as draft July 15, 2026 00:33

dd-octo-sts Bot added the tag: ai generated Largely based on code generated by an AI or LLM label Jul 15, 2026

This comment has been minimized.

Sign in to view

chatgpt-codex-connector Bot reviewed Jul 15, 2026

View reviewed changes

datadog-datadog-prod-us1 Bot reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Deprecate AgentScope.Continuation and migrate call sites to ContextContinuation#11951

Deprecate AgentScope.Continuation and migrate call sites to ContextContinuation#11951
mcculls wants to merge 2 commits into
masterfrom
mcculls/deprecate-agent-scope-continuation-1-migrate-call-sites

mcculls commented Jul 15, 2026

Uh oh!

This comment has been minimized.

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 15, 2026

Uh oh!

mcculls Jul 15, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 15, 2026

Uh oh!

mcculls Jul 15, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 15, 2026

Uh oh!

mcculls Jul 15, 2026

Uh oh!

datadog-datadog-prod-us1 Bot left a comment

Uh oh!

dd-octo-sts Bot commented Jul 15, 2026

Uh oh!

pr-commenter Bot commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		public ContextScope attach(Context context) {
		return noopScope();

Uh oh!

Conversation

mcculls commented Jul 15, 2026

What Does This Do

Motivation

Additional Notes

Contributor Checklist

Uh oh!

This comment has been minimized.

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

mcculls Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

mcculls Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

mcculls Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

datadog-datadog-prod-us1 Bot left a comment

Choose a reason for hiding this comment

Uh oh!

dd-octo-sts Bot commented Jul 15, 2026

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

pr-commenter Bot commented Jul 15, 2026

Kafka / consumer-benchmark

Parameters

Summary

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant