@crimson-education/browser-logger 2.0.2 → 3.0.0

package/src/index.ts

@@ -1,234 +1,64 @@
-import {
-  ILogger,
-  IReporter,
-  Metadata,
-  ReporterBreadcrumb,
-  ReporterEvent,
-  ReporterFilters,
-  ReportError,
-  ReportUser,
-  ServiceInfo,
-  TrackedReporterEvent,
-} from './types';
-import { consoleLogger } from './utils';
-import {
-  datadogLogger,
-  datadogReporter,
-  DatadogReporterConfig,
-  gtmReporter,
-  GTMReporterConfig,
-  amplifyReporter,
-  AmplifyReporterConfig,
-} from './reporters';
+import { ReporterConfigurations, ServiceInfo } from './types';
+import { setLogLevel } from './logger';
+import { addMetadata, reporters, setEventLevel } from './reporters';
+import { gtmReporter } from './reporters/gtmReporter';
+import { amplifyReporter } from './reporters/amplifyReporter';
+import { datadogReporter } from './reporters/datadogReporter';
+import { logReporter } from './reporters/logReporter';
 
 export * from './types';
+export * from './reporters';
+export * from './logger';
 
-export let logger: ILogger | null = null;
+export type LoggerConfig = ServiceInfo & { reporters?: ReporterConfigurations };
 
-export type ReporterType = 'datadog' | 'gtm' | 'amplify';
-
-export type ReporterConfig = ServiceInfo & {
-  // Datadog
-  datadog?: DatadogReporterConfig;
-
-  // Amplify/Pinpoint
-  amplify?: AmplifyReporterConfig;
-
-  // Google Tag Manager
-  gtm?: true | GTMReporterConfig;
-};
-
-const reporters: Partial<Record<ReporterType, IReporter>> = {};
 let initialized = false;
-let ddInitialized = false;
 
 /**
  * Initializes the logger and reporters.
  * @param config Reporter config options.
  */
