Codebase consistency: call scope.close() before span.finish()

[mcculls]

Motivation

Provide more consistent examples for new developers

Additional Notes

During this refactoring it became clear that while scope.close() should go before span.finish(), there was an undocumented ordering that scope.close() should happen after decorator calls like beforeFinish and any registration of async callbacks.

This is because the beforeFinish call can trigger callbacks in products like IAST where it checks the current active span. Likewise any async instrumentation will capture the current active span at the time the callback is registered, and we'd want that to reflect the current span.

The agent instructions and docs have been updated to make this ordering clear.

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]

@codex review

[Copilot]

Pull request overview

This PR standardizes scope/span lifecycle ordering across a broad set of instrumentations by closing the active AgentScope before finishing the associated AgentSpan, improving consistency and reducing the chance of a finished span remaining active on the thread.

Changes:

• Reorders cleanup logic to call scope.close() before span.finish() (or finishWithEndToEnd()) across many instrumentations.
• Simplifies several exit/cleanup blocks by removing try/finally where the scope is now closed earlier in the method.
• Updates one RxJava test helper to follow the same close-then-finish ordering.

Reviewed changes

Copilot reviewed 61 out of 61 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
dd-java-agent/instrumentation/undertow/undertow-2.0/src/main/java/datadog/trace/instrumentation/undertow/HttpRequestParserInstrumentation.java	Reorder scope.close() before span.finish() in request-parse cleanup.
dd-java-agent/instrumentation/twilio-0.0.1/src/main/java/datadog/trace/instrumentation/twilio/TwilioAsyncInstrumentation.java	Close scope earlier and finish span after async/error handling setup.
dd-java-agent/instrumentation/tibco-businessworks/tibco-businessworks-6.5/src/main/java/datadog/trace/instrumentation/tibcobw6/BehaviorInstrumentation.java	Close scope before finishing/stashing span for later completion.
dd-java-agent/instrumentation/synapse-3.0/src/main/java/datadog/trace/instrumentation/synapse3/SynapseServerWorkerInstrumentation.java	Close scope up-front in response handling and finish span conditionally.
dd-java-agent/instrumentation/synapse-3.0/src/main/java/datadog/trace/instrumentation/synapse3/SynapseServerInstrumentation.java	Close scope up-front in response handling and finish span conditionally.
dd-java-agent/instrumentation/synapse-3.0/src/main/java/datadog/trace/instrumentation/synapse3/SynapseClientInstrumentation.java	Close scope up-front in response handling and finish span conditionally.
dd-java-agent/instrumentation/servlet/javax-servlet/javax-servlet-3.0/src/main/java/datadog/trace/instrumentation/servlet3/Servlet3Advice.java	Close scope earlier in stopSpan advice (before response tagging).
dd-java-agent/instrumentation/rxjava/rxjava-3.0/src/test/java/testdog/trace/instrumentation/rxjava3/RxJava3Test.java	Test helper aligns ordering: scope.close() before span.finish().
dd-java-agent/instrumentation/rs/jax-rs/jax-rs-annotations/jax-rs-annotations-2.0/src/main/java/datadog/trace/instrumentation/jaxrs2/JaxRsAnnotationsInstrumentation.java	Close scope before span finish / async suspend checks.
dd-java-agent/instrumentation/rs/jax-rs/jax-rs-annotations/jax-rs-annotations-2.0/src/main/java/datadog/trace/instrumentation/jaxrs2/DefaultRequestContextInstrumentation.java	Reorder to close scope before finishing span.
dd-java-agent/instrumentation/rs/jakarta-rs-annotations-3.0/src/main/java/datadog/trace/instrumentation/jakarta3/JakartaRsAnnotationsInstrumentation.java	Close scope before span finish / async suspend checks.
dd-java-agent/instrumentation/rs/jakarta-rs-annotations-3.0/src/main/java/datadog/trace/instrumentation/jakarta3/DefaultRequestContextInstrumentation.java	Reorder to close scope before finishing span.
dd-java-agent/instrumentation/rediscala-1.8/src/main/java/datadog/trace/instrumentation/rediscala/RediscalaInstrumentation.java	Close scope earlier; span finished inline or via completion handler.
dd-java-agent/instrumentation/rabbitmq-amqp-2.7/src/main/java/datadog/trace/instrumentation/rabbitmq/amqp/RabbitDecorator.java	Close receiving scope before finishing span (including E2E finish).
dd-java-agent/instrumentation/quartz-2.0/src/main/java/datadog/trace/instrumentation/quartz/QuartzSchedulingInstrumentation.java	Reorder to close scope before finishing span.
dd-java-agent/instrumentation/play-ws/play-ws-2.1/src/main/java/datadog/trace/instrumentation/playws21/PlayWSClientInstrumentation.java	Close scope before error tagging/finish; async spans finish elsewhere.
dd-java-agent/instrumentation/play-ws/play-ws-2.0/src/main/java/datadog/trace/instrumentation/playws2/PlayWSClientInstrumentation.java	Close scope before error tagging/finish; async spans finish elsewhere.
dd-java-agent/instrumentation/play-ws/play-ws-1.0/src/main/java/datadog/trace/instrumentation/playws1/PlayWSClientInstrumentation.java	Close scope before error tagging/finish; async spans finish elsewhere.
dd-java-agent/instrumentation/pekko/pekko-http-1.0/src/main/java/datadog/trace/instrumentation/pekkohttp/PekkoHttpSingleRequestInstrumentation.java	Close scope before finishing span / attaching async completion.
dd-java-agent/instrumentation/opensearch/opensearch-transport-1.0/src/main/java/datadog/trace/instrumentation/opensearch/OpensearchTransportClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/opensearch/opensearch-rest-1.0/src/main/java/datadog/trace/instrumentation/opensearch/OpensearchRestClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/lettuce/lettuce-4.0/src/main/java/datadog/trace/instrumentation/lettuce4/InstrumentationPoints.java	Close scope early; span may finish inline or via async handling.
dd-java-agent/instrumentation/kafka/kafka-clients-3.8/src/main/java17/datadog/trace/instrumentation/kafka_clients38/RecordsAdvice.java	Close scope before finishing span after tagging records count.
dd-java-agent/instrumentation/kafka/kafka-clients-0.11/src/main/java/datadog/trace/instrumentation/kafka_clients/KafkaConsumerInfoInstrumentation.java	Close scope before finishing span after tagging records count.
dd-java-agent/instrumentation/jetty/jetty-server/jetty-server-9.0/src/main/java/datadog/trace/instrumentation/jetty9/ServerHandleInstrumentation.java	Close scope before conditional finish / async listener path.
dd-java-agent/instrumentation/jetty/jetty-server/jetty-server-7.6/src/main/java/datadog/trace/instrumentation/jetty76/ServerHandleInstrumentation.java	Close scope before conditional finish / async listener path.
dd-java-agent/instrumentation/jetty/jetty-server/jetty-server-7.0/src/main/java/datadog/trace/instrumentation/jetty70/ServerHandleInstrumentation.java	Close scope before conditional finish / async listener path.
dd-java-agent/instrumentation/jetty/jetty-server/jetty-server-10.0/src/main/java11/datadog/trace/instrumentation/jetty10/ServerHandleAdvice.java	Close scope before conditional finish / request cleanup.
dd-java-agent/instrumentation/java/java-net/java-net-11.0/src/main/java11/datadog/trace/instrumentation/httpclient/SendAsyncAdvice.java	Close scope before error tagging/finish; async completion keeps span.
dd-java-agent/instrumentation/ignite-2.0/src/main/java/datadog/trace/instrumentation/ignite/v2/cache/IgniteCacheAsyncInstrumentation.java	Close scope early; finish span on sync error or via async callback.
dd-java-agent/instrumentation/hibernate/hibernate-common/src/main/java/datadog/trace/instrumentation/hibernate/SessionMethodUtils.java	Close scope and clear state before conditional span finish.
dd-java-agent/instrumentation/hazelcast/hazelcast-4.0/src/main/java/datadog/trace/instrumentation/hazelcast4/InvocationAdvice.java	Close scope early; sync error finishes span, async finishes later.
dd-java-agent/instrumentation/hazelcast/hazelcast-4.0/src/main/java/datadog/trace/instrumentation/hazelcast4/ClientListenerInstrumentation.java	Close scope/reset call depth earlier; finish span in finally.
dd-java-agent/instrumentation/hazelcast/hazelcast-3.9/src/main/java/datadog/trace/instrumentation/hazelcast39/ClientInvocationInstrumentation.java	Close scope early; sync error finishes span, async finishes later.
dd-java-agent/instrumentation/hazelcast/hazelcast-3.6/src/main/java/datadog/trace/instrumentation/hazelcast36/DistributedObjectInstrumentation.java	Close scope early; sync error finishes span, async finishes later.
dd-java-agent/instrumentation/grpc-1.5/src/main/java/datadog/trace/instrumentation/grpc/client/MessagesAvailableInstrumentation.java	Close scope before finishing span in message-availability advice.
dd-java-agent/instrumentation/grizzly/grizzly-client-1.9/src/main/java/datadog/trace/instrumentation/grizzly/client/AsyncHttpClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/grizzly/grizzly-2.0/src/main/java/datadog/trace/instrumentation/grizzly/GrizzlyHttpHandlerInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/google-pubsub-1.116/src/main/java/datadog/trace/instrumentation/googlepubsub/PublisherInstrumentation.java	Close scope before finishing span in publisher exit advice.
dd-java-agent/instrumentation/google-http-client-1.19/src/main/java/datadog/trace/instrumentation/googlehttpclient/GoogleHttpClientInstrumentation.java	Close scope earlier; perform decoration and finish span after close.
dd-java-agent/instrumentation/finatra-2.9/src/main/java/datadog/trace/instrumentation/finatra/Listener.java	Close scope before finishing span in success/failure callbacks.
dd-java-agent/instrumentation/finatra-2.9/src/main/java/datadog/trace/instrumentation/finatra/FinatraInstrumentation.java	Close scope before finishing span on throwable path.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-transport/elasticsearch-transport-7.3/src/main/java/datadog/trace/instrumentation/elasticsearch7_3/Elasticsearch73TransportClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-transport/elasticsearch-transport-6.0/src/main/java/datadog/trace/instrumentation/elasticsearch6/Elasticsearch6TransportClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-transport/elasticsearch-transport-5.3/src/main/java/datadog/trace/instrumentation/elasticsearch5_3/Elasticsearch53TransportClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-transport/elasticsearch-transport-5.0/src/main/java/datadog/trace/instrumentation/elasticsearch5/Elasticsearch5TransportClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-transport/elasticsearch-transport-2.0/src/main/java/datadog/trace/instrumentation/elasticsearch2/Elasticsearch2TransportClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-rest/elasticsearch-rest-7.0/src/main/java/datadog/trace/instrumentation/elasticsearch7/Elasticsearch7RestClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-rest/elasticsearch-rest-6.4/src/main/java/datadog/trace/instrumentation/elasticsearch6_4/Elasticsearch6RestClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/elasticsearch/elasticsearch-rest/elasticsearch-rest-5.0/src/main/java/datadog/trace/instrumentation/elasticsearch5/Elasticsearch5RestClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/datanucleus-4.0.5/src/main/java/datadog/trace/instrumentation/datanucleus/JDOTransactionInstrumentation.java	Reorder to close scope before finishing span.
dd-java-agent/instrumentation/datanucleus-4.0.5/src/main/java/datadog/trace/instrumentation/datanucleus/JDOQueryInstrumentation.java	Reorder to close scope before finishing span.
dd-java-agent/instrumentation/datanucleus-4.0.5/src/main/java/datadog/trace/instrumentation/datanucleus/ExecutionContextInstrumentation.java	Reorder to close scope before finishing span in multiple end-method advices.
dd-java-agent/instrumentation/cucumber-5.4/src/main/java/datadog/trace/instrumentation/cucumber/CucumberStepDecorator.java	Reorder to close scope before finishing step span.
dd-java-agent/instrumentation/cics-9.1/src/main/java/datadog/trace/instrumentation/cics/JavaGatewayInterfaceInstrumentation.java	Reorder to close scope before finishing span.
dd-java-agent/instrumentation/cics-9.1/src/main/java/datadog/trace/instrumentation/cics/ECIInteractionInstrumentation.java	Close scope before finishing span; avoid repeated scope.span() calls.
dd-java-agent/instrumentation/aws-java/aws-java-lambda-handler-1.2/src/main/java/datadog/trace/instrumentation/aws/v1/lambda/LambdaHandlerInstrumentation.java	Close scope earlier; perform final tagging/notifications then finish span.
dd-java-agent/instrumentation/armeria/armeria-grpc-0.84/src/main/java/datadog/trace/instrumentation/armeria/grpc/client/ClientCallImplInstrumentation.java	Close scope before on-close decoration and finishing span.
dd-java-agent/instrumentation/apache-httpclient/apache-httpclient-5.0/src/main/java/datadog/trace/instrumentation/apachehttpclient5/ApacheHttpAsyncClientInstrumentation.java	Close scope early; error path finishes span inline.
dd-java-agent/instrumentation/akka/akka-http/akka-http-10.6/src/main/java11/datadog/trace/instrumentation/akkahttp106/SingleRequestAdvice.java	Close scope before error tagging/finish; async completion handles span.
dd-java-agent/instrumentation/akka/akka-http/akka-http-10.0/src/main/java/datadog/trace/instrumentation/akkahttp/AkkaHttpSingleRequestInstrumentation.java	Close scope before error tagging/finish; async completion handles span.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: adb2c9408a

