fix(core): release finished spans from captured async-context frames

`Plugin#enter` writes a fresh `{ ...store, span }` object into the current
async-context frame. Any async resource created while that frame is active
snapshots it and keeps the object — and its `span` — reachable for the
resource's whole lifetime. When the resource is never freed (a pooled socket, a
long-lived emitter), the finished span and its entire parent chain stay pinned,
so retention grows one span per request until the process runs out of memory
(#9227).

`enter` now returns the store it wrote into storage; a caller whose span outlives
the request keeps that object and nulls its `span` once the span is finished and
no in-scope continuation can still read it as active. Applied at the three sites
that enter a store for such a span:

1. router — null every entered store at `request:finish`, not at
   `middleware:finish` (which fires before `next.apply(...)`, while work the
   middleware schedules after `next()` must still see the correct active span).
2. google-cloud-pubsub push — null the push-receive store at request finish.
3. test-api-manual — null the entered store once the manual test is finished.

Nulling the store in place, rather than routing through a span-keyed WeakMap on
the base class, keeps the release off the hot path (no per-span map insert plus
lookup and delete) and off the npm-exported `Plugin` surface.

Refs: #9228

Author: BridgeAR

packages/datadog-plugin-google-cloud-pubsub/src/pubsub-push-subscription.js

@@ -5,7 +5,9 @@ const SpanContext = require('../../dd-trace/src/opentracing/span_context')
 const id = require('../../dd-trace/src/id')
 const log = require('../../dd-trace/src/log')
 
-// WeakMap to track push receive spans by request
+// Track each request's push-receive span and the store it was entered into, so
+// the store's `span` can be nulled at request finish (a captured async-context
+// frame would otherwise pin the finished span).
 const pushReceiveSpans = new WeakMap()
 
 class GoogleCloudPubsubPushSubscriptionPlugin extends TracingPlugin {
@@ -35,10 +37,13 @@ class GoogleCloudPubsubPushSubscriptionPlugin extends TracingPlugin {
   }
 
   #finishPushReceiveSpan (req) {
-    const pushReceiveSpan = pushReceiveSpans.get(req)
-    if (pushReceiveSpan && !pushReceiveSpan._duration) {
-      pushReceiveSpan.finish()
+    const entry = pushReceiveSpans.get(req)
+    if (entry && !entry.span._duration) {
+      entry.span.finish()
       pushReceiveSpans.delete(req)
+      // The request is done; null the span on the store entered for it so a
+      // captured async-context frame stops retaining the finished span.
+      entry.store.span = null
     }
   }
 
@@ -90,8 +95,8 @@ class GoogleCloudPubsubPushSubscriptionPlugin extends TracingPlugin {
       return
     }
 
-    this.enter(pushReceiveSpan, { req, res })
-    pushReceiveSpans.set(req, pushReceiveSpan)
+    const store = this.enter(pushReceiveSpan, { req, res })
+    pushReceiveSpans.set(req, { span: pushReceiveSpan, store })
   }
 
   #parseMessage (req) {

packages/datadog-plugin-router/src/index.js

@@ -38,7 +38,12 @@ class RouterPlugin extends WebPlugin {
       }
 
       context.storeStack.push(store)
-      this.enter(span, store)
+      // Keep the entered store for the whole request so its `span` can be nulled
+      // at request finish. `context.middleware` is drained early at
+      // `middleware:finish`, so it cannot serve as the release list; a middleware
+      // span finished mid-request would otherwise stay pinned by any async
+      // resource that captured its frame.
+      context.enteredStores.push(this.enter(span, store))
 
       web.patch(req)
       web.setRoute(req, context.route)
@@ -91,6 +96,17 @@ class RouterPlugin extends WebPlugin {
       while ((span = context.middleware.pop())) {
         span.finish()
       }
+
+      // The request/response is fully done: no async continuation can still need
+      // a middleware span as the active span. Null the `span` on every store we
+      // entered so an async resource that captured that frame no longer retains
+      // the finished span or its parent chain. This happens only here — never at
+      // `middleware:finish`, which fires before `next.apply(...)`, so work a
+      // middleware schedules after `next()` still sees the correct active span.
+      let store
+      while ((store = context.enteredStores.pop())) {
+        store.span = null
+      }
     })
   }
 
@@ -130,14 +146,17 @@ class RouterPlugin extends WebPlugin {
       return context
     }
 
-    // Five-property shape pinned at allocation so every request shares the
-    // same hidden class — no per-field transitions after construction.
+    // Fixed shape pinned at allocation so every request shares the same hidden
+    // class — no per-field transitions after construction.
     context = {
       span,
       stack: [route],
       route,
       middleware: [],
       storeStack: [],
+      // Every store entered for this request, retained until request finish so
+      // its `span` can be nulled there (see the `request:finish` handler).
+      enteredStores: [],
     }
 
     this.#contexts.set(req, context)

packages/dd-trace/src/ci-visibility/test-api-manual/test-api-manual-plugin.js

@@ -34,6 +34,10 @@ class TestApiManualPlugin extends CiPlugin {
         }
         testSpan.finish()
         finishAllTraceSpans(testSpan)
+        // Null the span on the entered store so a captured async-context frame no
+        // longer retains the finished test span. `store` is the frame entered for
+        // this test at `:start`; the same read already drives `finish` above.
+        store.span = null
       }
     })
     this.unconfiguredAddSub('dd-trace:ci:manual:test:addTags', (tags) => {

packages/dd-trace/src/plugins/plugin.js

@@ -98,13 +98,23 @@ module.exports = class Plugin {
   /**
    * Enter a context with the provided span bound in storage.
    *
+   * A fresh `{ ...store, span }` object is written into the current
+   * async-context frame, so any async resource created while it is active
+   * snapshots the frame and keeps that object — and its `span` — reachable for
+   * the resource's whole lifetime, even after the span finishes. A caller whose
+   * span outlives the request should keep the returned store and null its `span`
+   * once the span is finished and no in-scope continuation can still read it as
+   * active; otherwise a never-freed resource pins the finished span (and its
+   * parent chain) forever.
+   *
    * @param {object} span The span to bind as current.
    * @param {object=} store Optional existing store to extend; if omitted, uses current store.
-   * @returns {void}
+   * @returns {{ span: object | null }} The store object written into storage.
    */
   enter (span, store) {
-    store = store || legacyStorage.getStore()
-    legacyStorage.enterWith({ ...store, span })
+    const activeStore = { ...(store || legacyStorage.getStore()), span }
+    legacyStorage.enterWith(activeStore)
+    return activeStore
   }
 
   /**