-export function init(config: ReporterConfig) {
-  initialized = true;
-
-  if (config.datadog) {
-    reporters['datadog'] = datadogReporter(config, config.datadog);
-    ddInitialized = true;
-  }
-
-  if (config.amplify) {
-    reporters['amplify'] = amplifyReporter(config, config.amplify);
-  }
-
-  if (config.gtm) {
-    reporters['gtm'] = gtmReporter(config, typeof config.gtm === 'boolean' ? {} : config.gtm);
-  }
-
-  if (config.defaultMetadata) {
-    for (const reporter of Object.values(reporters)) {
-      reporter.addMetadata(config.defaultMetadata);
-    }
-  }
-
-  logger = createLogger('Reporter');
-}
-
-/**
- * Gets reporters, optionally with filters.
- * @param filters Filters to remove or specify specific reporters.
- * @returns Selected reporters, or all registered reporters.
- */
-function getReporters(filters?: ReporterFilters) {
-  let result = Object.entries(reporters);
-  if (filters?.excludeReporters) {
-    result = result.filter(([key]) => !filters?.excludeReporters?.includes(key as ReporterType));
-  }
-  if (filters?.toReporters) {
-    result = result.filter(([key]) => filters?.toReporters?.includes(key as ReporterType));
-  }
-  return result.map(([, reporter]) => reporter);
-}
-
-/**
- * Tracks an Analytics event.
- */
-export function trackEvent(event: ReporterEvent): void {
-  for (const reporter of getReporters(event)) {
-    reporter.trackEvent(event);
-  }
-}
-
-/**
- * Tracks an Analytics event, recording the time since the last event, if available.
- */
-export function trackEventSinceLastAction(event: ReporterEvent): void {
-  const lastEvent = getLastTrackedEvent();
-  if (lastEvent) {
-    const duration = new Date().getTime() - lastEvent.occurred.getTime();
-    trackEvent({
-      ...event,
-      metadata: {
-        ...event.metadata,
-        lastEventName: lastEvent.message,
-        timeSinceLastEvent: duration,
-      },
-    });
-  } else {
-    trackEvent(event);
-  }
-  sessionStorage.setItem('loggerLastEvent', JSON.stringify({ ...event, occurred: new Date() }));
-}
-
-/**
- * Gets the last tracked event, if available.
- */
-export function getLastTrackedEvent(): TrackedReporterEvent | null {
-  const eventStr = sessionStorage.getItem('loggerLastEvent');
-  if (!eventStr) return null;
-
-  const event: TrackedReporterEvent = JSON.parse(eventStr);
-  event.occurred = new Date(event.occurred);
-  return event;
-}
-
-/**
- * Breadcrumbs to create a trail of events that happened prior to an issue.
- * These events are very similar to traditional logs, but can record more rich structured data.
- */
-export function addBreadcrumb(breadcrumb: ReporterBreadcrumb): void {
-  for (const reporter of getReporters(breadcrumb)) {
-    reporter.addBreadcrumb(breadcrumb);
+export function init(config: LoggerConfig) {
+  // Some reporters don't like being initialized multiple times.
+  if (initialized) {
+    return;
   }
-}
-
-/**
- * Adds global metadata to all events.
- * @param metadata Metadata to add.
- * @param filters Optional filters to specify which reporters to add metadata to.
- */
-export function addMetadata(metadata: Metadata, filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.addMetadata(metadata);
-  }
-}
+  initialized = true;
 
-/**
- * Sets the user information in Analytics.
- * @param user User information, or null to clear.
- * @param filters Optional filters to specify which reporters to set the user for.
- */
-export function setUser(user: ReportUser | null, filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.setUser(user);
+  // Log Reporter enabled by default.
+  const logReporterConfig = config.reporters?.log ?? true;
+  if (logReporterConfig !== false) {
+    reporters['log'] = logReporter(config, typeof logReporterConfig === 'boolean' ? {} : logReporterConfig);
   }
-}
 
-/**
- * Sets the route name in Analytics.
- * Some Analytics services use this differentiate SPA Route vs Page changes.
- * @param routeName Name of the Route.
- * @param filters Optional filters to specify which reporters to set the route name for.
- */
-export function setRouteName(routeName: string, filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.setRouteName(routeName);
+  if (config.reporters?.datadog) {
+    reporters['datadog'] = datadogReporter(config, config.reporters.datadog);
   }
-}
 
-/**
- * Sets the page name in Analytics.
- * @param pageName Name of the Page.
- * @param filters Optional filters to specify which reporters to set the page name for.
- */
-export function setPageName(pageName: string, filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.setPageName(pageName);
+  if (config.reporters?.amplify) {
+    reporters['amplify'] = amplifyReporter(config, config.reporters.amplify);
   }
-}
 
-/**
- * Reports an Error in Reporters that support error tracking.
- * @param error Error data.
- * @param metadata Metadata to add to the error.
- * @param filters Optional filters to specify which reporters to report the error to.
- */
-export function reportError(error: ReportError, metadata?: Metadata, filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.reportError?.(error, metadata);
+  if (config.reporters?.gtm) {
+    reporters['gtm'] = gtmReporter(config, typeof config.reporters.gtm === 'boolean' ? {} : config.reporters.gtm);
   }
-}
 
-/**
- * Starts a session recording in Analytics, e.g. RUM Session Replay
- * @param filters Optional filters to specify which reporters to start a session recording for.
- */
-export function recordSession(filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.recordSession?.();
-  }
-}
+  const defaultMetadata = {
+    ...(config.defaultMetadata ?? {}),
+    service: config.service,
+    environment: config.environment,
+    version: config.version,
+  };
 
