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

This is the v9 backport of
#17063, which
deprecates the `enableLogs` and `beforeSendLog` under experiments and
move it to be top-level options.

Author: AbhiPrasad

MIGRATION.md

@@ -23,6 +23,30 @@ logger.info('This is an info message');
 debug.log('This is an info message');
 ```
 
+## Deprecated `_experiments.enableLogs` and `_experiments.beforeSendLog` options
+
+The `_experiments.enableLogs` and `_experiments.beforeSendLog` options have been deprecated in favor of the top-level `enableLogs` and `beforeSendLog` options.
+
+```js
+// before
+Sentry.init({
+  _experiments: {
+    enableLogs: true,
+    beforeSendLog: log => {
+      return log;
+    },
+  },
+});
+
+// after
+Sentry.init({
+  enableLogs: true,
+  beforeSendLog: log => {
+    return log;
+  },
+});
+```
+
 # Upgrading from 8.x to 9.x
 
 Version 9 of the Sentry JavaScript SDK primarily introduces API cleanup and version support changes.

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,24 @@ 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;
+    // eslint-disable-next-line deprecation/deprecation
+    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,
     });
   });