fix(core): Bound child span tracking on long-lived spans (#22916)

## What

Bounds the child spans a span keeps a reference to. A child is no longer
tracked when it could never show up in what that span sends:

- the parent is unsampled, so its tree is never read
- the parent has stopped recording and so has its segment span, so the
tree has been read for the last time

Late children still resolve their root span, so they keep being sent on
their own, and a late child that is itself still recording keeps
collecting the subtree it is re-emitted with. Both conditions are read
off the parent, so this holds for every capture path, including span
streaming and deferred capture.

## Why

A span that outlives its children retains every one of them. In NestJS
the `Create Nest App` span stays the active parent of anything a
`setInterval` from a provider constructor starts, so those spans are
never released and the process leaks around 80 MB/h. The cutoff covers
the whole tree, not only the segment span, so any span pinned in a
long-lived async context is bounded the same way.

Reproduction:
https://github.com/andreiborza/sentry-nestjs-span-retention-repro (60 s
at 20 rps, 12000 spans, post-GC heap snapshots). Children retained on
the boot span and heap node growth over the run, both measured on this
branch with and without the fix:

| | retained | node growth |
| --- | --- | --- |
| before, span streaming (the default) | 12000 | +115.7% |
| before, transactions | 12000 | +116.2% |
| after, span streaming | 0 | -2.5% |
| after, transactions | 0 | -1.7% |

Neither trace lifecycle avoids it, and published
`@sentry/nestjs@10.69.0` leaks the same way on both, so this is not new
in v11.

Closes: #22860

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: andreiborza

packages/core/src/utils/spanUtils.ts

