Switch instrumentations over to ContextScope, remove AgentScope

.agents/skills/apm-integrations/references/advice-class.md

@@ -23,7 +23,7 @@
 Enter method:
 1. `AgentSpan span = startSpan(DECORATE.operationName(), ...)`
 2. `DECORATE.afterStart(span)` + set domain-specific tags
-3. `AgentScope scope = activateSpan(span)` — return or store via `@Advice.Local`
+3. `ContextScope scope = activateSpan(span)` — return or store via `@Advice.Local`
 
 Exit method:
 4. `DECORATE.onError(span, throwable)` — only if throwable is non-null
@@ -39,10 +39,10 @@ The `onThrowable = Throwable.class` attribute on `@Advice.OnMethodExit` controls
 // Standard pattern — exit fires whether the target method returned or threw
 @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
 public static void exit(
-    @Advice.Enter final AgentScope scope,
+    @Advice.Enter final ContextScope scope,
     @Advice.Thrown final Throwable thrown) {
   if (scope != null) {
-    AgentSpan span = scope.span();
+    AgentSpan span = spanFromScope(scope);
     DECORATE.onError(span, thrown);
     DECORATE.beforeFinish(span);
     scope.close();
@@ -147,7 +147,7 @@ if (span != null && routeMatch != null) {
 }
 ```
 
-For route-only enrichers: no `AgentScope`, no `startSpan()`, no `decorator.afterStart()`. This rule does NOT apply to standalone HTTP clients (which own their own span identity) or to handler-owning frameworks like JAX-RS / Ratpack (which legitimately create controller spans).
+For route-only enrichers: no `ContextScope`, no `startSpan()`, no `decorator.afterStart()`. This rule does NOT apply to standalone HTTP clients (which own their own span identity) or to handler-owning frameworks like JAX-RS / Ratpack (which legitimately create controller spans).
 
 ### Advice classes must not declare non-constant static fields
 

ARCHITECTURE.md

@@ -157,7 +157,8 @@ Core tracing abstractions:
 
 - `AgentTracer` — Static tracer facade. Instrumentations call `AgentTracer.startSpan()`,
   `AgentTracer.activateSpan()`, etc.
-- `AgentSpan` / `AgentScope` / `AgentSpanContext` — Internal span/scope/context interfaces.
+- `AgentSpan` / `AgentSpanContext` — Internal span/context interfaces. Scopes use the tracer-agnostic
+  `ContextScope` (`components/context`); `AgentSpan.fromScope(scope)` extracts the active span from one.
 - `AgentPropagation` — Context propagation interfaces (`Getter`, `Setter`) that instrumentations
   implement to inject/extract trace context from framework-specific carriers (HTTP headers, message
   properties, etc.).

buildSrc/src/main/kotlin/datadog/gradle/plugin/config/ConfigInversionLinter.kt

@@ -89,7 +89,7 @@ private fun registerLogEnvVarUsages(target: Project, extension: SupportedTracerC
     val javaFiles = target.fileTree(target.projectDir) {
       include("**/src/main/java/**/*.java")
       exclude("**/build/**", "**/dd-smoke-tests/**")
-      // Undertow uses DD_UNDERTOW_CONTINUATION as a legacy key to store an AgentScope. It is not related to an environment variable
+      // Undertow uses DD_UNDERTOW_CONTINUATION as a legacy key to store a ContextContinuation. It is not related to an environment variable
       exclude("dd-java-agent/instrumentation/undertow/undertow-common/src/main/java/datadog/trace/instrumentation/undertow/UndertowDecorator.java")
     }
     inputs.files(javaFiles)

dd-java-agent/agent-aiguard/src/test/java/com/datadog/aiguard/AIGuardInternalRedactionTest.java

@@ -21,14 +21,14 @@
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 
+import datadog.context.ContextScope;
 import datadog.trace.api.aiguard.AIGuard.AIGuardAbortError;
 import datadog.trace.api.aiguard.AIGuard.AIGuardClientError;
 import datadog.trace.api.aiguard.AIGuard.Evaluation;
 import datadog.trace.api.aiguard.AIGuard.Message;
 import datadog.trace.api.aiguard.AIGuard.Options;
 import datadog.trace.api.telemetry.MetricCollector;
 import datadog.trace.api.telemetry.WafMetricCollector;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.test.junit.utils.config.WithConfigExtension;
@@ -86,7 +86,7 @@ void setUp() {
     lenient().when(builder.start()).thenReturn(span);
     final AgentTracer.TracerAPI tracer = mock(AgentTracer.TracerAPI.class);
     lenient().when(tracer.buildSpan(anyString(), anyString())).thenReturn(builder);
-    lenient().when(tracer.activateSpan(any())).thenReturn(mock(AgentScope.class));
+    lenient().when(tracer.activateSpan(any())).thenReturn(mock(ContextScope.class));
     AgentTracer.forceRegister(tracer);
   }
 

dd-java-agent/agent-bootstrap/src/main/java/datadog/trace/bootstrap/instrumentation/api/Java8BytecodeBridge.java

@@ -1,6 +1,7 @@
 package datadog.trace.bootstrap.instrumentation.api;
 
 import datadog.context.Context;
+import datadog.context.ContextScope;
 
 /**
  * A helper for accessing methods that rely on new Java 8 bytecode features such as calling a static
@@ -38,6 +39,13 @@ public static AgentSpan spanFromContext(Context context) {
     return AgentSpan.fromContext(context);
   }
 
+  /**
+   * @see AgentSpan#fromScope(ContextScope)
+   */
+  public static AgentSpan spanFromScope(ContextScope scope) {
+    return AgentSpan.fromScope(scope);
+  }
+
   /**
    * @see Baggage#fromContext(Context)
    */

dd-java-agent/agent-bootstrap/src/main/java/datadog/trace/bootstrap/instrumentation/decorator/BaseDecorator.java

@@ -10,7 +10,6 @@
 import datadog.trace.api.Functions;
 import datadog.trace.api.TagMap;
 import datadog.trace.api.cache.QualifiedClassNameCache;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.ErrorPriorities;
 import datadog.trace.bootstrap.instrumentation.api.Tags;
@@ -148,12 +147,6 @@ public final void beforeFinish(final Context context) {
 
   protected void doBeforeFinish(final Context context) {}
 
-  public final void onError(@Nullable final AgentScope scope, @Nullable final Throwable throwable) {
-    if (scope != null) {
-      onError(scope.span(), throwable);
-    }
-  }
-
   public final void onError(@Nullable final AgentSpan span, @Nullable final Throwable throwable) {
     onError(span, throwable, ErrorPriorities.DEFAULT);
   }

dd-java-agent/agent-debugger/src/main/java/com/datadog/debugger/agent/DebuggerTracer.java

@@ -3,9 +3,9 @@
 import static datadog.trace.bootstrap.instrumentation.api.AgentTracer.NOOP_TRACER;
 
 import com.datadog.debugger.sink.ProbeStatusSink;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.debugger.DebuggerContext;
 import datadog.trace.bootstrap.debugger.DebuggerSpan;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 
@@ -38,19 +38,19 @@ public DebuggerSpan createSpan(String encodedProbeId, String resourceName, Strin
         dynamicSpan.setTag(tag.substring(0, idx), tag.substring(idx + 1));
       }
     }
-    AgentScope scope = tracerAPI.activateManualSpan(dynamicSpan);
+    ContextScope scope = tracerAPI.activateManualSpan(dynamicSpan);
     return new DebuggerSpanImpl(dynamicSpan, scope, probeStatusSink, encodedProbeId);
   }
 
   static class DebuggerSpanImpl implements DebuggerSpan {
     final AgentSpan underlyingSpan;
-    final AgentScope currentScope;
+    final ContextScope currentScope;
     final ProbeStatusSink probeStatusSink;
     final String encodedProbeId;
 
     public DebuggerSpanImpl(
         AgentSpan underlyingSpan,
-        AgentScope currentScope,
+        ContextScope currentScope,
         ProbeStatusSink probeStatusSink,
         String encodedProbeId) {
       this.underlyingSpan = underlyingSpan;

dd-java-agent/agent-debugger/src/test/java/com/datadog/debugger/agent/DebuggerTracerTest.java

@@ -38,9 +38,11 @@ public void createSpan() {
     assertEquals(0, underlyingSpan.getDurationNano());
     assertEquals(
         "dd.dynamic.span",
-        ((DebuggerTracer.DebuggerSpanImpl) span).currentScope.span().getSpanName());
+        AgentSpan.fromScope(((DebuggerTracer.DebuggerSpanImpl) span).currentScope).getSpanName());
     assertEquals(
-        "a-span", ((DebuggerTracer.DebuggerSpanImpl) span).currentScope.span().getResourceName());
+        "a-span",
+        AgentSpan.fromScope(((DebuggerTracer.DebuggerSpanImpl) span).currentScope)
+            .getResourceName());
     span.finish();
     assertNotEquals(0, underlyingSpan.getDurationNano());
     verify(probeStatusSink).addEmitting(eq(SPAN_ID.getEncodedId()));

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/CapturedSnapshot29.java

@@ -1,7 +1,7 @@
 package com.datadog.debugger;
 
 import datadog.trace.agent.tooling.TracerInstaller;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.core.CoreTracer;

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/CodeOrigin01.java

@@ -2,7 +2,7 @@
 
 import com.datadog.debugger.origin.CodeOrigin;
 import datadog.trace.bootstrap.debugger.DebuggerContext;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -18,7 +18,7 @@ public class CodeOrigin01 {
 
   public static int main(String arg) throws ReflectiveOperationException {
     AgentSpan span = newSpan("main");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     marker();
     captureCodeOrigin(CodeOrigin01.class.getDeclaredMethod("main", String.class), true);
     if (arg.equals("debug_1")) {
@@ -38,7 +38,7 @@ public static int main(String arg) throws ReflectiveOperationException {
   @CodeOrigin
   public static void fullTrace() throws NoSuchMethodException {
     AgentSpan span = newSpan("entry");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     entry();
     span.finish();
     scope.close();

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/CodeOrigin02.java

@@ -1,7 +1,7 @@
 package com.datadog.debugger;
 
 import datadog.trace.bootstrap.debugger.DebuggerContext;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -14,7 +14,7 @@ public class CodeOrigin02 {
 
   public static int main(String arg) throws ReflectiveOperationException {
     AgentSpan span = newSpan("main");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     if (arg.equals("debug_1")) {
       ((DDSpan) span.getLocalRootSpan()).setTag("_dd.p.debug", "1");
     } else if (arg.equals("debug_0")) {
@@ -31,7 +31,7 @@ public static int main(String arg) throws ReflectiveOperationException {
 
   private static void fullTrace() throws NoSuchMethodException {
     AgentSpan span = newSpan("entry");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     entry();
     span.finish();
     scope.close();

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/CodeOrigin03.java

@@ -1,7 +1,7 @@
 package com.datadog.debugger;
 
 import datadog.trace.bootstrap.debugger.DebuggerContext;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -16,7 +16,7 @@ public class CodeOrigin03 {
 
   public static int main(String arg) throws ReflectiveOperationException {
     AgentSpan span = newSpan("main");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     if (arg.equals("debug_1")) {
       ((DDSpan) span.getLocalRootSpan()).setTag("_dd.p.debug", "1");
     } else if (arg.equals("debug_0")) {
@@ -33,7 +33,7 @@ public static int main(String arg) throws ReflectiveOperationException {
 
   private static void fullTrace() throws NoSuchMethodException {
     AgentSpan span = newSpan("entry");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     marker();
     DebuggerContext.captureCodeOrigin(true);
     entry();

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/CodeOrigin04.java

@@ -1,6 +1,6 @@
 package com.datadog.debugger;
 
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -21,7 +21,7 @@ private static void doExit(int level) {
       doExit(level - 1);
     } else {
       AgentSpan span;
-      AgentScope scope;
+      ContextScope scope;
       span = newSpan("exit");
       scope = tracerAPI.activateManualSpan(span);
       exit();

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/CodeOrigin05.java

@@ -1,6 +1,6 @@
 package com.datadog.debugger;
 
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -13,7 +13,7 @@ public class CodeOrigin05 {
 
   public static int main(String arg) throws ReflectiveOperationException {
     AgentSpan span = newSpan("main");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     if (arg.equals("debug_1")) {
       ((DDSpan) span.getLocalRootSpan()).setTag("_dd.p.debug", "1");
     } else if (arg.equals("debug_0")) {
@@ -30,7 +30,7 @@ public static int main(String arg) throws ReflectiveOperationException {
 
   private static void fullTrace() throws NoSuchMethodException {
     AgentSpan span = newSpan("entry");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     entry();
     span.finish();
     scope.close();

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/TriggerProbe01.java

@@ -1,6 +1,6 @@
 package com.datadog.debugger;
 
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -12,7 +12,7 @@ public class TriggerProbe01 {
 
   public static int main(String arg) throws ReflectiveOperationException {
     AgentSpan span = newSpan("main");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
 
     fullTrace();
 
@@ -24,7 +24,7 @@ public static int main(String arg) throws ReflectiveOperationException {
 
   private static void fullTrace() throws NoSuchMethodException {
     AgentSpan span = newSpan("entry");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     entry();
     span.finish();
     scope.close();

dd-java-agent/agent-debugger/src/test/resources/com/datadog/debugger/TriggerProbe02.java

@@ -1,6 +1,6 @@
 package com.datadog.debugger;
 
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
+import datadog.context.ContextScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer.TracerAPI;
@@ -12,7 +12,7 @@ public class TriggerProbe02 {
 
   public static int main(Integer value) throws ReflectiveOperationException {
     AgentSpan span = newSpan("main");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
 
     fullTrace(value);
 
@@ -24,7 +24,7 @@ public static int main(Integer value) throws ReflectiveOperationException {
 
   private static void fullTrace(int value) throws NoSuchMethodException {
     AgentSpan span = newSpan("entry");
-    AgentScope scope = tracerAPI.activateManualSpan(span);
+    ContextScope scope = tracerAPI.activateManualSpan(span);
     entry(value);
     span.finish();
     scope.close();

dd-java-agent/agent-iast/src/jmh/java/com/datadog/iast/propagation/AbstractBenchmark.java

@@ -6,12 +6,12 @@
 import com.datadog.iast.model.Range;
 import com.datadog.iast.model.Source;
 import com.datadog.iast.taint.TaintedObjects;
+import datadog.context.ContextScope;
 import datadog.trace.api.Config;
 import datadog.trace.api.ProductActivation;
 import datadog.trace.api.gateway.InstrumentationGateway;
 import datadog.trace.api.gateway.RequestContextSlot;
 import datadog.trace.api.iast.IastContext;
-import datadog.trace.bootstrap.instrumentation.api.AgentScope;
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer;
 import datadog.trace.bootstrap.instrumentation.api.TagContext;
@@ -44,7 +44,7 @@ public abstract class AbstractBenchmark<C extends AbstractBenchmark.BenchmarkCon
   private static final Logger LOG = LoggerFactory.getLogger(AbstractBenchmark.class);
 
   private AgentSpan span;
-  private AgentScope scope;
+  private ContextScope scope;
   protected C context;
 
   @Setup(Level.Trial)

dd-java-agent/agent-iast/src/test/groovy/com/datadog/iast/ReporterTest.groovy

@@ -10,7 +10,7 @@ import datadog.trace.api.ProductTraceSource
 import datadog.trace.api.gateway.RequestContext
 import datadog.trace.api.gateway.RequestContextSlot
 import datadog.trace.api.internal.TraceSegment
-import datadog.trace.bootstrap.instrumentation.api.AgentScope
+import datadog.context.ContextScope
 import datadog.trace.bootstrap.instrumentation.api.AgentSpan
 import datadog.trace.bootstrap.instrumentation.api.AgentSpanContext
 import datadog.trace.bootstrap.instrumentation.api.AgentTracer
@@ -218,7 +218,7 @@ class ReporterTest extends DDSpecification {
     final spanId = 12345L
     final serviceName = 'service-name'
     final span = Mock(AgentSpan)
-    final scope = Mock(AgentScope)
+    final scope = Mock(ContextScope)
     final ctx = new IastRequestContext(noOpTaintedObjects())
     final reqCtx = Stub(RequestContext)
     reqCtx.getData(RequestContextSlot.IAST) >> ctx