feat(v9/core): Deprecate experimental enableLogs and beforeSendLog option

dev-packages/browser-integration-tests/suites/public-api/logger/init.js

@@ -4,7 +4,5 @@ window.Sentry = Sentry;
 
 Sentry.init({
   dsn: 'https://[email protected]/1337',
-  _experiments: {
-    enableLogs: true,
-  },
+  enableLogs: true,
 });

dev-packages/browser-integration-tests/suites/public-api/logger/integration/init.js

@@ -4,8 +4,6 @@ window.Sentry = Sentry;
 
 Sentry.init({
   dsn: 'https://[email protected]/1337',
-  _experiments: {
-    enableLogs: true,
-  },
+  enableLogs: true,
   integrations: [Sentry.consoleLoggingIntegration()],
 });

dev-packages/e2e-tests/test-applications/node-express/src/app.ts

@@ -13,9 +13,7 @@ Sentry.init({
   debug: !!process.env.DEBUG,
   tunnel: `http://localhost:3031/`, // proxy server
   tracesSampleRate: 1,
-  _experiments: {
-    enableLogs: true,
-  },
+  enableLogs: true,
 });
 
 import { TRPCError, initTRPC } from '@trpc/server';

dev-packages/node-core-integration-tests/suites/winston/subject.ts

@@ -8,9 +8,7 @@ const client = Sentry.init({
   dsn: 'https://[email protected]/1337',
   release: '1.0.0',
   environment: 'test',
-  _experiments: {
-    enableLogs: true,
-  },
+  enableLogs: true,
   transport: loggingTransport,
 });
 

dev-packages/node-integration-tests/suites/winston/subject.ts

@@ -7,9 +7,7 @@ Sentry.init({
   dsn: 'https://[email protected]/1337',
   release: '1.0.0',
   environment: 'test',
-  _experiments: {
-    enableLogs: true,
-  },
+  enableLogs: true,
   transport: loggingTransport,
 });
 

packages/browser/src/client.ts

