Add `AgentSpan.captureWithContext()` and start removing deprecated internal scope API by mcculls · Pull Request #12285 · DataDog/dd-trace-java

mcculls · 2026-08-25T14:16:04Z

What Does This Do

Add AgentSpan.captureWithContext() to help with further context migration

This captures a combination of the span with the current context so it can be resumed in another execution unit.
Note: if this combination is alrady active the existing check in IndexedContent avoids allocating a new Context.
( this is the equivalent of attachWithContext() but for capturing, not attaching )
Migrate captureActiveSpan() to Context.current().capture()
Migrate captureSpan(span) to span.captureWithContext()
Remove unused AgentTracer.TracerAPI.captureSpan(span)
Replace AgentTracer.TracerAPI.captureActiveSpan() with thin wrapper around Context.current().capture()
Drop deprecated AgentScope.Continuation type (internal API)

Motivation

Cleaning up and removing deprecated internal API

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]

mcculls · 2026-08-25T14:16:21Z

@codex review

Copilot

Pull request overview

This PR extends the tracer/context propagation API by introducing AgentSpan.captureWithContext() and migrating call sites away from deprecated internal scope-continuation APIs toward Context.current().capture() / span-based capture. It also removes the deprecated internal AgentScope.Continuation type and related plumbing.

Changes:

