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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mcculls

AGENTS.md

@@ -63,6 +63,7 @@ docs/                     Developer documentation (see below)
 - **Forked tests**: Use `ForkedTest` suffix when tests need a separate JVM
 - **Flaky tests**: Annotate with `@Flaky` — they are skipped in CI by default
 - **Instrumentation one-shot methods**: Never extract the return values of `triggerClasses()`, `contextStore()`, `classLoaderMatcher()`, or `methodAdvice()` into static constants. These are called once by the framework — extracting to a constant adds constant-pool bloat with no benefit.
+- **Scope lifecycle order**: Always decorator calls → `scope.close()` → `span.finish()`. Closing the scope first restores the parent active span, breaking IAST/AppSec callbacks in `beforeFinish` that rely on `AgentTracer.activeSpan()`.
 
 ## PR conventions
 

dd-java-agent/instrumentation/akka/akka-http/akka-http-10.0/src/main/java/datadog/trace/instrumentation/akkahttp/AkkaHttpSingleRequestInstrumentation.java

@@ -98,12 +98,13 @@ public static void methodExit(
 
       if (throwable == null) {
         responseFuture.onComplete(new OnCompleteHandler(span), thiz.system().dispatcher());
+        scope.close();
       } else {
         DECORATE.onError(span, throwable);
         DECORATE.beforeFinish(span);
+        scope.close();
         span.finish();
       }
-      scope.close();
     }
   }
 

dd-java-agent/instrumentation/akka/akka-http/akka-http-10.6/src/main/java11/datadog/trace/instrumentation/akkahttp106/SingleRequestAdvice.java

@@ -44,11 +44,12 @@ public static void methodExit(
     if (throwable == null) {
       responseFuture.onComplete(
           new AkkaHttpClientHelpers.OnCompleteHandler(span), thiz.system().dispatcher());
+      scope.close();
     } else {
       DECORATE.onError(span, throwable);
       DECORATE.beforeFinish(span);
+      scope.close();
       span.finish();
     }
-    scope.close();
   }
 }

dd-java-agent/instrumentation/apache-httpclient/apache-httpclient-5.0/src/main/java/datadog/trace/instrumentation/apachehttpclient5/ApacheHttpAsyncClientInstrumentation.java

@@ -142,15 +142,17 @@ public static void methodExit(
       if (scope == null) {
         return;
       }
+      final AgentSpan span = scope.span();
       try {
         if (throwable != null) {
-          final AgentSpan span = scope.span();
           DECORATE.onError(span, throwable);
           DECORATE.beforeFinish(span);
-          span.finish();
         }
       } finally {
         scope.close();
+        if (throwable != null) {
+          span.finish();
+        }
       }
     }
   }

dd-java-agent/instrumentation/armeria/armeria-grpc-0.84/src/main/java/datadog/trace/instrumentation/armeria/grpc/client/ClientCallImplInstrumentation.java

@@ -122,12 +122,14 @@ public static void after(
         @Advice.Thrown Throwable error,
         @Advice.Local("$$ddSpan") AgentSpan span)
         throws Throwable {
+      if (null != error && null != span) {
+        DECORATE.onError(span, error);
+        DECORATE.beforeFinish(span);
+      }
       if (null != scope) {
         scope.close();
       }
       if (null != error && null != span) {
-        DECORATE.onError(span, error);
-        DECORATE.beforeFinish(span);
         span.finish();
         throw error;
       }
@@ -210,8 +212,8 @@ public static void closeObserver(
         @Advice.Enter AgentScope scope, @Advice.Argument(0) Status status) {
       if (null != scope) {
         DECORATE.onClose(scope.span(), status);
-        scope.span().finish();
         scope.close();
+        scope.span().finish();
       }
     }
   }
@@ -238,15 +240,17 @@ public static void closeObserver(
         @Advice.Argument(0) Status status,
         @Advice.FieldValue("closed") boolean closed) {
       if (null != scope) {
+        AgentSpan span = null;
         if (closed) {
-          AgentSpan span =
-              InstrumentationContext.get(ClientCall.class, AgentSpan.class).remove(call);
+          span = InstrumentationContext.get(ClientCall.class, AgentSpan.class).remove(call);
           if (span != null) {
             DECORATE.onClose(span, status);
-            span.finish();
           }
         }
         scope.close();
+        if (span != null) {
+          span.finish();
+        }
       }
     }
   }
