feat: Add basic logging support for browser-telemetry.

packages/telemetry/browser-telemetry/__tests__/BrowserTelemetryImpl.test.ts

@@ -208,3 +208,27 @@ it('unregisters collectors on close', () => {
 
   expect(mockCollector.unregister).toHaveBeenCalled();
 });
+
+it('logs event dropped message when maxPendingEvents is reached', () => {
+  const mockLogger = {
+    warn: jest.fn(),
+  };
+  const telemetry = new BrowserTelemetryImpl({
+    ...defaultOptions,
+    maxPendingEvents: 2,
+    logger: mockLogger,
+  });
+  telemetry.captureError(new Error('Test error'));
+  expect(mockLogger.warn).not.toHaveBeenCalled();
+  telemetry.captureError(new Error('Test error 2'));
+  expect(mockLogger.warn).not.toHaveBeenCalled();
+
+  telemetry.captureError(new Error('Test error 3'));
+  expect(mockLogger.warn).toHaveBeenCalledWith(
+    'LaunchDarkly - Browser Telemetry: Maximim pending events reached. Old events will be dropped until the SDK' +
+      ' client is registered.',
+  );
+
+  telemetry.captureError(new Error('Test error 4'));
+  expect(mockLogger.warn).toHaveBeenCalledTimes(1);
+});

packages/telemetry/browser-telemetry/__tests__/logging.test.ts

@@ -0,0 +1,52 @@
+import { MinLogger } from '../src/api';
+import { fallbackLogger, prefixLog, safeMinLogger } from '../src/logging';
+
+afterEach(() => {
+  jest.resetAllMocks();
+});
+
+it('prefixes the message with the telemetry prefix', () => {
+  const message = 'test message';
+  const prefixed = prefixLog(message);
+  expect(prefixed).toBe('LaunchDarkly - Browser Telemetry: test message');
+});
+
+it('uses fallback logger when no logger provided', () => {
+  const spy = jest.spyOn(fallbackLogger, 'warn');
+  const logger = safeMinLogger(undefined);
+
+  logger.warn('test message');
+
+  expect(spy).toHaveBeenCalledWith('test message');
+  spy.mockRestore();
+});
+
+it('uses provided logger when it works correctly', () => {
+  const mockWarn = jest.fn();
+  const testLogger: MinLogger = {
+    warn: mockWarn,
+  };
+
+  const logger = safeMinLogger(testLogger);
+  logger.warn('test message');
+
+  expect(mockWarn).toHaveBeenCalledWith('test message');
+});
+
+it('falls back to fallback logger when provided logger throws', () => {
+  const spy = jest.spyOn(fallbackLogger, 'warn');
+  const testLogger: MinLogger = {
+    warn: () => {
+      throw new Error('logger error');
+    },
+  };
+
+  const logger = safeMinLogger(testLogger);
+  logger.warn('test message');
+
+  expect(spy).toHaveBeenCalledWith('test message');
+  expect(spy).toHaveBeenCalledWith(
+    'LaunchDarkly - Browser Telemetry: The provided logger threw an exception, using fallback logger.',
+  );
+  spy.mockRestore();
+});

packages/telemetry/browser-telemetry/__tests__/options.test.ts

@@ -61,7 +61,7 @@ it('warns when maxPendingEvents is not a number', () => {
 
   expect(outOptions.maxPendingEvents).toEqual(defaultOptions().maxPendingEvents);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "maxPendingEvents" should be of type number, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "maxPendingEvents" should be of type number, got string, using default value',
   );
 });
 
@@ -88,7 +88,7 @@ it('warns when breadcrumbs config is not an object', () => {
 
   expect(outOptions.breadcrumbs).toEqual(defaultOptions().breadcrumbs);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs" should be of type object, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs" should be of type object, got string, using default value',
   );
 });
 
@@ -103,7 +103,7 @@ it('warns when collectors is not an array', () => {
 
   expect(outOptions.collectors).toEqual(defaultOptions().collectors);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "collectors" should be of type Collector[], got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "collectors" should be of type Collector[], got string, using default value',
   );
 });
 
@@ -131,7 +131,7 @@ it('warns when stack config is not an object', () => {
 
   expect(outOptions.stack).toEqual(defaultOptions().stack);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "stack" should be of type object, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "stack" should be of type object, got string, using default value',
   );
 });
 
@@ -150,7 +150,7 @@ it('warns when breadcrumbs.maxBreadcrumbs is not a number', () => {
     defaultOptions().breadcrumbs.maxBreadcrumbs,
   );
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.maxBreadcrumbs" should be of type number, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.maxBreadcrumbs" should be of type number, got string, using default value',
   );
 });
 