ℹ️ 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-datadog-prod-us1]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 69.73% (+12.55%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 22a2d0e | Docs | Datadog PR Page | Give us feedback!}

[dd-octo-sts]

🟡 Java Benchmark SLOs — Performance SLO warning (near threshold)

Suite	Status
Startup	🟡 warning

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.99 s	[-0.4%; +1.3%] (no difference)
startup:insecure-bank:tracing:Agent	12.85 s	13.06 s	[-2.6%; -0.7%] (maybe better)
startup:petclinic:appsec:Agent	17.02 s	16.67 s	[+1.1%; +3.2%] (significantly worse)
startup:petclinic:iast:Agent	16.89 s	16.97 s	[-1.4%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	16.56 s	16.97 s	[-3.8%; -1.2%] (significantly better)
startup:petclinic:sca:Agent	17.00 s	16.78 s	[+0.3%; +2.4%] (maybe worse)
startup:petclinic:tracing:Agent	16.16 s	16.25 s	[-1.6%; +0.4%] (no difference)

Commit: 22a2d0ee · 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]

Kafka / producer-benchmark

Parameters

	Baseline	Candidate
baseline_or_candidate	baseline	candidate
git_branch	master	mcculls/close-before-finish
git_commit_date	1784204168	1784204623
git_commit_sha	48bc030	22a2d0e