@@ -268,8 +272,8 @@ public static AgentScope before() {
     @Advice.OnMethodExit(onThrowable = Throwable.class)
     public static void after(@Advice.Enter AgentScope scope) {
       if (null != scope) {
-        scope.span().finish();
         scope.close();
+        scope.span().finish();
       }
     }
   }

dd-java-agent/instrumentation/aws-java/aws-java-lambda-handler-1.2/src/main/java/datadog/trace/instrumentation/aws/v1/lambda/LambdaHandlerInstrumentation.java

@@ -119,15 +119,12 @@ static void exit(
 
       CallDepthThreadLocalMap.reset(RequestHandler.class);
 
+      final AgentSpan span = scope.span();
       try {
-        final AgentSpan span = scope.span();
-        if (throwable != null) {
-          span.addThrowable(throwable);
-        }
-        String lambdaRequestId = awsContext.getAwsRequestId();
-
         if (throwable == null) {
           AgentTracer.get().notifyAppSecEnd(span, result);
+        } else {
+          span.addThrowable(throwable);
         }
         // Force the resource name back to the literal placeholder marker right
         // before finish so that the Datadog Lambda Extension's filter
@@ -144,10 +141,11 @@ static void exit(
         // and the HTTP/JAX-RS instrumentation will already have written
         // HTTP_FRAMEWORK_ROUTE (3) by this point.
         span.setResourceName(INVOCATION_SPAN_NAME, ResourceNamePriorities.TAG_INTERCEPTOR);
-        span.finish();
-        AgentTracer.get().notifyExtensionEnd(span, result, null != throwable, lambdaRequestId);
       } finally {
         scope.close();
+        span.finish();
+        AgentTracer.get()
+            .notifyExtensionEnd(span, result, null != throwable, awsContext.getAwsRequestId());
       }
     }
   }

dd-java-agent/instrumentation/cics-9.1/src/main/java/datadog/trace/instrumentation/cics/ECIInteractionInstrumentation.java

@@ -50,10 +50,11 @@ public static void exit(
       CallDepthThreadLocalMap.decrementCallDepth(ECIInteraction.class);
 
       if (null != scope) {
-        DECORATE.onError(scope.span(), throwable);
-        DECORATE.beforeFinish(scope.span());
-        scope.span().finish();
+        AgentSpan span = scope.span();
+        DECORATE.onError(span, throwable);
+        DECORATE.beforeFinish(span);
         scope.close();
+        span.finish();
       }
     }
   }

dd-java-agent/instrumentation/cics-9.1/src/main/java/datadog/trace/instrumentation/cics/JavaGatewayInterfaceInstrumentation.java

@@ -71,8 +71,8 @@ public static void exit(
 
       DECORATE.onError(span, throwable);
       DECORATE.beforeFinish(span);
-      span.finish();
       scope.close();
+      span.finish();
     }
   }
 }

dd-java-agent/instrumentation/cucumber-5.4/src/main/java/datadog/trace/instrumentation/cucumber/CucumberStepDecorator.java

@@ -44,7 +44,7 @@ public AgentScope onStepStart(StepDefinition step, Object[] arguments) {
   public void onStepFinish(AgentScope scope) {
     AgentSpan span = scope.span();
     beforeFinish(span);
-    span.finish();
     scope.close();
+    span.finish();
   }
 }

dd-java-agent/instrumentation/datanucleus-4.0.5/src/main/java/datadog/trace/instrumentation/datanucleus/ExecutionContextInstrumentation.java

@@ -97,8 +97,8 @@ public static void endMethod(
       DECORATE.onError(span, throwable);
       DECORATE.beforeFinish(span);
 
-      span.finish();
       scope.close();
+      span.finish();
     }
   }
 
@@ -133,8 +133,8 @@ public static void endMethod(
       DECORATE.onOperation(span, entity);
       DECORATE.beforeFinish(span);
 
-      span.finish();
       scope.close();
+      span.finish();
     }
   }
 
@@ -164,8 +164,8 @@ public static void endMethod(
       DECORATE.onError(span, throwable);
       DECORATE.beforeFinish(span);
 
-      span.finish();
       scope.close();
+      span.finish();
     }
   }
 
@@ -195,8 +195,8 @@ public static void endMethod(
       DECORATE.onError(span, throwable);
       DECORATE.beforeFinish(span);
 
-      span.finish();
       scope.close();
+      span.finish();
     }
   }
 }