@crimson-education/browser-logger 2.0.2 → 3.0.0

package/src/reporters/amplifyReporter.ts

@@ -9,7 +9,10 @@ import {
 } from '../types';
 import { Auth } from '@aws-amplify/auth';
 import { Analytics } from '@aws-amplify/analytics';
-import { AttributeMap, filterAttributeMap } from '../utils';
+import { logger } from '../logger';
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+type AttributeMap = Record<string, string[] | string | null>;
 
 export interface AmplifyReporterConfig extends ReporterConfigBase {
   /**
@@ -133,16 +136,11 @@ export function amplifyReporter(info: ServiceInfo, config: AmplifyReporterConfig
             ...event.tags,
           },
           false,
-          config.ignoreMetadataPatterns,
         ) as Record<string, string>,
         metrics: event.metrics,
       });
     },
     addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
-      if (breadcrumb.category && config.ignoreBreadcrumbCategories?.includes(breadcrumb.category)) {
-        return;
-      }
-
       reporter.trackEvent({
         message: breadcrumb.message,
         metadata: {
@@ -152,7 +150,7 @@ export function amplifyReporter(info: ServiceInfo, config: AmplifyReporterConfig
       });
     },
     addMetadata: function (metadata: Metadata): void {
-      Object.assign(allMetadata, asAttributeMap(metadata, true, config.ignoreMetadataPatterns));
+      Object.assign(allMetadata, asAttributeMap(metadata, true));
       Analytics.updateEndpoint({
         attributes: allMetadata,
       }).catch(() => {
@@ -188,16 +186,10 @@ export function amplifyReporter(info: ServiceInfo, config: AmplifyReporterConfig
 /**
  * Pinpoint has strict attribute name and value length limits
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function asAttributeMap(
-  values: Record<string, unknown>,
-  groupValues = true,
-  ignorePatterns: (string | RegExp)[] = [],
-): AttributeMap {
+export function asAttributeMap(values: Record<string, unknown>, groupValues = true): AttributeMap {
   const attributeMap = buildAttributeMap(values, undefined, groupValues);
-  const filteredAttributeMap = filterAttributeMap(attributeMap, ignorePatterns);
 
-  const checkedEntries = Object.entries(filteredAttributeMap).map(([key, value]) => {
+  const checkedEntries = Object.entries(attributeMap).map(([key, value]) => {
     const truncatedKey = key.length > 50 ? `___${key.slice(-47)}` : key;
     const truncatedValue = Array.isArray(value)
       ? value?.map((val) => val.slice(0, 100)) ?? null
@@ -206,6 +198,14 @@ export function asAttributeMap(
     return [truncatedKey, truncatedValue];
   });
 
+  // Pinpoint only accepts 40 attributes
+  if (checkedEntries.length > 40) {
+    logger.error(`Amplify only allows 40 attributes per event, truncating to 40 attributes`, {
+      attributes: checkedEntries,
+    });
+    checkedEntries.length = 40;
+  }
+
   return Object.fromEntries(checkedEntries);
 }
 
@@ -215,7 +215,6 @@ export function asAttributeMap(
  * all of its values are of type `string[]` to appease Pinpoint.
  */
 export function buildAttributeMap(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   values: Record<string, any>,
   parentKey: string | undefined = undefined,
   groupValues = true,

package/src/reporters/datadogReporter.ts

@@ -1,19 +1,17 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import {
   IReporter,
   ReporterBreadcrumb,
   ReporterEvent,
   Metadata,
-  Profiler,
   ReportError,
   ReportUser,
   ServiceInfo,
   ReporterConfigBase,
 } from '../types';
-import { datadogLogs, HandlerType, StatusType } from '@datadog/browser-logs';
+import { datadogLogs, HandlerType } from '@datadog/browser-logs';
 import { datadogRum, DefaultPrivacyLevel } from '@datadog/browser-rum';
-import { ILogger, LogLevel } from '..';
-import { filterAttributeMap } from '../utils';
+import { logTransports } from '../logger';
+import { DatadogLogTransportConfig, datadogTransport } from '../logger/datadogTransport';
 
 export interface DatadogReporterConfig extends ReporterConfigBase {
   /** The RUM application ID. */
@@ -75,6 +73,12 @@ export interface DatadogReporterConfig extends ReporterConfigBase {
    */
   actionNameAttribute?: string;
 
+  /**
+   * Toggles/configures the Datadog Log Transport.
+   * Defaults to true.
+   */
+  logTransport?: boolean | DatadogLogTransportConfig;
+
   /**
    * By enabling Session Replay, you can automatically mask sensitive elements from being recorded through the RUM Browser SDK.
    *
@@ -87,42 +91,39 @@ export interface DatadogReporterConfig extends ReporterConfigBase {
   allowedTracingOrigins?: (string | RegExp)[];
 }
 
-function getDatadogStatusType(level: LogLevel): StatusType {
-  switch (level) {
-    case LogLevel.Error:
-      return StatusType.error;
-
-    case LogLevel.Warn:
-      return StatusType.warn;
-
-    case LogLevel.Info:
-      return StatusType.info;
-
-    case LogLevel.Debug:
-    default:
-      return StatusType.debug;
-  }
-}
-
 export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig): IReporter {
   const isLocalhost = window.location.hostname === 'localhost';
 
-  datadogLogs.init({
-    site: config.site,
-    proxyUrl: config.proxyUrl,
-    clientToken: config.clientToken,
-    service: info.service,
-    env: info.environment,
-    version: config.version ?? info.version,
-
-    sampleRate: config.sampleRate ?? 100,
-
-    useSecureSessionCookie: config.useSecureSessionCookie ?? !isLocalhost,
-    useCrossSiteSessionCookie: config.useCrossSiteSessionCookie ?? false,
-    trackSessionAcrossSubdomains: config.trackSessionAcrossSubdomains,
+  // Don't forward error logs by default, do enable the log transport by default
+  // forwardErrorsToLogs incorrectly is called forwardConsoleLogs, this is for backwards compatibility
+  const forwardErrorsToLogs = config.forwardConsoleLogs ?? false;
+  const enableLogTransport = config.logTransport !== false;
+
+  // Only init datadog logs if something is using it.
+  if (forwardErrorsToLogs !== true && enableLogTransport !== true) {
+    datadogLogs.init({
+      site: config.site,
+      proxyUrl: config.proxyUrl,
+      clientToken: config.clientToken,
+      service: info.service,
+      env: info.environment,
+      version: config.version ?? info.version,
+
+      sampleRate: config.sampleRate ?? 100,
+
+      useSecureSessionCookie: config.useSecureSessionCookie ?? !isLocalhost,
+      useCrossSiteSessionCookie: config.useCrossSiteSessionCookie ?? false,
+      trackSessionAcrossSubdomains: config.trackSessionAcrossSubdomains,
+
+      forwardErrorsToLogs,
+    });
+    datadogLogs.logger.setHandler(HandlerType.http);
+  }
 
-    forwardErrorsToLogs: config.forwardConsoleLogs ?? false,
-  });
+  // Add the datadog log transport
+  if (enableLogTransport) {
+    logTransports.push(datadogTransport(typeof config.logTransport === 'boolean' ? {} : config.logTransport));
+  }
 
   datadogRum.init({
     site: config.site,
@@ -149,39 +150,33 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
     allowedTracingOrigins: config.allowedTracingOrigins,
   });
 
-  const ignoreMetadataPatterns = config.ignoreMetadataPatterns ?? [];
-
   const reporter: IReporter = {
     trackEvent: function (event: ReporterEvent): void {
-      const context = {
+      datadogRum.addAction(event.message, {
         level: event.level,
-        ...filterAttributeMap(event.metadata ?? {}, ignoreMetadataPatterns),
+        ...event.metadata,
         ...event.tags,
         ...event.metrics,
-      };
-      datadogRum.addAction(event.message, context);
-      datadogLogs.logger?.log(event.message, context, getDatadogStatusType(event.level ?? LogLevel.Info));
+      });
     },
     addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
-      if (breadcrumb.category && config.ignoreBreadcrumbCategories?.includes(breadcrumb.category)) {
-        return;
-      }
-
-      const context = {
+      datadogRum.addAction(breadcrumb.message, {
         ...breadcrumb.metadata,
         category: breadcrumb.category,
-      };
-      datadogRum.addAction(breadcrumb.message, context);
+      });
     },
     addMetadata: function (metadata: Metadata): void {
-      metadata = filterAttributeMap(metadata, ignoreMetadataPatterns);
-
       for (const [key, value] of Object.entries(metadata)) {
         if (value !== null) {
           datadogRum.addRumGlobalContext(key, value);
+
+          // Note, this will add duplicate context data in logs.
+          // But this is valuable for logs ingested outside of the browser logger.
           datadogLogs.addLoggerGlobalContext(key, value);
         } else {
           datadogRum.removeRumGlobalContext(key);
+
+          // But this is valuable for logs ingested outside of the browser logger.
           datadogLogs.removeLoggerGlobalContext(key);
         }
       }
@@ -193,16 +188,8 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
           email: user.email,
           name: user.name ?? user.email,
         });
-
-        datadogLogs.addLoggerGlobalContext('user_id', user.id);
-        datadogLogs.addLoggerGlobalContext('user_email', user.email);
-        datadogLogs.addLoggerGlobalContext('user_username', user.username);
       } else {
         datadogRum.removeUser();
-
-        datadogLogs.removeLoggerGlobalContext('user_id');
-        datadogLogs.removeLoggerGlobalContext('user_email');
-        datadogLogs.removeLoggerGlobalContext('user_username');
       }
     },
     setRouteName: function (routeName: string): void {
@@ -216,9 +203,6 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
       }
     },
     reportError: function (error: ReportError, metadata?: Metadata): void {
-      metadata = filterAttributeMap(metadata ?? {}, ignoreMetadataPatterns);
-
-      // Note, datadog should pick up the console error above
       datadogRum.addError(error, metadata);
     },
     recordSession: function (): void {
@@ -230,55 +214,3 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
   };
   return reporter;
 }
-
-export function datadogLogger(name?: string, options?: { metadata?: Metadata }): ILogger {
-  const loggerName = name ?? 'root';
-  const ddLogger = datadogLogs.createLogger(loggerName, {
-    context: options?.metadata,
-  });
-  // Send to datadog and console.
-  ddLogger.setHandler([HandlerType.http, HandlerType.console]);
-
-  const logger: ILogger = {
-    startTimer: function (): Profiler {
-      const start = new Date();
-
-      return {
-        logger: this,
-        done: ({ message, level } = {}) => {
-          const duration = new Date().getTime() - start.getTime();
-          logger[level ?? LogLevel.Info](message ?? 'Timer Completed', { duration });
-          return true;
-        },
-      };
-    },
-    child: function (metadata?: Metadata, name?: string): ILogger {
-      return datadogLogger(name ?? `${loggerName}.child`, metadata);
-    },
-    log: (level: LogLevel, message: string, metadata?: any) => {
-      switch (level) {
-        case LogLevel.Debug:
-          ddLogger.debug(message, metadata);
-          break;
-
-        case LogLevel.Info:
-          ddLogger.info(message, metadata);
-          break;
-
-        case LogLevel.Warn:
-          ddLogger.warn(message, metadata);
-          break;
-
-        case LogLevel.Error:
-          ddLogger.error(message, metadata);
-          break;
-      }
-      return logger;
-    },
-    debug: (message: string, metadata?: any) => logger.log(LogLevel.Debug, message, metadata),
-    info: (message: string, metadata?: any) => logger.log(LogLevel.Info, message, metadata),
-    warn: (message: string, metadata?: any) => logger.log(LogLevel.Warn, message, metadata),
-    error: (message: string, metadata?: any) => logger.log(LogLevel.Error, message, metadata),
-  };
-  return logger;
-}

package/src/reporters/gtmReporter.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import {
   IReporter,
   ReporterBreadcrumb,
@@ -8,7 +7,6 @@ import {
   ServiceInfo,
   ReporterConfigBase,
 } from '../types';
-import { filterAttributeMap } from '../utils';
 
 export type GTMReporterConfig = ReporterConfigBase;
 
@@ -28,6 +26,7 @@ export function gtmReporter(info: ServiceInfo, config: GTMReporterConfig): IRepo
   };
 
   const reporter: IReporter = {
+    ...config,
     addMetadata: function (metadata: Metadata): void {
       if (window.dataLayer) {
         // Lazy load base metadata, e.g. if GTM isn't ready yet.
@@ -36,7 +35,7 @@ export function gtmReporter(info: ServiceInfo, config: GTMReporterConfig): IRepo
           loadedDataLayer = true;
         }
 
-        window.dataLayer.push(filterAttributeMap(metadata, config.ignoreMetadataPatterns ?? []));
+        window.dataLayer.push(metadata);
       }
     },
     trackEvent: function (event: ReporterEvent): void {
@@ -49,10 +48,6 @@ export function gtmReporter(info: ServiceInfo, config: GTMReporterConfig): IRepo
       });
     },
     addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
-      if (config.ignoreBreadcrumbCategories?.includes(breadcrumb.category ?? '')) {
-        return;
-      }
-
       reporter.addMetadata({
         ...breadcrumb.metadata,
         event: breadcrumb.message,

package/src/reporters/index.ts

@@ -1,3 +1,216 @@
-export * from './amplifyReporter';
-export * from './datadogReporter';
-export * from './gtmReporter';
+import { isAboveLevel } from '../logger/utils';
+import {
+  IReporter,
+  LogLevel,
+  Metadata,
+  ReporterBreadcrumb,
+  ReporterEvent,
+  ReporterFilters,
+  ReportError,
+  ReporterType,
+  ReportUser,
+  TrackedReporterEvent,
+} from '../types';
+import { filterReporterMetadata } from '../utils';
+
+export const reporters: Partial<Record<ReporterType, IReporter>> = {};
+
+export let globalEventLevel: LogLevel | undefined;
+/**
+ * Sets the global event level.
+ */
+export function setEventLevel(level: LogLevel | null): void {
+  globalEventLevel = level ?? undefined;
+}
+
+/**
+ * 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 {
+  if (globalEventLevel && event.level && !isAboveLevel(event.level, globalEventLevel)) {
+    return;
+  }
+
+  for (const reporter of getReporters(event)) {
+    if (reporter.endpoints?.trackEvent === false) {
+      continue;
+    } else if (reporter.eventLevel && event.level && !isAboveLevel(event.level, reporter.eventLevel)) {
+      return;
+    }
+
+    const reporterEvent = { ...event };
+    reporterEvent.metadata = filterReporterMetadata(event.metadata, reporter);
+    reporterEvent.metrics = filterReporterMetadata(event.metrics, reporter);
+    reporterEvent.tags = filterReporterMetadata(event.tags, reporter);
+    reporter.trackEvent(reporterEvent);
+  }
+}
+
+/**
+ * Tracks an Analytics event, recording the time since the last event, if available.
+ */
+export function trackEventSinceLastAction(event: ReporterEvent): void {
+  if (globalEventLevel && event.level && !isAboveLevel(event.level, globalEventLevel)) {
+    return;
+  }
+
+  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)) {
+    if (reporter.endpoints?.addBreadcrumb === false) {
+      continue;
+    } else if (breadcrumb.category && reporter.ignoreBreadcrumbCategories?.includes(breadcrumb.category)) {
+      continue;
+    }
+
+    const reporterBreadcrumb = { ...breadcrumb };
+    reporterBreadcrumb.metadata = filterReporterMetadata(breadcrumb.metadata, reporter);
+    reporter.addBreadcrumb(reporterBreadcrumb);
+  }
+}
+
+/**
+ * Adds global metadata to all events and logs.
+ * @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)) {
+    if (reporter.endpoints?.addMetadata === false) {
+      continue;
+    }
+    reporter.addMetadata(filterReporterMetadata(metadata, reporter));
+  }
+}
+
+/**
+ * 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)) {
+    if (reporter.endpoints?.setUser === false) {
+      continue;
+    }
+    reporter.setUser(user);
+  }
+}
+
+/**
+ * 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)) {
+    if (reporter.endpoints?.setRouteName === false) {
+      continue;
+    }
+    reporter.setRouteName(routeName);
+  }
+}
+
+/**
+ * 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)) {
+    if (reporter.endpoints?.setPageName === false) {
+      continue;
+    }
+    reporter.setPageName(pageName);
+  }
+}
+
+/**
+ * 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)) {
+    if (reporter.endpoints?.reportError === false) {
+      continue;
+    }
+    reporter.reportError?.(error, filterReporterMetadata(metadata, reporter));
+  }
+}
+
+/**
+ * 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)) {
+    if (reporter.endpoints?.recordSession === false) {
+      continue;
+    }
+    reporter.recordSession?.();
+  }
+}
+
+/**
+ * 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)) {
+    if (reporter.endpoints?.recordSessionStop === false) {
+      continue;
+    }
+    reporter.recordSessionStop?.();
+  }
+}

package/src/reporters/logReporter.ts

@@ -0,0 +1,86 @@
+import { logger, globalMetadata as globalLogMetadata } from '../logger';
+import { IReporter, LogLevel, ReporterConfigBase, ServiceInfo } from '../types';
+
+export interface LogReporterConfig extends ReporterConfigBase {
+  /**
+   * The fallback log level to apply to all trackEvent calls (if the event's level is not set).
+   * Defaults to info.
+   */
+  trackEventDefaultLevel?: LogLevel;
+  /**
+   * The log level to apply to all addBreadcrumb calls.
+   * Defaults to info.
+   */
+  addBreadcrumbLevel?: LogLevel;
+  /**
+   * The log level to apply to all setRouteName calls.
+   * Defaults to debug.
+   */
+  setRouteNameLevel?: LogLevel;
+  /**
+   * The log level to apply to all setPageName calls.
+   * Defaults to debug.
+   */
+  setPageNameLevel?: LogLevel;
+  /**
+   * The log level to apply to all recordSession calls.
+   * Defaults to debug.
+   */
+  recordSessionLevel?: LogLevel;
+  /**
+   * The log level to apply to all recordSessionStop calls.
+   * Defaults to debug.
+   */
+  recordSessionStopLevel?: LogLevel;
+}
+
+export function logReporter(info: ServiceInfo, config: LogReporterConfig) {
+  const reporter: IReporter = {
+    ...config,
+    trackEvent(event) {
+      // config.trackEventLevel and config.level overrides event.level here, as it is an override, while config.trackEventDefaultLevel is a fallback.
+      const level = event.level ?? config.trackEventDefaultLevel ?? LogLevel.Info;
+      logger.log(level, event.message, {
+        ...(event.metadata ?? {}),
+        ...(event.metrics ?? {}),
+        ...(event.tags ?? {}),
+      });
+    },
+    addBreadcrumb(breadcrumb) {
+      const level = config.addBreadcrumbLevel ?? LogLevel.Info;
+      logger.log(level, breadcrumb.message, {
+        ...(breadcrumb.metadata ?? {}),
+        category: breadcrumb.category,
+      });
+    },
+    addMetadata(metadata) {
+      Object.assign(globalLogMetadata, metadata);
+    },
+    setUser(user) {
+      Object.assign(globalLogMetadata, { user });
+    },
+    setRouteName(routeName) {
+      Object.assign(globalLogMetadata, { routeName });
+      const level = config.setRouteNameLevel ?? LogLevel.Debug;
+      logger.log(level, `Route changed to ${routeName}`);
+    },
+    setPageName(pageName) {
+      Object.assign(globalLogMetadata, { pageName });
+      const level = config.setPageNameLevel ?? LogLevel.Debug;
+      logger.log(level, `Page changed to ${pageName}`);
+    },
+    reportError(error, metadata) {
+      logger.error(typeof error === 'string' ? error : error.message, { ...metadata, error });
+    },
+    recordSession() {
+      const level = config.recordSessionLevel ?? LogLevel.Debug;
+      logger.log(level, 'Recording Session');
+    },
+    recordSessionStop() {
+      const level = config.recordSessionStopLevel ?? LogLevel.Debug;
+      logger.log(level, 'Recording Session Stopping');
+    },
+  };
+
+  return reporter;
+}