feat(core): Add ignoreSpans option (#17078)

This adds a new `ignoreSpans` option to all SDKs which can be used as
follows:

```js
Sentry.init({
  ignoreSpans: ['partial match', /regex/, { name: 'span name', op: 'http.client' }]
});
```

this will drop spans before they are sent. Eventual child spans in the
same envelope will be re-parented, if possible.

Closes #16820

---------

Co-authored-by: Lukas Stracke <[email protected]>

Author: mydea

dev-packages/e2e-tests/test-applications/webpack-4/build.mjs

@@ -17,6 +17,11 @@ webpack(
       minimize: true,
       minimizer: [new TerserPlugin()],
     },
+    performance: {
+      hints: false,
+      maxEntrypointSize: 512000,
+      maxAssetSize: 512000
+  },
     plugins: [new HtmlWebpackPlugin(), new webpack.EnvironmentPlugin(['E2E_TEST_DSN'])],
     mode: 'production',
     // webpack 4 does not support ES2020 features out of the box, so we need to transpile them

packages/core/src/client.ts

@@ -42,6 +42,7 @@ import { merge } from './utils/merge';
 import { checkOrSetAlreadyCaught, uuid4 } from './utils/misc';
 import { parseSampleRate } from './utils/parseSampleRate';
 import { prepareEvent } from './utils/prepareEvent';
+import { reparentChildSpans, shouldIgnoreSpan } from './utils/should-ignore-span';
 import { getActiveSpan, showSpanDropWarning, spanToTraceContext } from './utils/spanUtils';
 import { rejectedSyncPromise, resolvedSyncPromise, SyncPromise } from './utils/syncpromise';
 import { convertSpanJsonToTransactionEvent, convertTransactionEventToSpanJson } from './utils/transactionEvent';
@@ -1281,36 +1282,67 @@ function processBeforeSend(
   event: Event,
   hint: EventHint,
 ): PromiseLike<Event | null> | Event | null {
-  const { beforeSend, beforeSendTransaction, beforeSendSpan } = options;
+  const { beforeSend, beforeSendTransaction, beforeSendSpan, ignoreSpans } = options;
   let processedEvent = event;
 
   if (isErrorEvent(processedEvent) && beforeSend) {
     return beforeSend(processedEvent, hint);
   }
 
   if (isTransactionEvent(processedEvent)) {
-    if (beforeSendSpan) {
-      // process root span
-      const processedRootSpanJson = beforeSendSpan(convertTransactionEventToSpanJson(processedEvent));
-      if (!processedRootSpanJson) {
-        showSpanDropWarning();
-      } else {
-        // update event with processed root span values
-        processedEvent = merge(event, convertSpanJsonToTransactionEvent(processedRootSpanJson));
+    // Avoid processing if we don't have to
+    if (beforeSendSpan || ignoreSpans) {
+      // 1. Process root span
+      const rootSpanJson = convertTransactionEventToSpanJson(processedEvent);
+
+      // 1.1 If the root span should be ignored, drop the whole transaction
+      if (ignoreSpans?.length && shouldIgnoreSpan(rootSpanJson, ignoreSpans)) {
+        // dropping the whole transaction!
+        return null;
       }
 
-      // process child spans
+      // 1.2 If a `beforeSendSpan` callback is defined, process the root span
+      if (beforeSendSpan) {
+        const processedRootSpanJson = beforeSendSpan(rootSpanJson);
+        if (!processedRootSpanJson) {
+          showSpanDropWarning();
+        } else {
+          // update event with processed root span values
+          processedEvent = merge(event, convertSpanJsonToTransactionEvent(processedRootSpanJson));
+        }
+      }
+
+      // 2. Process child spans
       if (processedEvent.spans) {
         const processedSpans: SpanJSON[] = [];
-        for (const span of processedEvent.spans) {
-          const processedSpan = beforeSendSpan(span);
-          if (!processedSpan) {
-            showSpanDropWarning();
-            processedSpans.push(span);
+
+        const initialSpans = processedEvent.spans;
+
+        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)) {
+            reparentChildSpans(initialSpans, span);
+            continue;
+          }
+
+          // 2.b If a `beforeSendSpan` callback is defined, process the child span
+          if (beforeSendSpan) {
+            const processedSpan = beforeSendSpan(span);
+            if (!processedSpan) {
+              showSpanDropWarning();
+              processedSpans.push(span);
+            } else {
+              processedSpans.push(processedSpan);
+            }
           } else {
-            processedSpans.push(processedSpan);
+            processedSpans.push(span);
           }
         }
+
+        const droppedSpans = processedEvent.spans.length - processedSpans.length;
+        if (droppedSpans) {
+          client.recordDroppedEvent('before_send', 'span', droppedSpans);
+        }
         processedEvent.spans = processedSpans;
       }
     }

packages/core/src/envelope.ts

@@ -26,6 +26,7 @@ import {
   getSdkMetadataForEnvelopeHeader,
 } from './utils/envelope';
 import { uuid4 } from './utils/misc';
+import { shouldIgnoreSpan } from './utils/should-ignore-span';
 import { showSpanDropWarning, spanToJSON } from './utils/spanUtils';
 
 /**
@@ -122,7 +123,17 @@ export function createSpanEnvelope(spans: [SentrySpan, ...SentrySpan[]], client?
     ...(!!tunnel && dsn && { dsn: dsnToString(dsn) }),
   };
 
-  const beforeSendSpan = client?.getOptions().beforeSendSpan;
+  const { beforeSendSpan, ignoreSpans } = client?.getOptions() || {};
+
+  const filteredSpans = ignoreSpans?.length
+    ? spans.filter(span => !shouldIgnoreSpan(spanToJSON(span), ignoreSpans))
+    : spans;
+  const droppedSpans = spans.length - filteredSpans.length;
+
+  if (droppedSpans) {
+    client?.recordDroppedEvent('before_send', 'span', droppedSpans);
+  }
+
   const convertToSpanJSON = beforeSendSpan
     ? (span: SentrySpan) => {
         const spanJson = spanToJSON(span);
@@ -138,7 +149,7 @@ export function createSpanEnvelope(spans: [SentrySpan, ...SentrySpan[]], client?
     : spanToJSON;
 
   const items: SpanItem[] = [];
-  for (const span of spans) {
+  for (const span of filteredSpans) {
     const spanJson = convertToSpanJSON(span);
     if (spanJson) {
       items.push(createSpanEnvelopeItem(spanJson));

packages/core/src/types-hoist/options.ts

@@ -10,6 +10,32 @@ import type { StackLineParser, StackParser } from './stacktrace';
 import type { TracePropagationTargets } from './tracing';
 import type { BaseTransportOptions, Transport } from './transport';
 
+/**
+ * A filter object for ignoring spans.
+ * At least one of the properties (`op` or `name`) must be set.
+ */
+type IgnoreSpanFilter =
+  | {
+      /**
+       * 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 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;
+    };
+
 export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOptions> {
   /**
    * Enable debug functionality in the SDK itself. If `debug` is set to `true` the SDK will attempt
@@ -208,6 +234,16 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    */
   ignoreTransactions?: Array<string | RegExp>;
 
+  /**
+   * 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.
+   *
+   * @default []
+   */
+  ignoreSpans?: (string | RegExp | IgnoreSpanFilter)[];
+
   /**
    * A URL to an envelope tunnel endpoint. An envelope tunnel is an HTTP endpoint
    * that accepts Sentry envelopes for forwarding. This can be used to force data

packages/core/src/utils/should-ignore-span.ts

@@ -0,0 +1,66 @@
+import type { ClientOptions } from '../types-hoist/options';
+import type { SpanJSON } from '../types-hoist/span';
+import { isMatchingPattern } from './string';
+
+/**
+ * Check if a span should be ignored based on the ignoreSpans configuration.
+ */
+export function shouldIgnoreSpan(
+  span: Pick<SpanJSON, 'description' | 'op'>,
+  ignoreSpans: Required<ClientOptions>['ignoreSpans'],
+): boolean {
+  if (!ignoreSpans?.length || !span.description) {
+    return false;
+  }
+
+  for (const pattern of ignoreSpans) {
+    if (isStringOrRegExp(pattern)) {
+      if (isMatchingPattern(span.description, pattern)) {
+        return true;
+      }
+      continue;
+    }
+
+    if (!pattern.name && !pattern.op) {
+      continue;
+    }
+
+    const nameMatches = pattern.name ? isMatchingPattern(span.description, pattern.name) : true;
+    const opMatches = pattern.op ? span.op && isMatchingPattern(span.op, pattern.op) : true;
+
+    // This check here is only correct because we can guarantee that we ran `isMatchingPattern`
+    // for at least one of `nameMatches` and `opMatches`. So in contrary to how this looks,
+    // not both op and name actually have to match. This is the most efficient way to check
+    // for all combinations of name and op patterns.
+    if (nameMatches && opMatches) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Takes a list of spans, and a span that was dropped, and re-parents the child spans of the dropped span to the parent of the dropped span, if possible.
+ * This mutates the spans array in place!
+ */
+export function reparentChildSpans(spans: SpanJSON[], dropSpan: SpanJSON): void {
+  const droppedSpanParentId = dropSpan.parent_span_id;
+  const droppedSpanId = dropSpan.span_id;
+
+  // This should generally not happen, as we do not apply this on root spans
+  // but to be safe, we just bail in this case
+  if (!droppedSpanParentId) {
+    return;
+  }
+
+  for (const span of spans) {
+    if (span.parent_span_id === droppedSpanId) {
+      span.parent_span_id = droppedSpanParentId;
+    }
+  }
+}
+
+function isStringOrRegExp(value: unknown): value is string | RegExp {
+  return typeof value === 'string' || value instanceof RegExp;
+}