Skip to content

Switch instrumentations over to ContextScope, remove AgentScope - #12557

Open
mcculls wants to merge 19 commits into
masterfrom
mcculls/remove-agent-scope
Open

mcculls wants to merge 19 commits into
masterfrom
mcculls/remove-agent-scope

Conversation

@mcculls

@mcculls mcculls commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

What Does This Do

After the continuation migration AgentScope was left as a thin bridge interface involving ContextScope + TraceScope + span(). This PR finishes that migration: AgentScope is deleted entirely, and every scope-returning/consuming call site now uses ContextScope directly, with AgentSpan.fromScope(scope) / Java8BytecodeBridge.spanFromScope(scope) helpers replacing scope.span().

Note the AgentSpan.fromContext method used by the helpers is optimized for the common case where the span is the context.

  • Decoupled AgentScope from TraceScope first (isolated, low-risk step) to prove nothing depended on the deprecated async-propagation methods through that interface.
  • Added AgentSpan.fromScope(ContextScope) to extract the active span from a scope's context.
  • Migrated all scope-typed fields, locals, and method signatures from AgentScope to ContextScope across internal-api, dd-trace-core, dd-trace-ot, and all dd-java-agent instrumentation modules (~195 files), plus debugger, LLM Observability, and test modules.
  • Deleted AgentScope.java.
  • Updated documentation (ARCHITECTURE.md, docs/add_new_instrumentation.md, docs/how_instrumentations_work.md) and the apm-integrations skill reference to describe ContextScope instead of AgentScope, including fixing a pre-existing doc issue which mentioned Continuation in AgentScope (we now use ContextContinuation as the continuation type).
  • Cleaned up stray AgentScope mentions in comments (ConfigInversionLinter.kt, DDLLMObsSpanTest.groovy) and renamed AgentScope-named identifiers in StreamTaskContext/KafkaStreamTaskInstrumentation (kafka-streams-0.11) to match. Also corrected the ConfigInversionLinter.kt comment to say Undertow's legacy DD_UNDERTOW_CONTINUATION key stores a ContextContinuation, not a ContextScope.
  • Removed the now-stale NoopAgentScope JaCoCo coverage exclusion in internal-api/build.gradle.kts.

Motivation

AgentScope added a layer of indirection with no remaining unique behaviour. Every implementer is a ContextScope, and the default methods contributed by TraceScope were unused. Switching toContextScope simplifies the scope hierarchy and continues the tracer's move toward the generic Context API

Additional Notes

Performance

Ran several load-test runs using dd-java-agent/benchmark-integration with a real DDAgentWriter serializing via a local trace agent. Comparing this branch against master across workloads from <1ms to 10ms: throughput and latency are statistically indistinguishable between the two (differences within ~0.2%, well under normal run-to-run noise). No measurable performance impact.

Contributor Checklist

Jira ticket: [PROJ-IDENT]

@mcculls mcculls added comp: core Tracer core tag: no release notes Changes to exclude from release notes type: refactoring tag: ai generated Largely based on code generated by an AI or LLM labels Sep 18, 2026
@datadog-prod-us1-5

This comment has been minimized.

@dd-octo-sts

dd-octo-sts Bot commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

🟢 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.11 s 14.01 s [-0.2%; +1.5%] (no difference)
startup:insecure-bank:tracing:Agent 12.98 s 13.01 s [-1.1%; +0.6%] (no difference)
startup:petclinic:appsec:Agent 17.59 s 17.24 s [+1.2%; +3.0%] (significantly worse)
startup:petclinic:iast:Agent 16.83 s 17.63 s [-8.7%; -0.3%] (maybe better)
startup:petclinic:profiling:Agent 17.33 s 17.55 s [-2.4%; -0.2%] (maybe better)
startup:petclinic:sca:Agent 17.65 s 17.55 s [-0.5%; +1.6%] (no difference)
startup:petclinic:tracing:Agent 16.56 s 16.33 s [-2.9%; +5.7%] (no difference)

Commit: c1c5a4da · 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

pr-commenter Bot commented Sep 18, 2026

