feat(core): Emit no_parent_span client outcomes for discarded spans requiring a parent (#20350)

Lms24 · s1gr1d · web-flow · commit be1353786b2c · 2026-04-20T11:43:32.000Z
This PR adds reporting a client discard outcome for spans we skip because they require a parent span to be active. This happens when `onlyIfParent: true` is set when starting spans, or in custom logic for `http.client` spans. With this PR, we should now get a much clearer picture of how many spans users are missing out on. In span streaming, we'll always emit them (see #17932) spans. closes https://linear.app/getsentry/issue/SDK-1123/add-client-report-outcome-for-dropped-spans-because-of-missing-parent --------- Co-authored-by: s1gr1d <32902192+s1gr1d@users.noreply.github.com>
diff --git a/.size-limit.js b/.size-limit.js
@@ -203,7 +203,7 @@ module.exports = [
     name: 'CDN Bundle (incl. Tracing, Logs, Metrics)',
     path: createCDNPath('bundle.tracing.logs.metrics.min.js'),
     gzip: true,
-    limit: '46 KB',
+    limit: '47 KB',
   },
   {
     name: 'CDN Bundle (incl. Replay, Logs, Metrics)',
@@ -324,7 +324,7 @@ module.exports = [
     import: createImport('init'),
     ignore: [...builtinModules, ...nodePrefixedBuiltinModules],
     gzip: true,
-    limit: '59 KB',
+    limit: '60 KB',
   },
   // Node SDK (ESM)
   {
diff --git a/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report-streamed/init.js b/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report-streamed/init.js
@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [
+    Sentry.browserTracingIntegration({ instrumentPageLoad: false, instrumentNavigation: false }),
+    Sentry.spanStreamingIntegration(),
+  ],
+  tracesSampleRate: 1,
+  sendClientReports: true,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report-streamed/subject.js b/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report-streamed/subject.js
@@ -0,0 +1 @@
+fetch('http://sentry-test-site.example/api/test');
diff --git a/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report-streamed/test.ts b/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report-streamed/test.ts
@@ -0,0 +1,45 @@
+import { expect } from '@playwright/test';
+import type { ClientReport } from '@sentry/core';
+import { sentryTest } from '../../../utils/fixtures';
+import {
+  envelopeRequestParser,
+  hidePage,
+  shouldSkipTracingTest,
+  testingCdnBundle,
+  waitForClientReportRequest,
+} from '../../../utils/helpers';
+
+sentryTest(
+  'records no_parent_span client report for fetch requests without an active span',
+  async ({ getLocalTestUrl, page }) => {
+    sentryTest.skip(shouldSkipTracingTest() || testingCdnBundle());
+
+    await page.route('http://sentry-test-site.example/api/test', route => {
+      route.fulfill({
+        status: 200,
+        body: 'ok',
+        headers: { 'Content-Type': 'text/plain' },
+      });
+    });
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    const clientReportPromise = waitForClientReportRequest(page, report => {
+      return report.discarded_events.some(e => e.reason === 'no_parent_span');
+    });
+
+    await page.goto(url);
+
+    await hidePage(page);
+
+    const clientReport = envelopeRequestParser<ClientReport>(await clientReportPromise);
+
+    expect(clientReport.discarded_events).toEqual([
+      {
+        category: 'span',
+        quantity: 1,
+        reason: 'no_parent_span',
+      },
+    ]);
+  },
+);
diff --git a/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report/init.js b/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report/init.js
@@ -0,0 +1,10 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [Sentry.browserTracingIntegration({ instrumentPageLoad: false, instrumentNavigation: false })],
+  tracesSampleRate: 1,
+  sendClientReports: true,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report/subject.js b/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report/subject.js
@@ -0,0 +1 @@
+fetch('http://sentry-test-site.example/api/test');
diff --git a/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report/test.ts b/dev-packages/browser-integration-tests/suites/tracing/no-parent-span-client-report/test.ts
@@ -0,0 +1,45 @@
+import { expect } from '@playwright/test';
+import type { ClientReport } from '@sentry/core';
+import { sentryTest } from '../../../utils/fixtures';
+import {
+  envelopeRequestParser,
+  hidePage,
+  shouldSkipTracingTest,
+  testingCdnBundle,
+  waitForClientReportRequest,
+} from '../../../utils/helpers';
+
+sentryTest(
+  'records no_parent_span client report for fetch requests without an active span',
+  async ({ getLocalTestUrl, page }) => {
+    sentryTest.skip(shouldSkipTracingTest() || testingCdnBundle());
+
+    await page.route('http://sentry-test-site.example/api/test', route => {
+      route.fulfill({
+        status: 200,
+        body: 'ok',
+        headers: { 'Content-Type': 'text/plain' },
+      });
+    });
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    const clientReportPromise = waitForClientReportRequest(page, report => {
+      return report.discarded_events.some(e => e.reason === 'no_parent_span');
+    });
+
+    await page.goto(url);
+
+    await hidePage(page);
+
+    const clientReport = envelopeRequestParser<ClientReport>(await clientReportPromise);
+
+    expect(clientReport.discarded_events).toEqual([
+      {
+        category: 'span',
+        quantity: 1,
+        reason: 'no_parent_span',
+      },
+    ]);
+  },
+);
diff --git a/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report-streamed/instrument.mjs b/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report-streamed/instrument.mjs
@@ -0,0 +1,11 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+  traceLifecycle: 'stream',
+  clientReportFlushInterval: 1_000,
+});
diff --git a/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report-streamed/scenario.mjs b/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report-streamed/scenario.mjs
@@ -0,0 +1,2 @@
+import http from 'http';
+http.get('http://localhost:9999/external', () => {}).on('error', () => {});
diff --git a/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report-streamed/test.ts b/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report-streamed/test.ts
@@ -0,0 +1,29 @@
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+describe('no_parent_span client report (streaming)', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('records no_parent_span outcome for http.client span without a local parent', async () => {
+      const runner = createRunner()
+        .unignore('client_report')
+        .expect({
+          client_report: report => {
+            expect(report.discarded_events).toEqual([
+              {
+                category: 'span',
+                quantity: 1,
+                reason: 'no_parent_span',
+              },
+            ]);
+          },
+        })
+        .start();
+
+      await runner.completed();
+    });
+  });
+});
diff --git a/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report/instrument.mjs b/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report/instrument.mjs
@@ -0,0 +1,10 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+  clientReportFlushInterval: 1_000,
+});
diff --git a/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report/scenario.mjs b/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report/scenario.mjs
@@ -0,0 +1,2 @@
+import http from 'http';
+http.get('http://localhost:9999/external', () => {}).on('error', () => {});
diff --git a/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report/test.ts b/dev-packages/node-integration-tests/suites/tracing/no-parent-span-client-report/test.ts
@@ -0,0 +1,29 @@
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+describe('no_parent_span client report', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('records no_parent_span outcome for http.client span without a local parent', async () => {
+      const runner = createRunner()
+        .unignore('client_report')
+        .expect({
+          client_report: report => {
+            expect(report.discarded_events).toEqual([
+              {
+                category: 'span',
+                quantity: 1,
+                reason: 'no_parent_span',
+              },
+            ]);
+          },
+        })
+        .start();
+
+      await runner.completed();
+    });
+  });
+});
diff --git a/packages/browser/src/tracing/request.ts b/packages/browser/src/tracing/request.ts
@@ -404,6 +404,7 @@ function xhrCallback(
 
   const urlForSpanName = stripDataUrlContent(stripUrlQueryAndFragment(url));
 
+  const client = getClient();
   const hasParent = !!getActiveSpan();
 
   const span =
@@ -424,6 +425,10 @@ function xhrCallback(
         })
       : new SentryNonRecordingSpan();
 