@@ -85,23 +85,23 @@ export class BrowserClient extends Client<BrowserClientOptions> {
 
     super(opts);
 
-    const { sendDefaultPii, sendClientReports, _experiments } = this._options;
-    const enableLogs = _experiments?.enableLogs;
+    const { sendDefaultPii, sendClientReports, enableLogs, _experiments } = this._options;
+    const shouldEnableLogs = enableLogs ?? _experiments?.enableLogs;
 
-    if (WINDOW.document && (sendClientReports || enableLogs)) {
+    if (WINDOW.document && (sendClientReports || shouldEnableLogs)) {
       WINDOW.document.addEventListener('visibilitychange', () => {
         if (WINDOW.document.visibilityState === 'hidden') {
           if (sendClientReports) {
             this._flushOutcomes();
           }
-          if (enableLogs) {
+          if (shouldEnableLogs) {
             _INTERNAL_flushLogsBuffer(this);
           }
         }
       });
     }
 
-    if (enableLogs) {
+    if (shouldEnableLogs) {
       this.on('flush', () => {
         _INTERNAL_flushLogsBuffer(this);
       });

packages/browser/src/log.ts

@@ -19,7 +19,7 @@ function captureLog(
 }
 
 /**
- * @summary Capture a log with the `trace` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `trace` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { userId: 100, route: '/dashboard' }.
@@ -48,7 +48,7 @@ export function trace(message: ParameterizedString, attributes?: Log['attributes
 }
 
 /**
- * @summary Capture a log with the `debug` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `debug` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { component: 'Header', state: 'loading' }.
@@ -78,7 +78,7 @@ export function debug(message: ParameterizedString, attributes?: Log['attributes
 }
 
 /**
- * @summary Capture a log with the `info` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `info` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { feature: 'checkout', status: 'completed' }.
@@ -108,7 +108,7 @@ export function info(message: ParameterizedString, attributes?: Log['attributes'
 }
 
 /**
- * @summary Capture a log with the `warn` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `warn` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { browser: 'Chrome', version: '91.0' }.
@@ -139,7 +139,7 @@ export function warn(message: ParameterizedString, attributes?: Log['attributes'
 }
 
 /**
- * @summary Capture a log with the `error` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `error` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { error: 'NetworkError', url: '/api/data' }.
@@ -171,7 +171,7 @@ export function error(message: ParameterizedString, attributes?: Log['attributes
 }
 
 /**
- * @summary Capture a log with the `fatal` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `fatal` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { appState: 'corrupted', sessionId: 'abc-123' }.

packages/browser/test/client.test.ts

@@ -27,7 +27,6 @@ describe('BrowserClient', () => {
   it('does not flush logs when logs are disabled', () => {
     client = new BrowserClient(
       getDefaultBrowserClientOptions({
-        _experiments: { enableLogs: false },
         sendClientReports: true,
       }),
     );
@@ -50,7 +49,7 @@ describe('BrowserClient', () => {
       vi.useFakeTimers();
       client = new BrowserClient(
         getDefaultBrowserClientOptions({
-          _experiments: { enableLogs: true },
+          enableLogs: true,
           sendClientReports: true,
         }),
       );

packages/browser/test/log.test.ts

@@ -42,9 +42,7 @@ describe('Logger', () => {
     init({
       dsn,
       transport: makeSimpleTransport,
-      _experiments: {
-        enableLogs: true,
-      },
+      enableLogs: true,
     });
   });
 

packages/cloudflare/src/logs/exports.ts

@@ -19,7 +19,7 @@ function captureLog(
 }
 
 /**
- * @summary Capture a log with the `trace` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `trace` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { userId: 100, route: '/dashboard' }.
@@ -48,7 +48,7 @@ export function trace(message: ParameterizedString, attributes?: Log['attributes
 }
 
 /**
- * @summary Capture a log with the `debug` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `debug` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { component: 'Header', state: 'loading' }.
@@ -78,7 +78,7 @@ export function debug(message: ParameterizedString, attributes?: Log['attributes
 }
 
 /**
- * @summary Capture a log with the `info` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `info` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { feature: 'checkout', status: 'completed' }.
@@ -108,7 +108,7 @@ export function info(message: ParameterizedString, attributes?: Log['attributes'
 }
 
 /**
- * @summary Capture a log with the `warn` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `warn` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { browser: 'Chrome', version: '91.0' }.
@@ -139,7 +139,7 @@ export function warn(message: ParameterizedString, attributes?: Log['attributes'
 }
 
 /**
- * @summary Capture a log with the `error` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `error` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { error: 'NetworkError', url: '/api/data' }.
@@ -171,7 +171,7 @@ export function error(message: ParameterizedString, attributes?: Log['attributes
 }
 
 /**
- * @summary Capture a log with the `fatal` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `fatal` level. Requires the `enableLogs` option to be enabled.
  *
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., { appState: 'corrupted', sessionId: 'abc-123' }.

packages/core/src/logs/console-integration.ts

@@ -33,9 +33,11 @@ const _consoleLoggingIntegration = ((options: Partial<CaptureConsoleOptions> = {
   return {
     name: INTEGRATION_NAME,
     setup(client) {
-      const { _experiments, normalizeDepth = 3, normalizeMaxBreadth = 1_000 } = client.getOptions();
-      if (!_experiments?.enableLogs) {
-        DEBUG_BUILD && debug.warn('`_experiments.enableLogs` is not enabled, ConsoleLogs integration disabled');
+      const { enableLogs, _experiments, normalizeDepth = 3, normalizeMaxBreadth = 1_000 } = client.getOptions();
+      // eslint-disable-next-line deprecation/deprecation
+      const shouldEnableLogs = enableLogs ?? _experiments?.enableLogs;
+      if (!shouldEnableLogs) {
+        DEBUG_BUILD && debug.warn('`enableLogs` is not enabled, ConsoleLogs integration disabled');
         return;
       }
 
@@ -69,7 +71,7 @@ const _consoleLoggingIntegration = ((options: Partial<CaptureConsoleOptions> = {
 }) satisfies IntegrationFn;
 
 /**
- * Captures calls to the `console` API as logs in Sentry. Requires `_experiments.enableLogs` to be enabled.
+ * Captures calls to the `console` API as logs in Sentry. Requires the `enableLogs` option to be enabled.
  *
  * @experimental This feature is experimental and may be changed or removed in future versions.
  *
@@ -83,6 +85,7 @@ const _consoleLoggingIntegration = ((options: Partial<CaptureConsoleOptions> = {
  * import * as Sentry from '@sentry/browser';
  *
  * Sentry.init({
+ *   enableLogs: true,
  *   integrations: [Sentry.consoleLoggingIntegration({ levels: ['error', 'warn'] })],
  * });
  * ```

packages/core/src/logs/exports.ts

@@ -124,12 +124,15 @@ export function _INTERNAL_captureLog(
     return;
   }
 
-  const { _experiments, release, environment } = client.getOptions();
-  const { enableLogs = false, beforeSendLog } = _experiments ?? {};
-  if (!enableLogs) {
+  const { release, environment, enableLogs, beforeSendLog, _experiments } = client.getOptions();
+  // eslint-disable-next-line deprecation/deprecation
+  const shouldEnableLogs = enableLogs ?? _experiments?.enableLogs;
+  if (!shouldEnableLogs) {
     DEBUG_BUILD && debug.warn('logging option not enabled, log will not be captured.');
     return;
   }
+  // eslint-disable-next-line deprecation/deprecation
+  const actualBeforeSendLog = beforeSendLog ?? _experiments?.beforeSendLog;
 
   const [, traceContext] = _getTraceInfoFromScope(client, currentScope);
 
@@ -169,7 +172,7 @@ export function _INTERNAL_captureLog(
   client.emit('beforeCaptureLog', processedLog);
 
   // We need to wrap this in `consoleSandbox` to avoid recursive calls to `beforeSendLog`
-  const log = beforeSendLog ? consoleSandbox(() => beforeSendLog(processedLog)) : processedLog;
+  const log = actualBeforeSendLog ? consoleSandbox(() => actualBeforeSendLog(processedLog)) : processedLog;
   if (!log) {
     client.recordDroppedEvent('before_send', 'log_item', 1);
     DEBUG_BUILD && debug.warn('beforeSendLog returned null, log will not be captured.');

packages/core/src/server-runtime-client.ts

@@ -49,7 +49,9 @@ export class ServerRuntimeClient<
 
     this._logWeight = 0;
 
-    if (this._options._experiments?.enableLogs) {
+    // eslint-disable-next-line deprecation/deprecation
+    const shouldEnableLogs = this._options.enableLogs ?? this._options._experiments?.enableLogs;
+    if (shouldEnableLogs) {
       // eslint-disable-next-line @typescript-eslint/no-this-alias
       const client = this;
 

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

@@ -246,19 +246,25 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
   _experiments?: {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     [key: string]: any;
+
     /**
      * If logs support should be enabled.
      *
+     * @deprecated Use the top-level `enableLogs` option instead.
+     *
      * @default false
      */
     enableLogs?: boolean;
+
     /**
      * An event-processing callback for logs, guaranteed to be invoked after all other log
      * processors. This allows a log to be modified or dropped before it's sent.
      *
      * Note that you must return a valid log from this callback. If you do not wish to modify the log, simply return
      * it at the end. Returning `null` will cause the log to be dropped.
      *
+     * @deprecated Use the top-level `beforeSendLog` option instead.
+     *
      * @default undefined
      *
      * @param log The log generated by the SDK.
@@ -328,6 +334,27 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    */
   orgId?: `${number}` | number;
 
+  /**
+   * If logs support should be enabled.
+   *
+   * @default false
+   */
+  enableLogs?: boolean;
+
+  /**
+   * An event-processing callback for logs, guaranteed to be invoked after all other log
+   * processors. This allows a log to be modified or dropped before it's sent.
+   *
+   * Note that you must return a valid log from this callback. If you do not wish to modify the log, simply return
+   * it at the end. Returning `null` will cause the log to be dropped.
+   *
+   * @default undefined
+   *
+   * @param log The log generated by the SDK.
+   * @returns A new log that will be sent | null.
+   */
+  beforeSendLog?: (log: Log) => Log | null;
+
   /**
    * Function to compute tracing sample rate dynamically and filter unwanted traces.
    *