@@ -378,6 +378,23 @@ export function addChildSpanToSpan(span: SpanWithPotentialChildren, childSpan: S
   const rootSpan = span[ROOT_SPAN_FIELD] || span;
   addNonEnumerableProperty(childSpan, ROOT_SPAN_FIELD, rootSpan);
 
+  // `_sentryChildSpans` exists only so `getSpanDescendants()` can walk the tree when the segment span
+  // is sent, and that walk stops at an unsampled span without ever visiting its children. So a child
+  // tracked here would be held for the parent's lifetime and never read.
+  if (!spanIsSampled(span)) {
+    return;
+  }
+
+  // Once the segment span stopped recording, the tree has been read for the last time, and a child
+  // starting now belongs to whatever segment comes next: it is re-emitted on its own instead. Tracking
+  // it here would pin it for as long as the parent lives, which for a span left active in an async
+  // context (e.g. a framework boot span captured by a queue consumer) is the rest of the process. Only
+  // a parent that is itself still recording keeps tracking, so a late child that outlives its segment
+  // still collects the subtree it is re-emitted with.
+  if (!span.isRecording() && !rootSpan.isRecording()) {
+    return;
+  }
+
   // We store a list of child spans on the parent span
   // We need this for `getSpanDescendants()` to work
   if (span[CHILD_SPANS_FIELD]) {

packages/core/test/lib/tracing/sentrySpan.test.ts

@@ -8,15 +8,19 @@ import {
 } from '../../../src/semanticAttributes';
 import { SentrySpan } from '../../../src/tracing/sentrySpan';
 import { SPAN_STATUS_ERROR } from '../../../src/tracing/spanstatus';
-import { startInactiveSpan, startSpan } from '../../../src/tracing/trace';
+import { startInactiveSpan, startSpan, withActiveSpan } from '../../../src/tracing/trace';
 import { markSpanAsTracerProviderSpan } from '../../../src/tracing/utils';
 import { withStaticSpan } from '../../../src/tracing/spans/beforeSendSpan';
 import type { Envelope } from '../../../src/types/envelope';
-import type { SpanJSON } from '../../../src/types/span';
-import { spanToStaticSpanJSON, TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
+import type { Span, SpanJSON } from '../../../src/types/span';
+import { getRootSpan, spanToStaticSpanJSON, TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import { timestampInSeconds } from '../../../src/utils/time';
 import { getDefaultTestClientOptions, TestClient } from '../../mocks/client';
 
+function childSpansOf(span: Span): Set<Span> {
+  return (span as unknown as { _sentryChildSpans?: Set<Span> })._sentryChildSpans ?? new Set();
+}
+
 describe('SentrySpan', () => {
   describe('name', () => {
     it('works with name', () => {
@@ -168,6 +172,51 @@ describe('SentrySpan', () => {
     });
   });
 
+  describe('child span retention', () => {
+    it('stops tracking children on a segment span once it has been captured', () => {
+      const client = new TestClient(getDefaultTestClientOptions({ tracesSampleRate: 1 }));
+      setCurrentClient(client);
+      const captureEvent = vi.spyOn(client, 'captureEvent');
+
+      let rootSpan: Span | undefined;
+      startSpan({ name: 'root' }, span => {
+        rootSpan = span;
+        startSpan({ name: 'child' }, () => {});
+      });
+
+      expect(captureEvent).toHaveBeenCalledTimes(1);
+      expect(captureEvent).toHaveBeenCalledWith(
+        expect.objectContaining({ spans: [expect.objectContaining({ description: 'child' })] }),
+        expect.any(Object),
+        expect.any(Object),
+      );
+      expect(childSpansOf(rootSpan!).size).toBe(1);
+
+      // A child that starts after the tree was read is not tracked, but can still find its root span,
+      // which is all that re-emitting it as its own transaction needs.
+      const lateChild = withActiveSpan(rootSpan!, () => startInactiveSpan({ name: 'late child' }));
+      expect(childSpansOf(rootSpan!).size).toBe(1);
+      expect(getRootSpan(lateChild)).toBe(rootSpan);
+    });
+
+    it('stops tracking children on a segment span that has streamed', () => {
+      const client = new TestClient(getDefaultTestClientOptions({ tracesSampleRate: 1, traceLifecycle: 'stream' }));
+      setCurrentClient(client);
+
+      let rootSpan: Span | undefined;
+      startSpan({ name: 'root' }, span => {
+        rootSpan = span;
+        startSpan({ name: 'child' }, () => {});
+      });
+
+      expect(childSpansOf(rootSpan!).size).toBe(1);
+
+      const lateChild = withActiveSpan(rootSpan!, () => startInactiveSpan({ name: 'late child' }));
+      expect(childSpansOf(rootSpan!).size).toBe(1);
+      expect(getRootSpan(lateChild)).toBe(rootSpan);
+    });
+  });
+
   describe('end', () => {
     test('simple', () => {
       const span = new SentrySpan({});

packages/core/test/lib/utils/spanUtils.test.ts

@@ -27,8 +27,10 @@ import type { SpanStatus } from '../../../src/types/spanStatus';
 import { _setSpanForScope } from '../../../src/utils/spanOnScope';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
 import {
+  addChildSpanToSpan,
   getActiveSpan,
   getRootSpan,
+  getSpanDescendants,
   spanIsSampled,
   spanTimeInputToSeconds,
   spanToStaticSpanJSON,
@@ -872,6 +874,72 @@ describe('getActiveSpan', () => {
   });
 });
 
+describe('addChildSpanToSpan', () => {
+  it('does not track children on an unsampled span', () => {
+    const parent = new SentrySpan({ name: 'parent', sampled: false });
+    const child = new SentrySpan({ name: 'child', sampled: false });
+
+    addChildSpanToSpan(parent, child);
+
+    expect(getRootSpan(child)).toBe(parent);
+    expect((parent as unknown as { _sentryChildSpans?: Set<Span> })._sentryChildSpans).toBeUndefined();
+  });
+
+  it('does not track children on a segment span that stopped recording', () => {
+    const parent = new SentrySpan({ name: 'parent', sampled: true });
+    parent.end();
+
+    const child = new SentrySpan({ name: 'child', sampled: true });
+    addChildSpanToSpan(parent, child);
+
+    // the child that was not tracked can still find its root span
+    expect(getRootSpan(child)).toBe(parent);
+    expect(getSpanDescendants(parent)).toEqual([parent]);
+  });
+
+  it('keeps tracking children on an ended span while its segment span is still recording', () => {
+    const segment = new SentrySpan({ name: 'segment', sampled: true });
+    const parent = new SentrySpan({ name: 'parent', sampled: true });
+    addChildSpanToSpan(segment, parent);
+    parent.end();
+
+    const child = new SentrySpan({ name: 'child', sampled: true });
+    addChildSpanToSpan(parent, child);
+
+    // the segment span is still open, so its transaction has not been assembled yet
+    expect(getSpanDescendants(segment)).toEqual([segment, parent, child]);
+  });
+
+  it('stops tracking children on an ended span once its segment span has ended', () => {
+    const segment = new SentrySpan({ name: 'segment', sampled: true });
+    const parent = new SentrySpan({ name: 'parent', sampled: true });
+    addChildSpanToSpan(segment, parent);
+    parent.end();
+    segment.end();
+
+    const child = new SentrySpan({ name: 'child', sampled: true });
+    addChildSpanToSpan(parent, child);
+
+    // the child that was not tracked can still find its root span
+    expect(getRootSpan(child)).toBe(segment);
+    expect(getSpanDescendants(segment)).toEqual([segment, parent]);
+  });
+
+  it('keeps tracking children on a still-recording span after its segment span ended', () => {
+    const segment = new SentrySpan({ name: 'segment', sampled: true });
+    const lateChild = new SentrySpan({ name: 'late child', sampled: true });
+    addChildSpanToSpan(segment, lateChild);
+    segment.end();
+
+    const grandChild = new SentrySpan({ name: 'grandchild', sampled: true });
+    addChildSpanToSpan(lateChild, grandChild);
+
+    // a late child that outlives its segment is re-emitted as its own orphan transaction with its
+    // subtree, so the subtree must keep collecting
+    expect(getSpanDescendants(lateChild)).toEqual([lateChild, grandChild]);
+  });
+});
+
 describe('updateSpanName', () => {
   it('updates the span name and source', () => {
     const span = new SentrySpan({ name: 'old-name', attributes: { [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url' } });