ref(core): Add debug log when dropping a span via ignoreSpans (#17692)

- Emit a debug log when a span matches `ignoreSpans`
- Adjust the warning when returning `null` in `beforeSendSpan` to
suggest `ignoreSpans` instead

closes #17687

Author: Lms24

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

@@ -1,7 +1,13 @@
+import { DEBUG_BUILD } from '../debug-build';
 import type { ClientOptions } from '../types-hoist/options';
 import type { SpanJSON } from '../types-hoist/span';
+import { debug } from './debug-logger';
 import { isMatchingPattern } from './string';
 
+function logIgnoredSpan(droppedSpan: Pick<SpanJSON, 'description' | 'op'>): void {
+  debug.log(`Ignoring span ${droppedSpan.op} - ${droppedSpan.description} because it matches \`ignoreSpans\`.`);
+}
+
 /**
  * Check if a span should be ignored based on the ignoreSpans configuration.
  */
@@ -16,6 +22,7 @@ export function shouldIgnoreSpan(
   for (const pattern of ignoreSpans) {
     if (isStringOrRegExp(pattern)) {
       if (isMatchingPattern(span.description, pattern)) {
+        DEBUG_BUILD && logIgnoredSpan(span);
         return true;
       }
       continue;
@@ -33,6 +40,7 @@ export function shouldIgnoreSpan(
     // 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) {
+      DEBUG_BUILD && logIgnoredSpan(span);
       return true;
     }
   }

packages/core/src/utils/spanUtils.ts

@@ -323,7 +323,7 @@ export function showSpanDropWarning(): void {
     consoleSandbox(() => {
       // eslint-disable-next-line no-console
       console.warn(
-        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly.',
+        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly or use `ignoreSpans`.',
       );
     });
     hasShownSpanDropWarning = true;

packages/core/test/lib/client.test.ts

@@ -1445,7 +1445,7 @@ describe('Client', () => {
 
       expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
       expect(consoleWarnSpy).toHaveBeenCalledWith(
-        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly.',
+        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly or use `ignoreSpans`.',
       );
       consoleWarnSpy.mockRestore();
     });

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

@@ -190,7 +190,7 @@ describe('SentrySpan', () => {
       expect(recordDroppedEventSpy).not.toHaveBeenCalled();
 
       expect(consoleWarnSpy).toHaveBeenCalledWith(
-        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly.',
+        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly or use `ignoreSpans`.',
       );
       consoleWarnSpy.mockRestore();
     });

packages/core/test/lib/utils/should-ignore-span.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { ClientOptions, SpanJSON } from '../../../src';
+import { debug } from '../../../src/utils/debug-logger';
 import { reparentChildSpans, shouldIgnoreSpan } from '../../../src/utils/should-ignore-span';
 
 describe('shouldIgnoreSpan', () => {
@@ -87,6 +88,16 @@ describe('shouldIgnoreSpan', () => {
     expect(shouldIgnoreSpan(span11, ignoreSpans)).toBe(false);
     expect(shouldIgnoreSpan(span12, ignoreSpans)).toBe(false);
   });
+
+  it('emits a debug log when a span is ignored', () => {
+    const debugLogSpy = vi.spyOn(debug, 'log');
+    const span = { description: 'testDescription', op: 'testOp' };
+    const ignoreSpans = [/test/];
+    expect(shouldIgnoreSpan(span, ignoreSpans)).toBe(true);
+    expect(debugLogSpy).toHaveBeenCalledWith(
+      'Ignoring span testOp - testDescription because it matches `ignoreSpans`.',
+    );
+  });
 });
 
 describe('reparentChildSpans', () => {