Copy link
Copy Markdown

Debugger benchmarks

Parameters

Baseline Candidate
baseline_or_candidate baseline candidate
ci_job_date 1789722784 1789723111
end_time 2026-09-18T09:14:34 2026-09-18T09:20:01
git_branch master mcculls/remove-agent-scope
git_commit_sha cf8ea07 8a13612
start_time 2026-09-18T09:13:05 2026-09-18T09:18:32
See matching parameters
Baseline Candidate
ci_job_id 2056865755 2056865755
ci_pipeline_id 138405868 138405868
cpu_model Intel(R) Xeon(R) Platinum 8175M CPU @ 2.50GHz Intel(R) Xeon(R) Platinum 8175M CPU @ 2.50GHz
git_commit_date 1789721963 1789721963

Summary

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

See unchanged results
scenario Δ mean agg_http_req_duration_min Δ mean agg_http_req_duration_p50 Δ mean agg_http_req_duration_p75 Δ mean agg_http_req_duration_p99 Δ mean throughput
scenario:noprobe unstable
[-25.382µs; +18.390µs] or [-7.617%; +5.519%]
unstable
[-36.090µs; +29.301µs] or [-9.894%; +8.033%]
unstable
[-45.785µs; +38.440µs] or [-12.074%; +10.137%]
unstable
[-20.145µs; +183.589µs] or [-1.892%; +17.240%]
same
scenario:basic same same same unstable
[-63.809µs; +187.335µs] or [-6.597%; +19.369%]
same
scenario:loop same same same same same
Request duration reports for reports
gantt
    title reports - request duration [CI 0.99] : candidate=None, baseline=None
    dateFormat X
    axisFormat %s
section baseline
noprobe (364.751 µs) : 333, 397
.   : milestone, 365,
basic (340.586 µs) : 333, 349
.   : milestone, 341,
loop (8.116 ms) : 8052, 8180
.   : milestone, 8116,
section candidate
noprobe (361.356 µs) : 331, 391
.   : milestone, 361,
basic (340.533 µs) : 334, 347
.   : milestone, 341,
loop (8.117 ms) : 8053, 8181
.   : milestone, 8117,
Loading
  • baseline results
Scenario Request median duration [CI 0.99]
noprobe 364.751 µs [332.672 µs, 396.83 µs]
basic 340.586 µs [332.618 µs, 348.555 µs]
loop 8.116 ms [8.052 ms, 8.18 ms]
  • candidate results
Scenario Request median duration [CI 0.99]
noprobe 361.356 µs [331.373 µs, 391.339 µs]
basic 340.533 µs [333.848 µs, 347.218 µs]
loop 8.117 ms [8.053 ms, 8.181 ms]

