feat(core): Deprecate logger in favor of debug (#17040)

resolves #16905

also renames the file to be `debug-logger.ts` instead of `logger.ts` to
make usage inside `@sentry/core` a little easier to understand.

Added a note to `MIGRATION.md`, but let me know if I should remove that.

---------

Co-authored-by: Francesco Gringl-Novy <francesco.novy@sentry.io>

Author: AbhiPrasad

MIGRATION.md

@@ -7,6 +7,22 @@ These docs walk through how to migrate our JavaScript SDKs through different maj
 - Upgrading from [SDK 7.x to 8.x](./docs/migration/v7-to-v8.md)
 - Upgrading from [SDK 8.x to 9.x](#upgrading-from-8x-to-9x)
 
+# Deprecations in 9.x
+
+## Deprecated `@sentry/core` SDK internal `logger` export
+
+The internal SDK `logger` export from `@sentry/core` has been deprecated in favor of the `debug` export. `debug` only exposes `log`, `warn`, and `error` methods but is otherwise identical to `logger`. Note that this deprecation does not affect the `logger` export from other packages (like `@sentry/browser` or `@sentry/node`) which is used for Sentry Logging.
+
+```js
+import { logger, debug } from '@sentry/core';
+
+// before
+logger.info('This is an info message');
+
+// after
+debug.log('This is an info message');
+```
+
 # Upgrading from 8.x to 9.x
 
 Version 9 of the Sentry JavaScript SDK primarily introduces API cleanup and version support changes.

dev-packages/opentelemetry-v2-tests/test/helpers/initOtel.ts

@@ -7,7 +7,7 @@ import {
   ATTR_SERVICE_VERSION,
   SEMRESATTRS_SERVICE_NAMESPACE,
 } from '@opentelemetry/semantic-conventions';
-import { getClient, logger, SDK_VERSION } from '@sentry/core';
+import { debug as debugLogger, getClient, SDK_VERSION } from '@sentry/core';
 import { wrapContextManagerClass } from '../../../../packages/opentelemetry/src/contextManager';
 import { DEBUG_BUILD } from '../../../../packages/opentelemetry/src/debug-build';
 import { SentryPropagator } from '../../../../packages/opentelemetry/src/propagator';
@@ -25,21 +25,23 @@ export function initOtel(): void {
 
   if (!client) {
     DEBUG_BUILD &&
-      logger.warn(
+      debugLogger.warn(
         'No client available, skipping OpenTelemetry setup. This probably means that `Sentry.init()` was not called before `initOtel()`.',
       );
     return;
   }
 
   if (client.getOptions().debug) {
-    const otelLogger = new Proxy(logger as typeof logger & { verbose: (typeof logger)['debug'] }, {
-      get(target, prop, receiver) {
-        const actualProp = prop === 'verbose' ? 'debug' : prop;
-        return Reflect.get(target, actualProp, receiver);
+    diag.setLogger(
+      {
+        error: debugLogger.error,
+        warn: debugLogger.warn,
+        info: debugLogger.log,
+        debug: debugLogger.log,
+        verbose: debugLogger.log,
       },
-    });
-
-    diag.setLogger(otelLogger, DiagLogLevel.DEBUG);
+      DiagLogLevel.DEBUG,
+    );
   }
 
   setupEventContextTrace(client);

dev-packages/opentelemetry-v2-tests/test/integration/transactions.test.ts

@@ -6,7 +6,6 @@ import {
   addBreadcrumb,
   debug,
   getClient,
-  logger,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   setTag,
@@ -503,7 +502,7 @@ describe('Integration | Transactions', () => {
     vi.setSystemTime(now);
 
     const logs: unknown[] = [];
-    vi.spyOn(logger, 'log').mockImplementation(msg => logs.push(msg));
+    vi.spyOn(debug, 'log').mockImplementation(msg => logs.push(msg));
 
     const transactions: Event[] = [];
 
@@ -555,7 +554,7 @@ describe('Integration | Transactions', () => {
     vi.setSystemTime(now);
 
     const logs: unknown[] = [];
-    vi.spyOn(logger, 'log').mockImplementation(msg => logs.push(msg));
+    vi.spyOn(debug, 'log').mockImplementation(msg => logs.push(msg));
 
     const transactions: Event[] = [];
 
@@ -606,7 +605,7 @@ describe('Integration | Transactions', () => {
     vi.setSystemTime(now);
 
     const logs: unknown[] = [];
-    vi.spyOn(logger, 'log').mockImplementation(msg => logs.push(msg));
+    vi.spyOn(debug, 'log').mockImplementation(msg => logs.push(msg));
 
     const transactions: Event[] = [];
 

packages/core/src/breadcrumbs.ts

@@ -1,6 +1,6 @@
 import { getClient, getIsolationScope } from './currentScopes';
 import type { Breadcrumb, BreadcrumbHint } from './types-hoist/breadcrumb';
-import { consoleSandbox } from './utils/logger';
+import { consoleSandbox } from './utils/debug-logger';
 import { dateTimestampInSeconds } from './utils/time';
 
 /**

packages/core/src/carrier.ts

@@ -3,7 +3,7 @@ import type { AsyncContextStrategy } from './asyncContext/types';
 import type { Client } from './client';
 import type { Scope } from './scope';
 import type { SerializedLog } from './types-hoist/log';
-import type { Logger } from './utils/logger';
+import type { Logger } from './utils/debug-logger';
 import { SDK_VERSION } from './utils/version';
 import { GLOBAL_OBJ } from './utils/worldwide';
 
@@ -27,6 +27,7 @@ export interface SentryCarrier {
   defaultIsolationScope?: Scope;
   defaultCurrentScope?: Scope;
   /** @deprecated Logger is no longer set. Instead, we keep enabled state in loggerSettings. */
+  // eslint-disable-next-line deprecation/deprecation
   logger?: Logger;
   loggerSettings?: { enabled: boolean };
   /**

packages/core/src/client.ts

@@ -33,11 +33,11 @@ import type { Span, SpanAttributes, SpanContextData, SpanJSON } from './types-ho
 import type { StartSpanOptions } from './types-hoist/startSpanOptions';
 import type { Transport, TransportMakeRequestResponse } from './types-hoist/transport';
 import { createClientReportEnvelope } from './utils/clientreport';
+import { debug } from './utils/debug-logger';
 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 { debug } from './utils/logger';
 import { merge } from './utils/merge';
 import { checkOrSetAlreadyCaught, uuid4 } from './utils/misc';
 import { parseSampleRate } from './utils/parseSampleRate';

packages/core/src/eventProcessors.ts

@@ -1,8 +1,8 @@
 import { DEBUG_BUILD } from './debug-build';
 import type { Event, EventHint } from './types-hoist/event';
 import type { EventProcessor } from './types-hoist/eventprocessor';
+import { debug } from './utils/debug-logger';
 import { isThenable } from './utils/is';
-import { debug } from './utils/logger';
 import { SyncPromise } from './utils/syncpromise';
 
 /**

packages/core/src/exports.ts

@@ -10,8 +10,8 @@ import type { Primitive } from './types-hoist/misc';
 import type { Session, SessionContext } from './types-hoist/session';
 import type { SeverityLevel } from './types-hoist/severity';
 import type { User } from './types-hoist/user';
+import { debug } from './utils/debug-logger';
 import { isThenable } from './utils/is';
-import { debug } from './utils/logger';
 import { uuid4 } from './utils/misc';
 import type { ExclusiveEventHintOrCaptureContext } from './utils/prepareEvent';
 import { parseEventHintOrCaptureContext } from './utils/prepareEvent';

packages/core/src/index.ts

@@ -165,8 +165,10 @@ export {
   isVueViewModel,
 } from './utils/is';
 export { isBrowser } from './utils/isBrowser';
-export { CONSOLE_LEVELS, consoleSandbox, debug, logger, originalConsoleMethods } from './utils/logger';
-export type { Logger } from './utils/logger';
+// eslint-disable-next-line deprecation/deprecation
+export { CONSOLE_LEVELS, consoleSandbox, debug, logger, originalConsoleMethods } from './utils/debug-logger';
+// eslint-disable-next-line deprecation/deprecation
+export type { Logger } from './utils/debug-logger';
 export {
   addContextToFrame,
   addExceptionMechanism,

packages/core/src/instrument/console.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/ban-types */
 import type { ConsoleLevel, HandlerDataConsole } from '../types-hoist/instrument';
-import { CONSOLE_LEVELS, originalConsoleMethods } from '../utils/logger';
+import { CONSOLE_LEVELS, originalConsoleMethods } from '../utils/debug-logger';
 import { fill } from '../utils/object';
 import { GLOBAL_OBJ } from '../utils/worldwide';
 import { addHandler, maybeInstrument, triggerHandlers } from './handlers';