Add AgentSpan.captureWithContext() (and document AgentSpan.capture() as span-only capture) to support context+span continuation capture.
Replace usages of AgentTracer.captureActiveSpan() / captureSpan(span) across core + instrumentations with Context.current().capture() and span.captureWithContext().
Remove deprecated internal continuation APIs (AgentScope.Continuation, ContinuableScopeManager.capture*, CoreTracer overrides), and adapt deprecated TraceScope.Continuation via a wrapper.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/NoopScope.java	Removes deprecated continuation capture override from noop scope.
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/NoopContinuation.java	Reworks noop continuation to implement `ContextContinuation` directly.
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/java/lang/ProcessImplInstrumentationHelpers.java	Switches async continuation capture to `Context.current().capture()`.
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentTracer.java	Removes deprecated capture APIs and adds a deprecated `TraceScope.Continuation` adapter wrapper.
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentSpan.java	Adds `captureWithContext()` and clarifies span-only vs span+context capture behavior.
internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentScope.java	Drops deprecated `AgentScope.Continuation` internal type.
dd-trace-core/src/test/java/datadog/trace/core/scopemanager/ScopeManagerForkedTest.java	Migrates tests to `Context.current().capture()` and `span.captureWithContext()`.
dd-trace-core/src/test/java/datadog/trace/core/PendingTraceTest.java	Updates test to use `Context.current().capture()` in place of tracer capture API.
dd-trace-core/src/test/java/datadog/trace/core/PendingTraceStrictWriteTest.java	Updates strict-write tests to use `Context.current().capture()`.
dd-trace-core/src/test/java/datadog/trace/core/PendingTraceBufferTest.java	Switches buffered continuation capture to `span.captureWithContext()`.
dd-trace-core/src/main/java/datadog/trace/core/scopemanager/ScopeContinuation.java	Switches continuation implementation from deprecated agent continuation type to `ContextContinuation`.
dd-trace-core/src/main/java/datadog/trace/core/scopemanager/ContinuableScopeManager.java	Removes deprecated `captureActiveSpan()` / `captureSpan()` APIs in favor of context API.
dd-trace-core/src/main/java/datadog/trace/core/CoreTracer.java	Removes now-unused overrides for deprecated capture APIs.
dd-java-agent/instrumentation/zio/zio-2.0/src/main/java/datadog/trace/instrumentation/zio/v2_0/FiberContext.java	Captures `ContextContinuation` from stored `Context` instead of deprecated tracer API.
dd-java-agent/instrumentation/vertx/vertx-sql-client-3.9/src/main/java/datadog/trace/instrumentation/vertx_sql_client_39/QueryAdvice.java	Migrates parent continuation capture to `parentSpan.captureWithContext()`.
dd-java-agent/instrumentation/vertx/vertx-sql-client-3.9/src/main/java/datadog/trace/instrumentation/vertx_sql_client_39/CursorReadAdvice.java	Migrates parent continuation capture to `parentSpan.captureWithContext()`.
dd-java-agent/instrumentation/vertx/vertx-redis-client/vertx-redis-client-3.9/src/main/java/datadog/trace/instrumentation/vertx_redis_client/RedisSendAdvice.java	Switches parent continuation capture to span/context-based capture.
dd-java-agent/instrumentation/vertx/vertx-redis-client/vertx-redis-client-3.9/src/main/java/datadog/trace/instrumentation/vertx_redis_client/RedisFutureSendAdvice.java	Switches parent continuation capture to span/context-based capture for futures.
dd-java-agent/instrumentation/vertx/vertx-redis-client/vertx-redis-client-3.9/src/main/java/datadog/trace/instrumentation/vertx_redis_client/RedisAPICallAdvice.java	Switches parent continuation capture to span/context-based capture for Redis API calls.
dd-java-agent/instrumentation/undertow/undertow-2.0/src/main/java/datadog/trace/instrumentation/undertow/UndertowRunnableWrapper.java	Migrates runnable wrapper continuation capture to `Context.current().capture()`.
dd-java-agent/instrumentation/undertow/undertow-2.0/src/main/java/datadog/trace/instrumentation/undertow/HandlerInstrumentation.java	Captures continuation via `span.captureWithContext()` for exchange lifecycle.
dd-java-agent/instrumentation/synapse-3.0/src/main/java/datadog/trace/instrumentation/synapse3/SynapseServerWorkerInstrumentation.java	Uses `Java8BytecodeBridge.currentContext().capture()` for worker propagation.
dd-java-agent/instrumentation/synapse-3.0/src/main/java/datadog/trace/instrumentation/synapse3/SynapseClientWorkerInstrumentation.java	Uses `Java8BytecodeBridge.currentContext().capture()` for worker propagation.
dd-java-agent/instrumentation/spring/spring-scheduling-3.1/src/main/java/datadog/trace/instrumentation/springscheduling/SpringAsyncAdvice.java	Migrates async scheduling capture to `currentContext().capture()`.
dd-java-agent/instrumentation/servicetalk/servicetalk-0.42.56/src/test/groovy/ContextPreservingInstrumentationTest.groovy	Updates tests to use `Context.current().capture()` instead of tracer capture API.
dd-java-agent/instrumentation/servicetalk/servicetalk-0.42.0/src/test/groovy/ContextPreservingInstrumentationTest.groovy	Updates tests to use `Context.current().capture()` instead of tracer capture API.
dd-java-agent/instrumentation/redisson/redisson-3.10.3/src/main/java/datadog/trace/instrumentation/redisson30/RedissonInstrumentation.java	Migrates promise completion continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/redisson/redisson-2.3.0/src/main/java/datadog/trace/instrumentation/redisson23/RedissonInstrumentation.java	Migrates listener continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/redisson/redisson-2.0.0/src/main/java/datadog/trace/instrumentation/redisson/RedissonInstrumentation.java	Migrates listener continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/play-ws/play-ws-2.1/src/main/java/datadog/trace/instrumentation/playws21/AsyncHandlerWrapper.java	Switches handler wrapper continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/play-ws/play-ws-2.0/src/main/java/datadog/trace/instrumentation/playws2/AsyncHandlerWrapper.java	Switches handler wrapper continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/play-ws/play-ws-1.0/src/main/java/datadog/trace/instrumentation/playws1/AsyncHandlerWrapper.java	Switches handler wrapper continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/netty/netty-promise-4.0/src/main/java/datadog/trace/instrumentation/netty4/promise/ListenerWrapper.java	Migrates netty listener wrapper continuation capture to `Context.current().capture()`.
dd-java-agent/instrumentation/netty/netty-4.1/src/main/java/datadog/trace/instrumentation/netty41/NettyChannelPipelineInstrumentation.java	Uses `currentContext().capture()` for connect continuation propagation.
dd-java-agent/instrumentation/netty/netty-4.0/src/main/java/datadog/trace/instrumentation/netty40/NettyChannelPipelineInstrumentation.java	Uses `currentContext().capture()` for connect continuation propagation.
dd-java-agent/instrumentation/netty/netty-3.8/src/main/java/datadog/trace/instrumentation/netty38/NettyChannelInstrumentation.java	Uses `currentContext().capture()` for connect continuation propagation.
dd-java-agent/instrumentation/mongo/mongo-driver/mongo-driver-4.0/src/main/java/datadog/trace/instrumentation/mongo/CallbackWrapper.java	Migrates callback wrapper continuation capture to `Context.current().capture()`.
dd-java-agent/instrumentation/kotlin-coroutines-1.3/src/main/java/datadog/trace/instrumentation/kotlin/coroutines/DatadogThreadContextElement.java	Captures continuation from stored `Context` instead of deprecated tracer capture.
dd-java-agent/instrumentation/jetty/jetty-server/jetty-server-12.0/src/main/java17/datadog/trace/instrumentation/jetty12/JettyRunnableWrapper.java	Migrates runnable wrapper continuation capture to `Context.current().capture()`.
dd-java-agent/instrumentation/java/java-net/java-net-11.0/src/main/java11/datadog/trace/instrumentation/httpclient/BodyHandlerWrapper.java	Migrates body handler wrapper continuation capture to `span.captureWithContext()`.
dd-java-agent/instrumentation/java/java-lang/java-lang-21.0/src/main/java/datadog/trace/instrumentation/java/lang/jdk21/VirtualThreadInstrumentation.java	Uses `currentContext()` + `context.capture()` for virtual thread propagation.
dd-java-agent/instrumentation/axis2-1.3/src/main/java/datadog/trace/instrumentation/axis2/AxisEngineInstrumentation.java	Migrates Axis2 continuation storage to `span.captureWithContext()`.
dd-java-agent/instrumentation/apache-httpclient/apache-httpclient-5.0/src/main/java/datadog/trace/instrumentation/apachehttpclient5/ApacheHttpAsyncClientInstrumentation.java	Migrates async client parent continuation capture to `currentContext().capture()`.
dd-java-agent/instrumentation/apache-httpclient/apache-httpasyncclient-4.0/src/main/java/datadog/trace/instrumentation/apachehttpasyncclient/ApacheHttpAsyncClientInstrumentation.java	Migrates async client parent continuation capture to `currentContext().capture()`.
dd-java-agent/instrumentation/aerospike-4.0/src/main/java/datadog/trace/instrumentation/aerospike4/AerospikeClientInstrumentation.java	Migrates listener continuation capture to `span.captureWithContext()`.
dd-java-agent/agent-bootstrap/src/main/java/datadog/trace/bootstrap/instrumentation/java/concurrent/Wrapper.java	Migrates bootstrap runnable wrapper to `Context.current().capture()`.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0310c1f455