+  if (shouldCreateSpanResult && !hasParent) {
+    client?.recordDroppedEvent('no_parent_span', 'span');
+  }
+
   xhr.__sentry_xhr_span_id__ = span.spanContext().spanId;
   spans[xhr.__sentry_xhr_span_id__] = span;
 
@@ -438,7 +443,6 @@ function xhrCallback(
     );
   }
 
-  const client = getClient();
   if (client) {
     client.emit('beforeOutgoingRequestSpan', span, handlerData as XhrHint);
   }
diff --git a/packages/core/src/fetch.ts b/packages/core/src/fetch.ts
@@ -108,13 +108,18 @@ export function instrumentFetchRequest(
   const { spanOrigin = 'auto.http.browser', propagateTraceparent = false } =
     typeof spanOriginOrOptions === 'object' ? spanOriginOrOptions : { spanOrigin: spanOriginOrOptions };
 
+  const client = getClient();
   const hasParent = !!getActiveSpan();
 
   const span =
     shouldCreateSpanResult && hasParent
       ? startInactiveSpan(getSpanStartOptions(url, method, spanOrigin))
       : new SentryNonRecordingSpan();
 
+  if (shouldCreateSpanResult && !hasParent) {
+    client?.recordDroppedEvent('no_parent_span', 'span');
+  }
+
   handlerData.fetchData.__span = span.spanContext().spanId;
   spans[span.spanContext().spanId] = span;
 
@@ -141,8 +146,6 @@ export function instrumentFetchRequest(
     }
   }
 
