feat(browser): Add logger.X methods to browser SDK (#15763)

ref #15526

Continuing off the work from
#15717, this PR adds
the logging public API to the Browser SDK. It also adds a basic flushing
strategy to the SDK that is timeout based. This is done to help save
bundle size.

The main file added was `log.ts`. This has three areas to look at:

1. The logger methods for `trace`, `debug`, `info`, `warn`, `error`,
`fatal` (the log severity levels) as well as an internal capture log
helper all these methods call.
2. `addFlushingListeners` which adds listeners to flush the logs buffer
on client flush and document visibility hidden.
3. a flush timeout that flushes logs after X seconds, which gets
restarted when new logs are captured.

I also removed any logs logic from the `BrowserClient`, which should
ensure this stays as bundle size efficient as possible.

Usage:

```js
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "your-dsn-here",
  _experiments: {
    enableLogs: true  // This is required to use the logging features
  }
});

// Trace level (lowest severity)
Sentry.logger.trace("This is a trace message", { userId: 123 });

// Debug level
Sentry.logger.debug("This is a debug message", { component: "UserProfile" });

// Info level
Sentry.logger.info("User logged in successfully", { userId: 123 });

// Warning level
Sentry.logger.warn("API response was slow", { responseTime: 2500 });

// Error level
Sentry.logger.error("Failed to load user data", { userId: 123, errorCode: 404 });

// Critical level
Sentry.logger.critical("Database connection failed", { dbHost: "primary-db" });

// Fatal level (highest severity)
Sentry.logger.fatal("Application is shutting down unexpectedly", { memory: "exhausted" });
```

Author: AbhiPrasad

packages/browser/src/client.ts

@@ -15,7 +15,6 @@ import {
   addAutoIpAddressToUser,
   applySdkMetadata,
   getSDKSource,
-  _INTERNAL_flushLogsBuffer,
 } from '@sentry/core';
 import { eventFromException, eventFromMessage } from './eventbuilder';
 import { WINDOW } from './helpers';
@@ -86,9 +85,6 @@ export class BrowserClient extends Client<BrowserClientOptions> {
       WINDOW.document.addEventListener('visibilitychange', () => {
         if (WINDOW.document.visibilityState === 'hidden') {
           this._flushOutcomes();
-          if (this._options._experiments?.enableLogs) {
-            _INTERNAL_flushLogsBuffer(this);
-          }
         }
       });
     }

packages/browser/src/index.ts

@@ -1,5 +1,9 @@
 export * from './exports';
 
+import * as logger from './log';
+
+export { logger };
+
 export { reportingObserverIntegration } from './integrations/reportingobserver';
 export { httpClientIntegration } from './integrations/httpclient';
 export { contextLinesIntegration } from './integrations/contextlines';

packages/browser/src/log.ts

@@ -0,0 +1,186 @@
+import type { LogSeverityLevel, Log, Client } from '@sentry/core';
+import { getClient, _INTERNAL_captureLog, _INTERNAL_flushLogsBuffer } from '@sentry/core';
+
+import { WINDOW } from './helpers';
+
+/**
+ * TODO: Make this configurable
+ */
+const DEFAULT_FLUSH_INTERVAL = 5000;
+
+let timeout: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * This is a global timeout that is used to flush the logs buffer.
+ * It is used to ensure that logs are flushed even if the client is not flushed.
+ */
+function startFlushTimeout(client: Client): void {
+  if (timeout) {
+    clearTimeout(timeout);
+  }
+
+  timeout = setTimeout(() => {
+    _INTERNAL_flushLogsBuffer(client);
+  }, DEFAULT_FLUSH_INTERVAL);
+}
+
+let isClientListenerAdded = false;
+/**
+ * This is a function that is used to add a flush listener to the client.
+ * It is used to ensure that the logger buffer is flushed when the client is flushed.
+ */
+function addFlushingListeners(client: Client): void {
+  if (isClientListenerAdded || !client.getOptions()._experiments?.enableLogs) {
+    return;
+  }
+
+  isClientListenerAdded = true;
+
+  if (WINDOW.document) {
+    WINDOW.document.addEventListener('visibilitychange', () => {
+      if (WINDOW.document.visibilityState === 'hidden') {
+        _INTERNAL_flushLogsBuffer(client);
+      }
+    });
+  }
+
+  client.on('flush', () => {
+    _INTERNAL_flushLogsBuffer(client);
+  });
+}
+
+/**
+ * Capture a log with the given level.
+ *
+ * @param level - The level of the log.
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * @param severityNumber - The severity number of the log.
+ */
+function captureLog(
+  level: LogSeverityLevel,
+  message: string,
+  attributes?: Log['attributes'],
+  severityNumber?: Log['severityNumber'],
+): void {
+  const client = getClient();
+  if (client) {
+    addFlushingListeners(client);
+
+    startFlushTimeout(client);
+  }
+
+  _INTERNAL_captureLog({ level, message, attributes, severityNumber }, client, undefined);
+}
+
+/**
+ * @summary Capture a log with the `trace` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.trace('Hello world', { userId: 100 });
+ * ```
+ */
+export function trace(message: string, attributes?: Log['attributes']): void {
+  captureLog('trace', message, attributes);
+}
+
+/**
+ * @summary Capture a log with the `debug` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.debug('Hello world', { userId: 100 });
+ * ```
+ */
+export function debug(message: string, attributes?: Log['attributes']): void {
+  captureLog('debug', message, attributes);
+}
+
+/**
+ * @summary Capture a log with the `info` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.info('Hello world', { userId: 100 });
+ * ```
+ */
+export function info(message: string, attributes?: Log['attributes']): void {
+  captureLog('info', message, attributes);
+}
+
+/**
+ * @summary Capture a log with the `warn` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.warn('Hello world', { userId: 100 });
+ * ```
+ */
+export function warn(message: string, attributes?: Log['attributes']): void {
+  captureLog('warn', message, attributes);
+}
+
+/**
+ * @summary Capture a log with the `error` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.error('Hello world', { userId: 100 });
+ * ```
+ */
+export function error(message: string, attributes?: Log['attributes']): void {
+  captureLog('error', message, attributes);
+}
+
+/**
+ * @summary Capture a log with the `fatal` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.fatal('Hello world', { userId: 100 });
+ * ```
+ */
+export function fatal(message: string, attributes?: Log['attributes']): void {
+  captureLog('fatal', message, attributes);
+}
+
+/**
+ * @summary Capture a log with the `critical` level. Requires `_experiments.enableLogs` to be enabled.
+ *
+ * @param message - The message to log.
+ * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ *
+ * @example
+ *
+ * ```
+ * Sentry.logger.critical('Hello world', { userId: 100 });
+ * ```
+ */
+export function critical(message: string, attributes?: Log['attributes']): void {
+  captureLog('critical', message, attributes);
+}

packages/browser/test/index.test.ts

@@ -29,6 +29,7 @@ import {
   getCurrentScope,
   init,
   showReportDialog,
+  logger,
 } from '../src';
 import { getDefaultBrowserClientOptions } from './helper/browser-client-options';
 import { makeSimpleTransport } from './mocks/simpletransport';
@@ -243,20 +244,21 @@ describe('SentryBrowser', () => {
       expect(event.exception.values[0]?.stacktrace.frames).not.toHaveLength(0);
     });
 
-    it('should capture a message', done => {
-      const options = getDefaultBrowserClientOptions({
-        beforeSend: (event: Event): Event | null => {
-          expect(event.level).toBe('info');
-          expect(event.message).toBe('test');
-          expect(event.exception).toBeUndefined();
-          done();
-          return event;
-        },
-        dsn,
-      });
-      setCurrentClient(new BrowserClient(options));
-      captureMessage('test');
-    });
+    it('should capture an message', () =>
+      new Promise<void>(resolve => {
+        const options = getDefaultBrowserClientOptions({
+          beforeSend: event => {
+            expect(event.level).toBe('info');
+            expect(event.message).toBe('test');
+            expect(event.exception).toBeUndefined();
+            resolve();
+            return event;
+          },
+          dsn,
+        });
+        setCurrentClient(new BrowserClient(options));
+        captureMessage('test');
+      }));
 
     it('should capture an event', () =>
       new Promise<void>(resolve => {
@@ -322,6 +324,19 @@ describe('SentryBrowser', () => {
       expect(localBeforeSend).not.toHaveBeenCalled();
     });
   });
+
+  describe('logger', () => {
+    it('exports all log methods', () => {
+      expect(logger).toBeDefined();
+      expect(logger.trace).toBeDefined();
+      expect(logger.debug).toBeDefined();
+      expect(logger.info).toBeDefined();
+      expect(logger.warn).toBeDefined();
+      expect(logger.error).toBeDefined();
+      expect(logger.fatal).toBeDefined();
+      expect(logger.critical).toBeDefined();
+    });
+  });
 });
 
 describe('SentryBrowser initialization', () => {