feat: Add basic logging support for browser-telemetry.

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,8 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
   private _collectors: Collector[] = [];
   private _sessionId: string = randomUuidV4();
 
+  private _logger: MinLogger;
+
   constructor(private _options: ParsedOptions) {
     configureTraceKit(_options.stack);
 
@@ -127,16 +130,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 +168,11 @@ 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)
+        this._logger.warn(
+          prefixLog(
+            `Dropping ${this._pendingEvents.length - this._maxPendingEvents} pending events.`,
+          ),
+        );
         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/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.'),
+        );
+      }
+    },
+  };
+}

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

@@ -1,6 +1,7 @@
 import { Collector } from './api/Collector';
+import { MinLogger } from './api/MinLogger';
 import { HttpBreadCrumbOptions, Options, StackOptions, UrlFilter } from './api/Options';
-import { MinLogger } from './MinLogger';
+import { fallbackLogger, prefixLog, safeMinLogger } from './logging';
 
 export function defaultOptions(): ParsedOptions {
   return {
@@ -28,7 +29,9 @@ export function defaultOptions(): ParsedOptions {
 }
 
 function wrongOptionType(name: string, expectedType: string, actualType: string): string {
-  return `Config option "${name}" should be of type ${expectedType}, got ${actualType}, using default value`;
+  return prefixLog(
+    `Config option "${name}" should be of type ${expectedType}, got ${actualType}, using default value`,
+  );
 }
 
 function checkBasic<T>(type: string, name: string, logger?: MinLogger): (item: T) => boolean {
@@ -77,7 +80,9 @@ function parseHttp(
   if (options?.customUrlFilter) {
     if (typeof options.customUrlFilter !== 'function') {
       logger?.warn(
-        `The "breadcrumbs.http.customUrlFilter" must be a function. Received ${typeof options.customUrlFilter}`,
+        prefixLog(
+          `The "breadcrumbs.http.customUrlFilter" must be a function. Received ${typeof options.customUrlFilter}`,
+        ),
       );
     }
   }
@@ -101,6 +106,18 @@ function parseHttp(
   };
 }
 
+function parseLogger(options: Options): MinLogger | undefined {
+  if (options.logger) {
+    const { logger } = options;
+    if (typeof logger === 'object' && logger !== null && 'warn' in logger) {
+      return safeMinLogger(logger);
+    }
+    // Using console.warn here because the logger is not suitable to log with.
+    fallbackLogger.warn(wrongOptionType('logger', 'MinLogger or LDLogger', typeof logger));
+  }
+  return undefined;
+}
+
 function parseStack(
   options: StackOptions | undefined,
   defaults: ParsedStackOptions,
@@ -175,10 +192,11 @@ export default function parse(options: Options, logger?: MinLogger): ParsedOptio
         if (Array.isArray(item)) {
           return true;
         }
-        logger?.warn(logger?.warn(wrongOptionType('collectors', 'Collector[]', typeof item)));
+        logger?.warn(wrongOptionType('collectors', 'Collector[]', typeof item));
         return false;
       }),
     ],
+    logger: parseLogger(options),
   };
 }
 
@@ -282,4 +300,9 @@ export interface ParsedOptions {
    * Additional, or custom, collectors.
    */
   collectors: Collector[];
+
+  /**
+   * Logger to use for warnings.
+   */
+  logger?: MinLogger;
 }