feat(core): Introduce debug to replace logger (#16906)

resolves #16903

ref #16901

This PR introduces a `debug` function that aims to replace `logger`.

This gives us a couple of benefits:
1. communicates intent of the export much better
1. avoids collision with `logger` exported from other sdks (which is
used for sentry structured logging)
1. we can move structured logging `logger` code into `@sentry/core`,
reducing duplication across our sdks

We don't deprecate `logger` just yet, we need to convert everything else
in the other SDKs first.

Author: AbhiPrasad

packages/core/src/client.ts

@@ -37,7 +37,7 @@ import { dsnToString, makeDsn } from './utils/dsn';
 import { addItemToEnvelope, createAttachmentEnvelopeItem } from './utils/envelope';
 import { getPossibleEventMessages } from './utils/eventUtils';
 import { isParameterizedString, isPlainObject, isPrimitive, isThenable } from './utils/is';
-import { logger } from './utils/logger';
+import { debug } from './utils/logger';
 import { merge } from './utils/merge';
 import { checkOrSetAlreadyCaught, uuid4 } from './utils/misc';
 import { parseSampleRate } from './utils/parseSampleRate';
@@ -154,7 +154,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     if (options.dsn) {
       this._dsn = makeDsn(options.dsn);
     } else {
-      DEBUG_BUILD && logger.warn('No DSN provided, client will not send events.');
+      DEBUG_BUILD && debug.warn('No DSN provided, client will not send events.');
     }
 
     if (this._dsn) {
@@ -182,7 +182,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
 
     // ensure we haven't captured this very object before
     if (checkOrSetAlreadyCaught(exception)) {
-      DEBUG_BUILD && logger.log(ALREADY_SEEN_ERROR);
+      DEBUG_BUILD && debug.log(ALREADY_SEEN_ERROR);
       return eventId;
     }
 
@@ -237,7 +237,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
 
     // ensure we haven't captured this very object before
     if (hint?.originalException && checkOrSetAlreadyCaught(hint.originalException)) {
-      DEBUG_BUILD && logger.log(ALREADY_SEEN_ERROR);
+      DEBUG_BUILD && debug.log(ALREADY_SEEN_ERROR);
       return eventId;
     }
 
@@ -429,15 +429,15 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     if ('aggregates' in session) {
       const sessionAttrs = session.attrs || {};
       if (!sessionAttrs.release && !clientReleaseOption) {
-        DEBUG_BUILD && logger.warn(MISSING_RELEASE_FOR_SESSION_ERROR);
+        DEBUG_BUILD && debug.warn(MISSING_RELEASE_FOR_SESSION_ERROR);
         return;
       }
       sessionAttrs.release = sessionAttrs.release || clientReleaseOption;
       sessionAttrs.environment = sessionAttrs.environment || clientEnvironmentOption;
       session.attrs = sessionAttrs;
     } else {
       if (!session.release && !clientReleaseOption) {
-        DEBUG_BUILD && logger.warn(MISSING_RELEASE_FOR_SESSION_ERROR);
+        DEBUG_BUILD && debug.warn(MISSING_RELEASE_FOR_SESSION_ERROR);
         return;
       }
       session.release = session.release || clientReleaseOption;
@@ -465,7 +465,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
       // would be `Partial<Record<SentryRequestType, Partial<Record<Outcome, number>>>>`
       // With typescript 4.1 we could even use template literal types
       const key = `${reason}:${category}`;
-      DEBUG_BUILD && logger.log(`Recording outcome: "${key}"${count > 1 ? ` (${count} times)` : ''}`);
+      DEBUG_BUILD && debug.log(`Recording outcome: "${key}"${count > 1 ? ` (${count} times)` : ''}`);
       this._outcomes[key] = (this._outcomes[key] || 0) + count;
     }
   }
@@ -866,12 +866,12 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
 
     if (this._isEnabled() && this._transport) {
       return this._transport.send(envelope).then(null, reason => {
-        DEBUG_BUILD && logger.error('Error while sending envelope:', reason);
+        DEBUG_BUILD && debug.error('Error while sending envelope:', reason);
         return reason;
       });
     }
 
-    DEBUG_BUILD && logger.error('Transport disabled');
+    DEBUG_BUILD && debug.error('Transport disabled');
 
     return resolvedSyncPromise({});
   }
