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.69%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: e4dfb05 | Docs | Datadog PR Page | 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	13.93 s	13.93 s	[-0.7%; +0.6%] (no difference)
startup:insecure-bank:tracing:Agent	12.86 s	12.95 s	[-1.6%; +0.1%] (no difference)
startup:petclinic:appsec:Agent	16.88 s	16.57 s	[+0.6%; +3.0%] (maybe worse)
startup:petclinic:iast:Agent	16.41 s	16.89 s	[-7.3%; +1.7%] (no difference)
startup:petclinic:profiling:Agent	16.68 s	16.68 s	[-1.4%; +1.3%] (no difference)
startup:petclinic:sca:Agent	16.85 s	16.30 s	[-1.3%; +8.1%] (no difference)
startup:petclinic:tracing:Agent	16.12 s	16.10 s	[-0.9%; +1.2%] (no difference)

Commit: e4dfb057 · 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	1783977597	1783977671
git_commit_sha	f2121a0	e4dfb05

See matching parameters

	Baseline	Candidate
ci_job_date	1783978815	1783978815
ci_job_id	1856221874	1856221874
ci_pipeline_id	124430300	124430300
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	unsure [-56774.684op/s; -4798.255op/s] or [-3.090%; -0.261%]
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	1783977597	1783977671
git_commit_sha	f2121a0	e4dfb05

See matching parameters

	Baseline	Candidate
ci_job_date	1783978853	1783978853
ci_job_id	1856221878	1856221878
ci_pipeline_id	124430300	124430300
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	unsure [+593.197op/s; +12630.940op/s] or [+0.197%; +4.203%]
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}