See matching parameters

	Baseline	Candidate
ci_job_date	1784205832	1784205832
ci_job_id	1865043288	1865043288
ci_pipeline_id	124990600	124990600
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/producer-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/producer-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 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

[pr-commenter]

Kafka / consumer-benchmark

Parameters

	Baseline	Candidate
baseline_or_candidate	baseline	candidate
git_branch	master	mcculls/close-before-finish
git_commit_date	1784204168	1784204623
git_commit_sha	48bc030	22a2d0e

See matching parameters

	Baseline	Candidate
ci_job_date	1784205849	1784205849
ci_job_id	1865043290	1865043290
ci_pipeline_id	124990600	124990600
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 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

[mcculls]

@codex review

[Copilot]

Pull request overview

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9308e7ce86

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

[mcculls]

@codex review

[datadog-datadog-prod-us1]

More details

The PR implements the documented span lifecycle order across 60+ instrumentations, moving scope.close() before span.finish() while keeping beforeFinish() calls first. This aligns with the documentation which requires beforeFinish to execute while the scope is active (for IAST/AppSec callbacks). The reordering is safe: span objects remain valid after scope close, and async callbacks properly activate parent scopes. No behavioral regressions detected from the code review.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

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

[PerfectSlayer]

Looking good. I marked a bunch of places where the pattern could be more consistent (cases with async error handling for example) and maybe easier to read - at the cost of scope close call duplication (but some other instrumentations adopted this pattern already).
Not blocking, only suggesting :)

[mcculls]

Decided to keep the existing pattern of having the try-finally outermost for the following reasons (AI summary)

The general problem with the "conditional try/finally" shape is that it makes the safety invariant depend on which branch is taken, rather than being unconditional:

• Two scope.close() call sites split across branches means anyone touching the "safe" branch later has to remember to move scope.close() back under a try/finally if they add anything risky — nothing enforces that.
• Any code that runs before the branch decision (like self.isFinished(...), or evaluating a condition that can throw) is completely unprotected.
• It reads harder too — scope.close() appearing at two different indentation levels in the same method is a real code-smell signal that the invariant isn't structurally guaranteed anymore.

Whereas a single finally that always closes the scope, with span.finish() gated by a boolean/condition inside that finally — keeps the guarantee structural rather than something a future editor has to preserve by convention. That's a strictly stronger property for something as leak-sensitive as scope lifecycle.

[dd-octo-sts]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-07-17 13:23:45 UTC ℹ️ Start processing command /merge

---

2026-07-17 13:23:51 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2h (p90).

---

2026-07-17 14:28:39 UTC ℹ️ MergeQueue: This merge request was merged