@@ -1021,7 +1021,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     isolationScope = getIsolationScope(),
   ): PromiseLike<string | undefined> {
     if (DEBUG_BUILD && isErrorEvent(event)) {
-      logger.log(`Captured error event \`${getPossibleEventMessages(event)[0] || '<unknown>'}\``);
+      debug.log(`Captured error event \`${getPossibleEventMessages(event)[0] || '<unknown>'}\``);
     }
 
     return this._processEvent(event, hint, currentScope, isolationScope).then(
@@ -1031,11 +1031,11 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
       reason => {
         if (DEBUG_BUILD) {
           if (_isDoNotSendEventError(reason)) {
-            logger.log(reason.message);
+            debug.log(reason.message);
           } else if (_isInternalError(reason)) {
-            logger.warn(reason.message);
+            debug.warn(reason.message);
           } else {
-            logger.warn(reason);
+            debug.warn(reason);
           }
         }
         return undefined;
@@ -1196,22 +1196,22 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    * Sends client reports as an envelope.
    */
   protected _flushOutcomes(): void {
-    DEBUG_BUILD && logger.log('Flushing outcomes...');
+    DEBUG_BUILD && debug.log('Flushing outcomes...');
 
     const outcomes = this._clearOutcomes();
 
     if (outcomes.length === 0) {
-      DEBUG_BUILD && logger.log('No outcomes to send');
+      DEBUG_BUILD && debug.log('No outcomes to send');
       return;
     }
 
     // This is really the only place where we want to check for a DSN and only send outcomes then
     if (!this._dsn) {
-      DEBUG_BUILD && logger.log('No dsn provided, will not send outcomes');
+      DEBUG_BUILD && debug.log('No dsn provided, will not send outcomes');
       return;
     }
 
-    DEBUG_BUILD && logger.log('Sending outcomes:', outcomes);
+    DEBUG_BUILD && debug.log('Sending outcomes:', outcomes);
 
     const envelope = createClientReportEnvelope(outcomes, this._options.tunnel && dsnToString(this._dsn));
 

packages/core/src/eventProcessors.ts

@@ -2,7 +2,7 @@ import { DEBUG_BUILD } from './debug-build';
 import type { Event, EventHint } from './types-hoist/event';
 import type { EventProcessor } from './types-hoist/eventprocessor';
 import { isThenable } from './utils/is';
-import { logger } from './utils/logger';
+import { debug } from './utils/logger';
 import { SyncPromise } from './utils/syncpromise';
 
 /**
@@ -21,7 +21,7 @@ export function notifyEventProcessors(
     } else {
       const result = processor({ ...event }, hint) as Event | null;
 
-      DEBUG_BUILD && processor.id && result === null && logger.log(`Event processor "${processor.id}" dropped event`);
+      DEBUG_BUILD && processor.id && result === null && debug.log(`Event processor "${processor.id}" dropped event`);
 
       if (isThenable(result)) {
         void result

packages/core/src/exports.ts

@@ -11,7 +11,7 @@ import type { Session, SessionContext } from './types-hoist/session';
 import type { SeverityLevel } from './types-hoist/severity';
 import type { User } from './types-hoist/user';
 import { isThenable } from './utils/is';
-import { logger } from './utils/logger';
+import { debug } from './utils/logger';
 import { uuid4 } from './utils/misc';
 import type { ExclusiveEventHintOrCaptureContext } from './utils/prepareEvent';
 import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
@@ -136,9 +136,9 @@ export function captureCheckIn(checkIn: CheckIn, upsertMonitorConfig?: MonitorCo
   const scope = getCurrentScope();
   const client = getClient();
   if (!client) {
-    DEBUG_BUILD && logger.warn('Cannot capture check-in. No client defined.');
+    DEBUG_BUILD && debug.warn('Cannot capture check-in. No client defined.');
   } else if (!client.captureCheckIn) {
-    DEBUG_BUILD && logger.warn('Cannot capture check-in. Client does not support sending check-ins.');
+    DEBUG_BUILD && debug.warn('Cannot capture check-in. Client does not support sending check-ins.');
   } else {
     return client.captureCheckIn(checkIn, upsertMonitorConfig, scope);
   }
@@ -206,7 +206,7 @@ export async function flush(timeout?: number): Promise<boolean> {
   if (client) {
     return client.flush(timeout);
   }
-  DEBUG_BUILD && logger.warn('Cannot flush events. No client defined.');
+  DEBUG_BUILD && debug.warn('Cannot flush events. No client defined.');
   return Promise.resolve(false);
 }
 
@@ -223,7 +223,7 @@ export async function close(timeout?: number): Promise<boolean> {
   if (client) {
     return client.close(timeout);
   }
-  DEBUG_BUILD && logger.warn('Cannot flush events and disable SDK. No client defined.');
+  DEBUG_BUILD && debug.warn('Cannot flush events and disable SDK. No client defined.');
   return Promise.resolve(false);
 }
 

packages/core/src/index.ts

@@ -165,7 +165,7 @@ export {
   isVueViewModel,
 } from './utils/is';
 export { isBrowser } from './utils/isBrowser';
-export { CONSOLE_LEVELS, consoleSandbox, logger, originalConsoleMethods } from './utils/logger';
+export { CONSOLE_LEVELS, consoleSandbox, debug, logger, originalConsoleMethods } from './utils/logger';
 export type { Logger } from './utils/logger';
 export {
   addContextToFrame,

packages/core/src/instrument/handlers.ts

@@ -1,5 +1,5 @@
 import { DEBUG_BUILD } from '../debug-build';
-import { logger } from '../utils/logger';
+import { debug } from '../utils/logger';
 import { getFunctionName } from '../utils/stacktrace';
 
 export type InstrumentHandlerType =
@@ -41,7 +41,7 @@ export function maybeInstrument(type: InstrumentHandlerType, instrumentFn: () =>
     try {
       instrumentFn();
     } catch (e) {
-      DEBUG_BUILD && logger.error(`Error while instrumenting ${type}`, e);
+      DEBUG_BUILD && debug.error(`Error while instrumenting ${type}`, e);
     }
   }
 }
@@ -58,7 +58,7 @@ export function triggerHandlers(type: InstrumentHandlerType, data: unknown): voi
       handler(data);
     } catch (e) {
       DEBUG_BUILD &&
-        logger.error(
+        debug.error(
           `Error while triggering instrumentation handler.\nType: ${type}\nName: ${getFunctionName(handler)}\nError:`,
           e,
         );

packages/core/src/integration.ts

@@ -4,7 +4,7 @@ import { DEBUG_BUILD } from './debug-build';
 import type { Event, EventHint } from './types-hoist/event';
 import type { Integration, IntegrationFn } from './types-hoist/integration';
 import type { Options } from './types-hoist/options';
-import { logger } from './utils/logger';
+import { debug } from './utils/logger';
 
 export const installedIntegrations: string[] = [];
 
@@ -99,7 +99,7 @@ export function afterSetupIntegrations(client: Client, integrations: Integration
 /** Setup a single integration.  */
 export function setupIntegration(client: Client, integration: Integration, integrationIndex: IntegrationIndex): void {
   if (integrationIndex[integration.name]) {
-    DEBUG_BUILD && logger.log(`Integration skipped because it was already installed: ${integration.name}`);
+    DEBUG_BUILD && debug.log(`Integration skipped because it was already installed: ${integration.name}`);
     return;
   }
   integrationIndex[integration.name] = integration;
@@ -130,15 +130,15 @@ export function setupIntegration(client: Client, integration: Integration, integ
     client.addEventProcessor(processor);
   }
 
-  DEBUG_BUILD && logger.log(`Integration installed: ${integration.name}`);
+  DEBUG_BUILD && debug.log(`Integration installed: ${integration.name}`);
 }
 
 /** Add an integration to the current scope's client. */
 export function addIntegration(integration: Integration): void {
   const client = getClient();
 
   if (!client) {
-    DEBUG_BUILD && logger.warn(`Cannot add integration "${integration.name}" because no SDK Client is available.`);
+    DEBUG_BUILD && debug.warn(`Cannot add integration "${integration.name}" because no SDK Client is available.`);
     return;
   }
 

packages/core/src/integrations/dedupe.ts

@@ -4,7 +4,7 @@ import type { Event } from '../types-hoist/event';
 import type { Exception } from '../types-hoist/exception';
 import type { IntegrationFn } from '../types-hoist/integration';
 import type { StackFrame } from '../types-hoist/stackframe';
-import { logger } from '../utils/logger';
+import { debug } from '../utils/logger';
 import { getFramesFromEvent } from '../utils/stacktrace';
 
 const INTEGRATION_NAME = 'Dedupe';
@@ -24,7 +24,7 @@ const _dedupeIntegration = (() => {
       // Juuust in case something goes wrong
       try {
         if (_shouldDropEvent(currentEvent, previousEvent)) {
-          DEBUG_BUILD && logger.warn('Event dropped due to being a duplicate of previously captured event.');
+          DEBUG_BUILD && debug.warn('Event dropped due to being a duplicate of previously captured event.');
           return null;
         }
       } catch (_oO) {} // eslint-disable-line no-empty

packages/core/src/integrations/eventFilters.ts

@@ -4,7 +4,7 @@ import type { Event } from '../types-hoist/event';
 import type { IntegrationFn } from '../types-hoist/integration';
 import type { StackFrame } from '../types-hoist/stackframe';
 import { getPossibleEventMessages } from '../utils/eventUtils';
-import { logger } from '../utils/logger';
+import { debug } from '../utils/logger';
 import { getEventDescription } from '../utils/misc';
 import { stringMatchesSomePattern } from '../utils/string';
 
@@ -111,14 +111,14 @@ function _shouldDropEvent(event: Event, options: Partial<EventFiltersOptions>):
     // Filter errors
     if (_isIgnoredError(event, options.ignoreErrors)) {
       DEBUG_BUILD &&
-        logger.warn(
+        debug.warn(
           `Event dropped due to being matched by \`ignoreErrors\` option.\nEvent: ${getEventDescription(event)}`,
         );
       return true;
     }
     if (_isUselessError(event)) {
       DEBUG_BUILD &&
-        logger.warn(
+        debug.warn(
           `Event dropped due to not having an error message, error type or stacktrace.\nEvent: ${getEventDescription(
             event,
           )}`,
@@ -127,7 +127,7 @@ function _shouldDropEvent(event: Event, options: Partial<EventFiltersOptions>):
     }
     if (_isDeniedUrl(event, options.denyUrls)) {
       DEBUG_BUILD &&
-        logger.warn(
+        debug.warn(
           `Event dropped due to being matched by \`denyUrls\` option.\nEvent: ${getEventDescription(
             event,
           )}.\nUrl: ${_getEventFilterUrl(event)}`,
@@ -136,7 +136,7 @@ function _shouldDropEvent(event: Event, options: Partial<EventFiltersOptions>):
     }
     if (!_isAllowedUrl(event, options.allowUrls)) {
       DEBUG_BUILD &&
-        logger.warn(
+        debug.warn(
           `Event dropped due to not being matched by \`allowUrls\` option.\nEvent: ${getEventDescription(
             event,
           )}.\nUrl: ${_getEventFilterUrl(event)}`,
@@ -148,7 +148,7 @@ function _shouldDropEvent(event: Event, options: Partial<EventFiltersOptions>):
 
     if (_isIgnoredTransaction(event, options.ignoreTransactions)) {
       DEBUG_BUILD &&
-        logger.warn(
+        debug.warn(
           `Event dropped due to being matched by \`ignoreTransactions\` option.\nEvent: ${getEventDescription(event)}`,
         );
       return true;
@@ -212,7 +212,7 @@ function _getEventFilterUrl(event: Event): string | null {
     const frames = rootException?.stacktrace?.frames;
     return frames ? _getLastValidUrl(frames) : null;
   } catch (oO) {
-    DEBUG_BUILD && logger.error(`Cannot extract url for event ${getEventDescription(event)}`);
+    DEBUG_BUILD && debug.error(`Cannot extract url for event ${getEventDescription(event)}`);
     return null;
   }
 }

packages/core/src/integrations/extraerrordata.ts

@@ -5,7 +5,7 @@ import type { ExtendedError } from '../types-hoist/error';
 import type { Event, EventHint } from '../types-hoist/event';
 import type { IntegrationFn } from '../types-hoist/integration';
 import { isError, isPlainObject } from '../utils/is';
-import { logger } from '../utils/logger';
+import { debug } from '../utils/logger';
 import { normalize } from '../utils/normalize';
 import { addNonEnumerableProperty } from '../utils/object';
 import { truncate } from '../utils/string';
@@ -130,7 +130,7 @@ function _extractErrorData(
 
     return extraErrorInfo;
   } catch (oO) {
-    DEBUG_BUILD && logger.error('Unable to extract extra data from the Error object:', oO);
+    DEBUG_BUILD && debug.error('Unable to extract extra data from the Error object:', oO);
   }
 
   return null;

packages/core/src/integrations/supabase.ts

@@ -10,7 +10,7 @@ import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '
 import { setHttpStatus, SPAN_STATUS_ERROR, SPAN_STATUS_OK, startSpan } from '../tracing';
 import type { IntegrationFn } from '../types-hoist/integration';
 import { isPlainObject } from '../utils/is';
-import { logger } from '../utils/logger';
+import { debug } from '../utils/logger';
 
 const AUTH_OPERATIONS_TO_INSTRUMENT = [
   'reauthenticate',
@@ -481,7 +481,7 @@ function instrumentPostgRESTQueryBuilder(PostgRESTQueryBuilder: new () => PostgR
           const rv = Reflect.apply(target, thisArg, argumentsList);
           const PostgRESTFilterBuilder = (rv as PostgRESTFilterBuilder).constructor;
 
-          DEBUG_BUILD && logger.log(`Instrumenting ${operation} operation's PostgRESTFilterBuilder`);
+          DEBUG_BUILD && debug.log(`Instrumenting ${operation} operation's PostgRESTFilterBuilder`);
 
           instrumentPostgRESTFilterBuilder(PostgRESTFilterBuilder);
 
@@ -496,7 +496,7 @@ function instrumentPostgRESTQueryBuilder(PostgRESTQueryBuilder: new () => PostgR
 
 export const instrumentSupabaseClient = (supabaseClient: unknown): void => {
   if (!supabaseClient) {
-    DEBUG_BUILD && logger.warn('Supabase integration was not installed because no Supabase client was provided.');
+    DEBUG_BUILD && debug.warn('Supabase integration was not installed because no Supabase client was provided.');
     return;
   }
   const SupabaseClientConstructor =