-  const client = getClient();
-
   if (client) {
     const fetchHint = {
       input: handlerData.args,
diff --git a/packages/core/src/tracing/trace.ts b/packages/core/src/tracing/trace.ts
@@ -68,9 +68,10 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
     return wrapper(() => {
       const scope = getCurrentScope();
       const parentSpan = getParentSpan(scope, customParentSpan);
+      const client = getClient();
 
-      const shouldSkipSpan = options.onlyIfParent && !parentSpan;
-      const activeSpan = shouldSkipSpan
+      const missingRequiredParent = options.onlyIfParent && !parentSpan;
+      const activeSpan = missingRequiredParent
         ? new SentryNonRecordingSpan()
         : createChildOrRootSpan({
             parentSpan,
@@ -79,6 +80,10 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
             scope,
           });
 
+      if (missingRequiredParent) {
+        client?.recordDroppedEvent('no_parent_span', 'span');
+      }
+
       // Ignored root spans still need to be set on scope so that `getActiveSpan()` returns them
       // and descendants are also non-recording. Ignored child spans don't need this because
       // the parent span is already on scope.
@@ -132,8 +137,8 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
       const scope = getCurrentScope();
       const parentSpan = getParentSpan(scope, customParentSpan);
 
-      const shouldSkipSpan = options.onlyIfParent && !parentSpan;
-      const activeSpan = shouldSkipSpan
+      const missingRequiredParent = options.onlyIfParent && !parentSpan;
+      const activeSpan = missingRequiredParent
         ? new SentryNonRecordingSpan()
         : createChildOrRootSpan({
             parentSpan,
@@ -142,6 +147,10 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
             scope,
           });
 
+      if (missingRequiredParent) {
+        getClient()?.recordDroppedEvent('no_parent_span', 'span');
+      }
+
       // We don't set ignored child spans onto the scope because there likely is an active,
       // unignored span on the scope already.
       if (!_isIgnoredSpan(activeSpan) || !parentSpan) {
@@ -195,10 +204,12 @@ export function startInactiveSpan(options: StartSpanOptions): Span {
   return wrapper(() => {
     const scope = getCurrentScope();
     const parentSpan = getParentSpan(scope, customParentSpan);
+    const client = getClient();
 
-    const shouldSkipSpan = options.onlyIfParent && !parentSpan;
+    const missingRequiredParent = options.onlyIfParent && !parentSpan;
 
-    if (shouldSkipSpan) {
+    if (missingRequiredParent) {
+      client?.recordDroppedEvent('no_parent_span', 'span');
       return new SentryNonRecordingSpan();
     }
 
diff --git a/packages/core/src/types-hoist/clientreport.ts b/packages/core/src/types-hoist/clientreport.ts
@@ -11,7 +11,8 @@ export type EventDropReason =
   | 'internal_sdk_error'
   | 'buffer_overflow'
   | 'ignored'
-  | 'invalid';
+  | 'invalid'
+  | 'no_parent_span';
 
 export type Outcome = {
   reason: EventDropReason;
diff --git a/packages/core/test/lib/tracing/trace.test.ts b/packages/core/test/lib/tracing/trace.test.ts
diff --git a/packages/opentelemetry/src/sampler.ts b/packages/opentelemetry/src/sampler.ts
diff --git a/packages/opentelemetry/src/trace.ts b/packages/opentelemetry/src/trace.ts
diff --git a/packages/opentelemetry/test/sampler.test.ts b/packages/opentelemetry/test/sampler.test.ts
diff --git a/packages/opentelemetry/test/trace.test.ts b/packages/opentelemetry/test/trace.test.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+fetch('http://sentry-test-site.example/api/test');`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+import http from 'http';`
	`2`	`+http.get('http://localhost:9999/external', () => {}).on('error', () => {});`