feat(core): Support attribute matching in ignoreSpans (#20512)

nicohrubec · web-flow · commit 15a6a8ba06bb · 2026-04-27T11:25:10.000+02:00
Extends `ignoreSpans` with a new optional attributes field per the `ignoreSpans` [spec](https://develop.sentry.dev/sdk/telemetry/spans/filtering/#filter-with-ignorespans), letting users drop spans based on span attributes (in addition to name/description or op). String attribute values use pattern matching (substring / RegExp). Non-string values match by strict equality (arrays element-wise). Closes #20360
diff --git a/.size-limit.js b/.size-limit.js
@@ -8,7 +8,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '26 KB',
+    limit: '27 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -40,7 +40,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init', 'browserTracingIntegration'),
     gzip: true,
-    limit: '44 KB',
+    limit: '45 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -128,7 +128,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init', 'feedbackAsyncIntegration'),
     gzip: true,
-    limit: '36 KB',
+    limit: '37 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -197,7 +197,7 @@ module.exports = [
     path: 'packages/svelte/build/esm/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '26 KB',
+    limit: '27 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   // Browser CDN bundles
@@ -254,7 +254,7 @@ module.exports = [
     name: 'CDN Bundle (incl. Tracing, Replay, Feedback)',
     path: createCDNPath('bundle.tracing.replay.feedback.min.js'),
     gzip: true,
-    limit: '89 KB',
+    limit: '90 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -270,15 +270,15 @@ module.exports = [
     path: createCDNPath('bundle.min.js'),
     gzip: false,
     brotli: false,
-    limit: '84 KB',
+    limit: '85 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
     name: 'CDN Bundle (incl. Tracing) - uncompressed',
     path: createCDNPath('bundle.tracing.min.js'),
     gzip: false,
     brotli: false,
-    limit: '138 KB',
+    limit: '139 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -294,39 +294,39 @@ module.exports = [
     path: createCDNPath('bundle.tracing.logs.metrics.min.js'),
     gzip: false,
     brotli: false,
-    limit: '141.5 KB',
+    limit: '142 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
     name: 'CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed',
     path: createCDNPath('bundle.replay.logs.metrics.min.js'),
     gzip: false,
     brotli: false,
-    limit: '212 KB',
+    limit: '213 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
     name: 'CDN Bundle (incl. Tracing, Replay) - uncompressed',
     path: createCDNPath('bundle.tracing.replay.min.js'),
     gzip: false,
     brotli: false,
-    limit: '255.5 KB',
+    limit: '256 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
     name: 'CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed',
     path: createCDNPath('bundle.tracing.replay.logs.metrics.min.js'),
     gzip: false,
     brotli: false,
-    limit: '259 KB',
+    limit: '260 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
     name: 'CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed',
     path: createCDNPath('bundle.tracing.replay.feedback.min.js'),
     gzip: false,
     brotli: false,
-    limit: '269 KB',
+    limit: '270 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
diff --git a/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/init.js b/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/init.js
@@ -0,0 +1,11 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [Sentry.spanStreamingIntegration()],
+  ignoreSpans: [{ attributes: { 'http.status_code': 200 } }],
+  tracesSampleRate: 1,
+  debug: true,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/subject.js b/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/subject.js
@@ -0,0 +1,11 @@
+// This segment span matches ignoreSpans via attributes — segment + child should be dropped
+Sentry.startSpan({ name: 'health-check', attributes: { 'http.status_code': 200 } }, () => {
+  Sentry.startSpan({ name: 'child-of-ignored' }, () => {});
+});
+
+setTimeout(() => {
+  // This segment span does NOT match — segment + child should be sent
+  Sentry.startSpan({ name: 'normal-segment', attributes: { 'http.status_code': 500 } }, () => {
+    Sentry.startSpan({ name: 'child-span' }, () => {});
+  });
+}, 1000);
diff --git a/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/test.ts b/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/test.ts
@@ -0,0 +1,35 @@
+import { expect } from '@playwright/test';
+import type { ClientReport } from '@sentry/core';
+import { sentryTest } from '../../../../utils/fixtures';
+import {
+  envelopeRequestParser,
+  hidePage,
+  shouldSkipTracingTest,
+  waitForClientReportRequest,
+} from '../../../../utils/helpers';
+import { observeStreamedSpan, waitForStreamedSpans } from '../../../../utils/spanUtils';
+
+sentryTest('attribute-matching ignoreSpans drops the trace', async ({ getLocalTestUrl, page }) => {
+  sentryTest.skip(shouldSkipTracingTest());
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  observeStreamedSpan(page, span => {
+    if (span.name === 'health-check' || span.name === 'child-of-ignored') {
+      throw new Error('Ignored span found');
+    }
+    return false;
+  });
+
+  const spansPromise = waitForStreamedSpans(page, spans => !!spans?.find(s => s.name === 'normal-segment'));
+  const clientReportPromise = waitForClientReportRequest(page);
+
+  await page.goto(url);
+
+  expect((await spansPromise)?.length).toBe(2);
+
+  await hidePage(page);
+
+  const clientReport = envelopeRequestParser<ClientReport>(await clientReportPromise);
+  expect(clientReport.discarded_events).toEqual([{ category: 'span', quantity: 2, reason: 'ignored' }]);
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/segment/subject.js b/dev-packages/browser-integration-tests/suites/tracing/ignoreSpans-streamed/segment/subject.js
@@ -1,10 +1,10 @@
-// This segment span matches ignoreSpans — should NOT produce a transaction
+// This segment span matches ignoreSpans — segment + child should be dropped
 Sentry.startSpan({ name: 'ignore-segment' }, () => {
   Sentry.startSpan({ name: 'child-of-ignored-segment' }, () => {});
 });
 
 setTimeout(() => {
-  // This segment span does NOT match — should produce a transaction
+  // This segment span does NOT match — segment + child should be sent
   Sentry.startSpan({ name: 'normal-segment' }, () => {
     Sentry.startSpan({ name: 'child-span' }, () => {});
   });
diff --git a/dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/instrument.mjs b/dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/instrument.mjs
@@ -0,0 +1,12 @@
+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',
+  ignoreSpans: [{ attributes: { 'http.method': 'POST' } }],
+  clientReportFlushInterval: 1_000,
+});
diff --git a/dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/server.mjs b/dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/server.mjs
@@ -0,0 +1,25 @@
+import express from 'express';
+import cors from 'cors';
+import * as Sentry from '@sentry/node';
+import { startExpressServerAndSendPortToRunner } from '@sentry-internal/node-integration-tests';
+
+const app = express();
+
+app.use(cors());
+
+app.get('/keep', (_req, res) => {
+  res.send({ status: 'kept' });
+  setTimeout(() => {
+    // flush to avoid waiting for the span buffer timeout to send spans
+    // but defer it to the next tick to let the SDK finish the http.server span first.
+    Sentry.flush();
+  });
+});
+
+app.post('/drop', (_req, res) => {
+  res.send({ status: 'dropped' });
+});
+
+Sentry.setupExpressErrorHandler(app);
+
+startExpressServerAndSendPortToRunner(app);
diff --git a/dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/test.ts b/dev-packages/node-integration-tests/suites/tracing/ignoreSpans-streamed/attributes/test.ts
@@ -0,0 +1,44 @@
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../../utils/runner';
+
+describe('filtering segment spans by attribute with ignoreSpans (streaming)', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'server.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('segment spans matching an attribute filter are dropped including all children', async () => {
+      const runner = createRunner()
+        .unignore('client_report')
+        .expect({
+          client_report: {
+            discarded_events: [
+              {
+                category: 'span',
+                quantity: 5, // 1 segment ignored + 4 child spans (implicitly ignored)
+                reason: 'ignored',
+              },
+            ],
+          },
+        })
+        .expect({
+          span: container => {
+            expect(container.items).toHaveLength(5);
+            const segmentSpan = container.items.find(s => s.name === 'GET /keep' && !!s.is_segment);
+
+            expect(segmentSpan).toBeDefined();
+            expect(container.items.every(s => s.trace_id === segmentSpan!.trace_id)).toBe(true);
+          },
+        })
+        .start();
+
+      const dropRes = await runner.makeRequest('post', '/drop');
+      expect((dropRes as { status: string }).status).toBe('dropped');
+
+      const keepRes = await runner.makeRequest('get', '/keep');
+      expect((keepRes as { status: string }).status).toBe('kept');
+
+      await runner.completed();
+    });
+  });
+});
diff --git a/packages/core/src/client.ts b/packages/core/src/client.ts
@@ -1600,7 +1600,13 @@ function processBeforeSend(
       const rootSpanJson = convertTransactionEventToSpanJson(processedEvent);
 
       // 1.1 If the root span should be ignored, drop the whole transaction
-      if (ignoreSpans?.length && shouldIgnoreSpan(rootSpanJson, ignoreSpans)) {
+      if (
+        ignoreSpans?.length &&
+        shouldIgnoreSpan(
+          { description: rootSpanJson.description, op: rootSpanJson.op, attributes: rootSpanJson.data },
+          ignoreSpans,
+        )
+      ) {
         // dropping the whole transaction!
         return null;
       }
@@ -1624,7 +1630,10 @@ function processBeforeSend(
 
         for (const span of initialSpans) {
           // 2.a If the child span should be ignored, reparent it to the root span
-          if (ignoreSpans?.length && shouldIgnoreSpan(span, ignoreSpans)) {
+          if (
+            ignoreSpans?.length &&
+            shouldIgnoreSpan({ description: span.description, op: span.op, attributes: span.data }, ignoreSpans)
+          ) {
             reparentChildSpans(initialSpans, span);
             continue;
           }
diff --git a/packages/core/src/envelope.ts b/packages/core/src/envelope.ts
@@ -142,7 +142,10 @@ export function createSpanEnvelope(spans: [SentrySpan, ...SentrySpan[]], client?
   const { beforeSendSpan, ignoreSpans } = client?.getOptions() || {};
 
   const filteredSpans = ignoreSpans?.length
-    ? spans.filter(span => !shouldIgnoreSpan(spanToJSON(span), ignoreSpans))
+    ? spans.filter(span => {
+        const json = spanToJSON(span);
+        return !shouldIgnoreSpan({ description: json.description, op: json.op, attributes: json.data }, ignoreSpans);
+      })
     : spans;
   const droppedSpans = spans.length - filteredSpans.length;
 
diff --git a/packages/core/src/tracing/idleSpan.ts b/packages/core/src/tracing/idleSpan.ts
@@ -179,7 +179,13 @@ export function startIdleSpan(startSpanOptions: StartSpanOptions, options: Parti
         // Ignored spans will get dropped later (in the client) but since we already adjust
         // the idle span end timestamp here, we can already take to-be-ignored spans out of
         // the calculation here.
-        if (ignoreSpans && shouldIgnoreSpan(currentSpanJson, ignoreSpans)) {
+        if (
+          ignoreSpans &&
+          shouldIgnoreSpan(
+            { description: currentSpanJson.description, op: currentSpanJson.op, attributes: currentSpanJson.data },
+            ignoreSpans,
+          )
+        ) {
           return acc;
         }
         return acc ? Math.max(acc, currentSpanJson.timestamp) : currentSpanJson.timestamp;
diff --git a/packages/core/src/tracing/trace.ts b/packages/core/src/tracing/trace.ts
@@ -610,6 +610,7 @@ function _shouldIgnoreStreamedSpan(client: Client | undefined, spanArguments: Se
     {
       description: spanArguments.name || '',
       op: spanArguments.attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP] || spanArguments.op,
+      attributes: spanArguments.attributes,
     },
     ignoreSpans,
   );
diff --git a/packages/core/src/types-hoist/options.ts b/packages/core/src/types-hoist/options.ts
@@ -100,9 +100,17 @@ export interface ServerRuntimeOptions {
   onFatalError?(this: void, error: Error): void;
 }
 
+/**
+ * Allowed attribute value matchers in `ignoreSpans` filters.
+ * String span attributes use pattern matching (substring or RegExp).
+ * Non-string attribute values match by strict equality (arrays element-wise).
+ */
+export type IgnoreSpanAttributeValue = string | boolean | number | string[] | boolean[] | number[] | RegExp;
+
 /**
  * A filter object for ignoring spans.
- * At least one of the properties (`op` or `name`) must be set.
+ * At least one of the properties (`name`, `op`, or `attributes`) must be set.
+ * If multiple are set, all must match for the span to be ignored.
  */
 type IgnoreSpanFilter =
   | {
@@ -114,6 +122,12 @@ type IgnoreSpanFilter =
        * Spans with an op matching this pattern will be ignored.
        */
       op?: string | RegExp;
+      /**
+       * Spans whose attributes ALL match the corresponding entries will be ignored.
+       * String attribute values are matched as patterns (substring or RegExp).
+       * Non-string values match by strict equality (arrays element-wise).
+       */
+      attributes?: Record<string, IgnoreSpanAttributeValue>;
     }
   | {
       /**
@@ -124,6 +138,28 @@ type IgnoreSpanFilter =
        * Spans with an op matching this pattern will be ignored.
        */
       op: string | RegExp;
+      /**
+       * Spans whose attributes ALL match the corresponding entries will be ignored.
+       * String attribute values are matched as patterns (substring or RegExp).
+       * Non-string values match by strict equality (arrays element-wise).
+       */
+      attributes?: Record<string, IgnoreSpanAttributeValue>;
+    }
+  | {
+      /**
+       * Spans with a name matching this pattern will be ignored.
+       */
+      name?: string | RegExp;
+      /**
+       * Spans with an op matching this pattern will be ignored.
+       */
+      op?: string | RegExp;
+      /**
+       * Spans whose attributes ALL match the corresponding entries will be ignored.
+       * String attribute values are matched as patterns (substring or RegExp).
+       * Non-string values match by strict equality (arrays element-wise).
+       */
+      attributes: Record<string, IgnoreSpanAttributeValue>;
     };
 
 export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOptions> {
@@ -326,7 +362,8 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    * A list of span names or patterns to ignore.
    *
    * If you specify a pattern {@link IgnoreSpanFilter}, at least one
-   * of the properties (`op` or `name`) must be set.
+   * of the properties (`name`, `op`, or `attributes`) must be set.
+   * When multiple properties are set, all must match for the span to be ignored.
    *
    * @default []
    */
diff --git a/packages/core/src/utils/should-ignore-span.ts b/packages/core/src/utils/should-ignore-span.ts
diff --git a/packages/core/test/lib/utils/should-ignore-span.test.ts b/packages/core/test/lib/utils/should-ignore-span.test.ts
diff --git a/packages/opentelemetry/src/sampler.ts b/packages/opentelemetry/src/sampler.ts