@@ -181,7 +181,7 @@ it('warns when breadcrumbs.click is not boolean', () => {
 
   expect(outOptions.breadcrumbs.click).toEqual(defaultOptions().breadcrumbs.click);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.click" should be of type boolean, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.click" should be of type boolean, got string, using default value',
   );
 });
 
@@ -198,7 +198,7 @@ it('warns when breadcrumbs.evaluations is not boolean', () => {
 
   expect(outOptions.breadcrumbs.evaluations).toEqual(defaultOptions().breadcrumbs.evaluations);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.evaluations" should be of type boolean, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.evaluations" should be of type boolean, got string, using default value',
   );
 });
 
@@ -215,7 +215,7 @@ it('warns when breadcrumbs.flagChange is not boolean', () => {
 
   expect(outOptions.breadcrumbs.flagChange).toEqual(defaultOptions().breadcrumbs.flagChange);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.flagChange" should be of type boolean, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.flagChange" should be of type boolean, got string, using default value',
   );
 });
 
@@ -232,7 +232,7 @@ it('warns when breadcrumbs.keyboardInput is not boolean', () => {
 
   expect(outOptions.breadcrumbs.keyboardInput).toEqual(defaultOptions().breadcrumbs.keyboardInput);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.keyboardInput" should be of type boolean, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.keyboardInput" should be of type boolean, got string, using default value',
   );
 });
 
@@ -305,7 +305,7 @@ it('warns when breadcrumbs.http is not an object', () => {
 
   expect(outOptions.breadcrumbs.http).toEqual(defaultOptions().breadcrumbs.http);
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.http" should be of type HttpBreadCrumbOptions | false, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.http" should be of type HttpBreadCrumbOptions | false, got string, using default value',
   );
 });
 
@@ -326,7 +326,7 @@ it('warns when breadcrumbs.http.instrumentFetch is not boolean', () => {
     defaultOptions().breadcrumbs.http.instrumentFetch,
   );
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.http.instrumentFetch" should be of type boolean, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.http.instrumentFetch" should be of type boolean, got string, using default value',
   );
 });
 
@@ -347,7 +347,7 @@ it('warns when breadcrumbs.http.instrumentXhr is not boolean', () => {
     defaultOptions().breadcrumbs.http.instrumentXhr,
   );
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'Config option "breadcrumbs.http.instrumentXhr" should be of type boolean, got string, using default value',
+    'LaunchDarkly - Browser Telemetry: Config option "breadcrumbs.http.instrumentXhr" should be of type boolean, got string, using default value',
   );
 });
 
@@ -417,6 +417,6 @@ it('warns when breadcrumbs.http.customUrlFilter is not a function', () => {
 
   expect(outOptions.breadcrumbs.http.customUrlFilter).toBeUndefined();
   expect(mockLogger.warn).toHaveBeenCalledWith(
-    'The "breadcrumbs.http.customUrlFilter" must be a function. Received string',
+    'LaunchDarkly - Browser Telemetry: The "breadcrumbs.http.customUrlFilter" must be a function. Received string',
   );
 });

packages/telemetry/browser-telemetry/src/BrowserTelemetryImpl.ts

@@ -5,7 +5,7 @@
  */
 import type { LDContext, LDEvaluationDetail, LDInspection } from '@launchdarkly/js-client-sdk';
 
-import { LDClientTracking } from './api';
+import { LDClientTracking, MinLogger } from './api';
 import { Breadcrumb, FeatureManagementBreadcrumb } from './api/Breadcrumb';
 import { BrowserTelemetry } from './api/BrowserTelemetry';
 import { Collector } from './api/Collector';
@@ -18,6 +18,7 @@ import FetchCollector from './collectors/http/fetch';
 import XhrCollector from './collectors/http/xhr';
 import defaultUrlFilter from './filters/defaultUrlFilter';
 import makeInspectors from './inspectors';
+import { fallbackLogger, prefixLog } from './logging';
 import { ParsedOptions, ParsedStackOptions } from './options';
 import randomUuidV4 from './randomUuidV4';
 import parse from './stack/StackParser';
@@ -80,6 +81,11 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
   private _collectors: Collector[] = [];
   private _sessionId: string = randomUuidV4();
 
+  private _logger: MinLogger;
+
+  // Used to ensure we only log the event dropped message once.
+  private _eventsDropped: boolean = false;
+
   constructor(private _options: ParsedOptions) {
     configureTraceKit(_options.stack);
 
@@ -127,16 +133,28 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
     const inspectors: LDInspection[] = [];
     makeInspectors(_options, inspectors, impl);
     this._inspectorInstances.push(...inspectors);
+
+    // Set the initial logger, it may be replaced when the client is registered.
+    // For typescript purposes, we need the logger to be directly set in the constructor.
+    this._logger = this._options.logger ?? fallbackLogger;
   }
 
   register(client: LDClientTracking): void {
     this._client = client;
+    // When the client is registered, we need to set the logger again, because we may be able to use the client's
+    // logger.
+    this._setLogger();
     this._pendingEvents.forEach((event) => {
       this._client?.track(event.type, event.data);
     });
     this._pendingEvents = [];
   }
 