@mcculls mcculls changed the title Remove AgentScope Remove AgentScope and switch instrumentations over to ContextScope Sep 18, 2026
*/
@Advice.OnMethodEnter(suppress = Throwable.class)
public static TraceScope methodEnter(
public static AutoCloseable methodEnter(

@mcculls mcculls Sep 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change was necessary so we could continue to use AgentTracer::closeActive in a specific edge-case. Since this is a SAM type (Single Abstract Method) we need to find a similar SAM type in the hierarchy, and the closest was AutoCloseable.

@mcculls

mcculls commented Sep 18, 2026

Copy link
Copy Markdown
Contributor Author

@DataDog review

@pr-commenter

pr-commenter Bot commented Sep 18, 2026

Copy link
Copy Markdown

Kafka / consumer-benchmark

Parameters

Baseline Candidate
baseline_or_candidate baseline candidate
git_branch master mcculls/remove-agent-scope
git_commit_date 1789676683 1789726786
git_commit_sha d5f7fcb c1c5a4d
See matching parameters
Baseline Candidate
ci_job_date 1789728325 1789728325
ci_job_id 2057182433 2057182433
ci_pipeline_id 138425420 138425420
cpu_model Intel(R) Xeon(R) Platinum 8175M CPU @ 2.50GHz Intel(R) Xeon(R) Platinum 8175M CPU @ 2.50GHz
jdkVersion 11.0.31 11.0.31
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 -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=15002 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=15002 -Dhttp.nonProxyHosts=localhost *.localhost
kernel_version Linux runner-zfyrx7zua-project-304-concurrent-0-edgipia2 6.8.0-1031-aws #33~22.04.1-Ubuntu SMP Thu Jun 26 14:22:30 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux Linux runner-zfyrx7zua-project-304-concurrent-0-edgipia2 6.8.0-1031-aws #33~22.04.1-Ubuntu SMP Thu Jun 26 14:22:30 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
vmName OpenJDK 64-Bit Server VM OpenJDK 64-Bit Server VM
vmVersion 11.0.31+11-post-1ubuntu1-22.04.2-Ubuntu 11.0.31+11-post-1ubuntu1-22.04.2-Ubuntu

Summary

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

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

@datadog-prod-us1-5 datadog-prod-us1-5 Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Datadog Autotest: PASS

More details

The new ContextScope path keeps span extraction and scope life cycle behavior.

Was this helpful? React 👍 or 👎

Open Bits AI session

🤖 Datadog Autotest · Commit a002980 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest

@mcculls
mcculls requested a lite review from Copilot September 18, 2026 08:33
@mcculls
mcculls requested review from a team as code owners September 18, 2026 10:09
@mcculls
mcculls requested review from dromanol, jandro996, jpbempel, mhlidd, sarahchen6 and vandonr and removed request for a team September 18, 2026 10:09

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8a136127df

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

@datadog-prod-us1-5 datadog-prod-us1-5 Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Datadog Autotest: PASS

More details

The migration keeps scope lifecycle order and gets spans from the scope context. Advice code uses the Java 8 bytecode bridge.

Was this helpful? React 👍 or 👎

Open Bits AI session

🤖 Datadog Autotest · Commit 8a13612 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest

@pr-commenter

pr-commenter Bot commented Sep 18, 2026

Copy link
Copy Markdown

Kafka / producer-benchmark

Parameters

Baseline Candidate
baseline_or_candidate baseline candidate
git_branch master mcculls/remove-agent-scope
git_commit_date 1789676683 1789726786
git_commit_sha d5f7fcb c1c5a4d
See matching parameters
Baseline Candidate
ci_job_date 1789728060 1789728060
ci_job_id 2057137316 2057137316
ci_pipeline_id 138425420 138425420
cpu_model Intel(R) Xeon(R) Platinum 8175M CPU @ 2.50GHz Intel(R) Xeon(R) Platinum 8175M CPU @ 2.50GHz
jdkVersion 11.0.31 11.0.31
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 -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=15002 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=15002 -Dhttp.nonProxyHosts=localhost *.localhost
kernel_version Linux runner-zfyrx7zua-project-304-concurrent-0-i32n91h1 6.8.0-1031-aws #33~22.04.1-Ubuntu SMP Thu Jun 26 14:22:30 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux Linux runner-zfyrx7zua-project-304-concurrent-0-i32n91h1 6.8.0-1031-aws #33~22.04.1-Ubuntu SMP Thu Jun 26 14:22:30 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
vmName OpenJDK 64-Bit Server VM OpenJDK 64-Bit Server VM
vmVersion 11.0.31+11-post-1ubuntu1-22.04.2-Ubuntu 11.0.31+11-post-1ubuntu1-22.04.2-Ubuntu

Summary

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

See unchanged results
scenario Δ mean throughput
scenario:not-instrumented/KafkaProduceBenchmark.benchProduce same
scenario:only-tracing-dsm-disabled-benchmarks/KafkaProduceBenchmark.benchProduce same
scenario:only-tracing-dsm-enabled-benchmarks/KafkaProduceBenchmark.benchProduce same

@jpbempel jpbempel left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM for debugger part

@daniel-mohedano daniel-mohedano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM on CiVis side!

@sarahchen6 sarahchen6 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM for LP

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp: core Tracer core tag: ai generated Largely based on code generated by an AI or LLM tag: no release notes Changes to exclude from release notes type: refactoring

Projects

None yet

Development

Successfully merging this pull request may close these issues.