ℹ️ 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".

dd-octo-sts · 2026-08-25T15:39:39Z

🟢 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.88 s	14.71 s	[+0.3%; +2.0%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.64 s	13.75 s	[-1.6%; -0.0%] (maybe better)
startup:petclinic:appsec:Agent	17.01 s	16.21 s	[+0.4%; +9.5%] (maybe worse)
startup:petclinic:iast:Agent	16.98 s	17.07 s	[-1.4%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	16.68 s	16.82 s	[-1.9%; +0.4%] (no difference)
startup:petclinic:sca:Agent	16.79 s	16.58 s	[+0.4%; +2.1%] (maybe worse)
startup:petclinic:tracing:Agent	16.20 s	16.10 s	[-0.2%; +1.5%] (no difference)

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

…tion This captures a combination of the span with the current context so it can be resumed in another execution unit. Note: if this combination is alrady active the existing check in IndexedContent avoids allocating a new Context. ( this is the equivalent of attachWithContext() but for capturing, not attaching )

…pan(span) to span.captureWithContext()

…apper around Context.current().capture()

mcculls added comp: core Tracer core tag: no release notes Changes to exclude from release notes type: refactoring labels Aug 25, 2026

mcculls requested a lite review from Copilot August 25, 2026 14:16

Copilot started reviewing on behalf of mcculls August 25, 2026 14:16 View session

Copilot AI reviewed Aug 25, 2026

View reviewed changes

Comment thread internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentTracer.java

This comment has been minimized.

Sign in to view

chatgpt-codex-connector Bot reviewed Aug 25, 2026

View reviewed changes

mcculls force-pushed the mcculls/span-capturewithcontext branch 3 times, most recently from f3753e0 to 2f46bce Compare August 25, 2026 15:05

mcculls added 5 commits August 25, 2026 18:02

Migrate captureActiveSpan to Context.current().capture() and captureS…

324a4b2

…pan(span) to span.captureWithContext()

Remove unused AgentTracer.TracerAPI.captureSpan method

0241337

Replace AgentTracer.TracerAPI.captureActiveSpan() method with thin wr…

55fd233

…apper around Context.current().capture()

Drop the deprecated AgentScope.Continuation type (internal API)

fe5a608

mcculls force-pushed the mcculls/span-capturewithcontext branch from 2f46bce to fe5a608 Compare August 25, 2026 17:03

Navigation Menu

Uh oh!

Add `AgentSpan.captureWithContext()` and start removing deprecated internal scope API - #12285

Add `AgentSpan.captureWithContext()` and start removing deprecated internal scope API#12285
mcculls wants to merge 5 commits into
masterfrom
mcculls/span-capturewithcontext

mcculls commented Aug 25, 2026 •

edited

Loading

Uh oh!

mcculls commented Aug 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

This comment has been minimized.

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-sts Bot commented Aug 25, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

mcculls commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Contributor Checklist

Uh oh!

mcculls commented Aug 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

dd-octo-sts Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mcculls commented Aug 25, 2026 •

edited

Loading

dd-octo-sts Bot commented Aug 25, 2026 •

edited

Loading