+  private _setLogger() {
+    this._logger =
+      this._options.logger ?? ((this._client as any)?.logger as MinLogger) ?? fallbackLogger;
+  }
+
   inspectors(): LDInspection[] {
     return this._inspectorInstances;
   }
@@ -153,7 +171,14 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
     if (this._client === undefined) {
       this._pendingEvents.push({ type, data: event });
       if (this._pendingEvents.length > this._maxPendingEvents) {
-        // TODO: Log when pending events must be dropped. (SDK-915)
+        if (!this._eventsDropped) {
+          this._eventsDropped = true;
+          this._logger.warn(
+            prefixLog(
+              `Maximim pending events reached. Old events will be dropped until the SDK client is registered.`,
+            ),
+          );
+        }
         this._pendingEvents.shift();
       }
     }

packages/telemetry/browser-telemetry/src/MinLogger.ts → packages/telemetry/browser-telemetry/src/api/MinLogger.ts

@@ -5,5 +5,11 @@
  * This allows usage with multiple SDK versions.
  */
 export interface MinLogger {
+  /**
+   * The warning logger.
+   *
+   * @param args
+   *   A sequence of any JavaScript values.
+   */
   warn(...args: any[]): void;
 }

packages/telemetry/browser-telemetry/src/api/Options.ts

@@ -1,4 +1,5 @@
 import { Collector } from './Collector';
+import { MinLogger } from './MinLogger';
 
 /**
  * Interface for URL filters.
@@ -143,4 +144,15 @@ export interface Options {
    * Configuration that controls the capture of the stack trace.
    */
   stack?: StackOptions;
+
+  /**
+   * Logger to use for warnings.
+   *
+   * This option is compatible with the `LDLogger` interface used by the LaunchDarkly SDK.
+   *
+   * If this option is not provided, the logs will be written to console.log unless the LaunchDarkly SDK is registered,
+   * and the registered SDK instance exposes its logger. In which case, the logs will be written to the registered SDK's
+   * logger. The 3.x SDKs do not expose their logger.
+   */
+  logger?: MinLogger;
 }

packages/telemetry/browser-telemetry/src/api/index.ts

@@ -5,3 +5,4 @@ export * from './Options';
 export * from './Recorder';
 export * from './stack';
 export * from './client';
+export * from './MinLogger';

packages/telemetry/browser-telemetry/src/collectors/http/fetchDecorator.ts

@@ -77,7 +77,7 @@ export default function decorateFetch(callback: (breadcrumb: HttpBreadcrumb) =>
       return response;
     });
   }
-  wrapper.prototype = originalFetch.prototype;
+  wrapper.prototype = originalFetch?.prototype;
 
   try {
     // Use defineProperty to prevent this value from being enumerable.

packages/telemetry/browser-telemetry/src/index.ts

@@ -1,11 +1,12 @@
 import { BrowserTelemetry } from './api/BrowserTelemetry';
 import { Options } from './api/Options';
 import BrowserTelemetryImpl from './BrowserTelemetryImpl';
+import { safeMinLogger } from './logging';
 import parse from './options';
 
 export * from './api';
 
 export function initializeTelemetry(options?: Options): BrowserTelemetry {
-  const parsedOptions = parse(options || {});
+  const parsedOptions = parse(options || {}, safeMinLogger(options?.logger));
   return new BrowserTelemetryImpl(parsedOptions);
 }

packages/telemetry/browser-telemetry/src/logging.ts

@@ -0,0 +1,33 @@
+import { MinLogger } from './api';
+
+export const fallbackLogger: MinLogger = {
+  // Intentionally using console.warn as a fallback logger.
+  // eslint-disable-next-line no-console
+  warn: console.warn,
+};
+
+const loggingPrefix = 'LaunchDarkly - Browser Telemetry:';
+
+export function prefixLog(message: string) {
+  return `${loggingPrefix} ${message}`;
+}
+
+export function safeMinLogger(logger: MinLogger | undefined): MinLogger {
+  return {
+    warn: (...args: any[]) => {
+      if (!logger) {
+        fallbackLogger.warn(...args);
+        return;
+      }
+
+      try {
+        logger.warn(...args);
+      } catch {
+        fallbackLogger.warn(...args);
+        fallbackLogger.warn(
+          prefixLog('The provided logger threw an exception, using fallback logger.'),
+        );
+      }
+    },
+  };
+}