-/**
- * Stops a session recording in Analytics, e.g. RUM Session Replay
- * @param filters Optional filters to specify which reporters to stop a session recording for.
- */
-export function recordSessionStop(filters?: ReporterFilters): void {
-  for (const reporter of getReporters(filters)) {
-    reporter.recordSessionStop?.();
+  // Sets the global log level, if specified.
+  if (config.logLevel) {
+    setLogLevel(config.logLevel);
   }
-}
 
-/**
- * Creates a Logger instance.
- * @param name Name of the Logger.
- * @param options Logger configuration options.
- */
-export function createLogger(name?: string, options?: { metadata?: Metadata }): ILogger {
-  if (!initialized) {
-    throw new Error('You must call init on BrowserLogger before creating a logger');
+  // Sets the global event level, if specified.
+  if (config.eventLevel) {
+    setEventLevel(config.eventLevel);
   }
 
-  if (ddInitialized) {
-    return datadogLogger(name, options);
-  } else {
-    return consoleLogger(name, options);
-  }
+  addMetadata(defaultMetadata);
 }

package/src/logger/consoleTransport.ts

@@ -0,0 +1,101 @@
+import { ILogTransport, LogLevel, LogTransportConfigBase } from '../types';
+
+// from browser-util-inspect
+const colors = {
+  bold: [1, 22],
+  italic: [3, 23],
+  underline: [4, 24],
+  inverse: [7, 27],
+  white: [37, 39],
+  grey: [90, 39],
+  black: [30, 39],
+  blue: [34, 39],
+  cyan: [36, 39],
+  green: [32, 39],
+  magenta: [35, 39],
+  red: [31, 39],
+  yellow: [33, 39],
+};
+export type ColorizeColor = keyof typeof colors;
+
+/**
+ * Colorize a string with a specified color.
+ * @param str String to colorize
+ * @param color Color to colorize the string with
+ * @returns Colorized string
+ */
+export function colorize(str: string, color: ColorizeColor) {
+  const colorData = colors[color];
+  return '\u001b[' + colorData[0] + 'm' + str + '\u001b[' + colorData[1] + 'm';
+}
+
+/**
+ * Gets a stack trace from metadata or accompanying error.
+ */
+function getStackTrace(data: any) {
+  const stack = data?.err?.stack || data.stack || data['error.stack'];
+  delete data.stack;
+  return stack ?? '';
+}
+
+export interface ConsoleLogTransportConfig extends LogTransportConfigBase {
+  /**
+   * Add colors to log messages.
+   */
+  colorize?: false | typeof colorize;
+
+  /**
+   * Gets the color for the log level.
+   */
+  getLogLevelColor?: (level: LogLevel) => ColorizeColor;
+}
+
+export function consoleTransport(config: ConsoleLogTransportConfig = {}) {
+  // Default ignore patterns
+  config.ignoreMetadataPatterns ??= ['application', 'service', 'environment', 'version'];
+
+  // Get the colorizer function, or a no-op if not enabled.
+  const colorizer = config.colorize !== false ? config.colorize ?? colorize : (str: string) => str;
+
+  // Get the log level color function, or use the default colors.
+  const getLogLevelColor =
+    config.getLogLevelColor ??
+    ((level) => {
+      return {
+        error: 'red',
+        warn: 'yellow',
+        info: 'cyan',
+        debug: 'green',
+      }[level] as ColorizeColor;
+    });
+
+  const transport: ILogTransport & ConsoleLogTransportConfig = {
+    ...config,
+    log: ({ level, message, timestamp, splat, ...metadata }) => {
+      let splatData = splat ?? [];
+      const stackTrace = getStackTrace(metadata);
+
+      const strippedInfo: any = { ...metadata };
+      delete strippedInfo['level'];
+      delete strippedInfo['message'];
+      delete strippedInfo['splat'];
+      delete strippedInfo['timestamp'];
+      delete strippedInfo['stack'];
+
+      if (Object.keys(strippedInfo).length > 0) {
+        splatData = [strippedInfo, ...splatData];
+      }
+
+      if (message) {
+        splatData = [message, ...splatData];
+      }
+
+      if (stackTrace) {
+        splatData = [...splatData, stackTrace];
+      }
+
+      console.log(`${colorizer(timestamp, 'magenta')} ${colorizer(level, getLogLevelColor(level))}: `, ...splatData);
+    },
+  };
+  return transport;
+}

package/src/logger/datadogTransport.ts

@@ -0,0 +1,20 @@
+import { ILogTransport, LogTransportConfigBase } from '../types';
+import { getLogMessage } from './utils';
+import { datadogLogs } from '@datadog/browser-logs';
+
+export type DatadogLogTransportConfig = LogTransportConfigBase;
+
+/**
+ * A transport that sends logs to Datadog.
+ * Note: This requires the datadog reporter to be initialized for it to work.
+ */
+export function datadogTransport(config: DatadogLogTransportConfig = {}) {
+  const transport: ILogTransport = {
+    ...config,
+    log: ({ level, message, ...metadata }) => {
+      // Datadog expects a string message.
+      datadogLogs.logger[level](getLogMessage(message), metadata);
+    },
+  };
+  return transport;
+}

package/src/logger/index.test.ts

@@ -0,0 +1,68 @@
+import { createLogger, setLogLevel as setGlobalLogLevel, logTransports, consoleTransport } from '.';
+import { init } from '..';
+import { addMetadata, setUser } from '../reporters';
+import { LogLevel } from '../types';
+
+// This isn't actually asserting anything.
+// But it ensures that the logs look correct, and no errors get thrown.
+describe('logger', () => {
+  const logger = createLogger({
+    metadata: {
+      service: 'test',
+    },
+  });
+
+  // Manually set the log transports.
+  logTransports.length = 0;
+  const transport = consoleTransport({
+    // So we can see everything.
+    ignoreMetadataPatterns: [],
+  });
+  logTransports.push(transport);
+
+  it('should log', async () => {
+    logger.log({
+      level: 'info',
+      message: 'data',
+    });
+    logger.log({ data: 'obj' });
+    logger.log(LogLevel.Debug, 'level, message', { data: 'obj' });
+    logger.log(LogLevel.Debug, 'level, message, metadata', { data: 'obj' });
+
+    init({
+      service: 'test-service',
+      environment: 'test',
+      version: 'no-version',
+      defaultMetadata: {
+        application: 'test',
+      },
+    });
+
+    const infoLogger = logger.child({ isLevel: 'info' });
+    infoLogger.info('info call, message');
+    infoLogger.info('info call, message, metadata', { data: 'metadataobj' });
+
+    const timer = logger.startTimer();
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    timer.done({ message: 'timer done', metadata: { id: 1 } });
+
+    setGlobalLogLevel(LogLevel.Info);
+    addMetadata({ global: 'metadata' });
+
+    logger.debug('You should not see this');
+    logger.info('You should see this with { global: "metadata" }');
+
+    setGlobalLogLevel(null);
+    setUser({
+      id: '123',
+      email: 'test@example.com',
+    });
+
+    logger.debug('debug call, user metadata');
+
+    transport.logLevel = LogLevel.Info;
+    logger.debug('You should not see this');
+    logger.info('You should see this');
+    transport.logLevel = undefined;
+  });
+});

package/src/logger/index.ts

@@ -0,0 +1,139 @@
+/* eslint-disable prefer-rest-params */
+import { ILogger, ILogTransport, LoggerOptions, LogLevel, Metadata, Profiler, StructuredLog } from '../types';
+import { filterReporterMetadata } from '../utils';
+import { consoleTransport } from './consoleTransport';
+import { getLogMessage, isAboveLevel } from './utils';
+
+export * from './consoleTransport';
+export * from './datadogTransport';
+
+export const globalMetadata: Metadata = {};
+
+export const logTransports: ILogTransport[] = [consoleTransport()];
+
+export let globalLogLevel: LogLevel | undefined;
+/**
+ * Sets the global log level.
+ */
+export function setLogLevel(level: LogLevel | null): void {
+  globalLogLevel = level ?? undefined;
+}
+
+/**
+ * Creates a Logger Instance.
+ */
+export function createLogger(options: LoggerOptions = {}): ILogger {
+  const rootMetadata = options.metadata ?? {};
+
+  const logger: ILogger = {
+    // impl loosely based on Winston Logger's dynamic log function
+    // https://github.com/winstonjs/winston/blob/master/lib/winston/logger.js
+    log() {
+      let logInfo: StructuredLog;
+
+      // Optimize for the hotpath of logging JSON literals
+      if (arguments.length === 1) {
+        logInfo = {
+          level: LogLevel.Info,
+          ...arguments[0],
+        };
+      }
+      // Slightly less hotpath, but worth optimizing for.
+      else if (arguments.length === 2) {
+        const [level, message] = Array.from(arguments);
+        if (message && typeof message === 'object') {
+          logInfo = {
+            ...message,
+            level: message.level ?? level,
+          };
+        } else {
+          logInfo = {
+            level,
+            message,
+          };
+        }
+      } else {
+        const [level, message, ...splat] = Array.from(arguments);
+
+        const [meta] = splat;
+        if (typeof meta === 'object' && meta !== null) {
+          logInfo = {
+            ...meta,
+            level,
+            splat: splat.slice(1),
+            message,
+          };
+
+          if (meta.message) {
+            logInfo.message = `${getLogMessage(logInfo.message)} ${getLogMessage(meta.message)}`;
+          }
+          if (meta.stack) {
+            logInfo.stack = meta.stack;
+          }
+        } else {
+          logInfo = {
+            level,
+            splat,
+            message,
+          };
+        }
+      }
+
+      // Check if we should log this message
+      const minLevel = globalLogLevel ?? options.logLevel;
+      if (minLevel && !isAboveLevel(logInfo.level, minLevel)) {
+        return logger;
+      }
+
+      // Add timestamp and root metadata.
+      // Ensure there is a message property.
+      logInfo = {
+        ...globalMetadata,
+        ...rootMetadata,
+        timestamp: new Date().toISOString(),
+        ...logInfo,
+        message: logInfo.message ?? '',
+      };
+
+      for (const transport of logTransports) {
+        if (transport.logLevel) {
+          if (!isAboveLevel(logInfo.level, transport.logLevel)) {
+            continue;
+          }
+        }
+        transport.log({
+          ...filterReporterMetadata(logInfo, transport),
+          // These would break the transport if excluded.
+          level: logInfo.level,
+          message: logInfo.message,
+          splat: logInfo.splat,
+        });
+      }
+      return logger;
+    },
+    child(metadata: Metadata): ILogger {
+      return createLogger({ ...rootMetadata, metadata });
+    },
+    startTimer(): Profiler {
+      const start = new Date();
+
+      return {
+        logger: this,
+        done: ({ message, level, metadata } = {}) => {
+          const duration = new Date().getTime() - start.getTime();
+          logger.log(level ?? LogLevel.Info, message ?? 'Timer Completed', { duration, ...(metadata ?? {}) });
+          return true;
+        },
+      };
+    },
+    // Forward the log levels into the log function, essentially shortcuts.
+    debug: (...args) => logger.log(LogLevel.Debug, ...args),
+    info: (...args) => logger.log(LogLevel.Info, ...args),
+    warn: (...args) => logger.log(LogLevel.Warn, ...args),
+    error: (...args) => logger.log(LogLevel.Error, ...args),
+  };
+
+  return logger;
+}
+
+export const logger = createLogger();

package/src/logger/utils.ts

@@ -0,0 +1,28 @@
+import { LogLevel } from '../types';
+
+/**
+ * Checks if a log level is above the global log level.
+ * @param level The log level to check
+ * @param checkLevel THe log level to check against
+ * @returns Is above the checkLevel?
+ */
+export function isAboveLevel(level: LogLevel, checkLevel: LogLevel): boolean {
+  const levels = [LogLevel.Debug, LogLevel.Info, LogLevel.Warn, LogLevel.Error];
+  return levels.indexOf(level) >= levels.indexOf(checkLevel);
+}
+
+/**
+ * Ensures a message output is a string.
+ * @param message The message to assert is/convert to a string
+ * @returns The message as a string
+ */
+export function getLogMessage(message: any): string {
+  if (typeof message === 'string') {
+    return message;
+  }
+  if (typeof message === 'object' && message !== null) {
+    const data = { ...message };
+    return JSON.stringify(data);
+  }
+  return String(message);
+}