@crimson-education/browser-logger 2.0.2-cognito.2 → 3.0.0

package/src/reporters/gtmReporter.ts

@@ -1,6 +1,14 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { IReporter, ReporterBreadcrumb, ReporterEvent } from '.';
-import { Metadata, ReportUser } from '../types';
+import {
+  IReporter,
+  ReporterBreadcrumb,
+  ReporterEvent,
+  Metadata,
+  ReportUser,
+  ServiceInfo,
+  ReporterConfigBase,
+} from '../types';
+
+export type GTMReporterConfig = ReporterConfigBase;
 
 declare global {
   interface Window {
@@ -8,10 +16,27 @@ declare global {
   }
 }
 
-export function gtmReporter(): IReporter {
+export function gtmReporter(info: ServiceInfo, config: GTMReporterConfig): IReporter {
+  let loadedDataLayer = !!window.dataLayer;
+  const baseMetadata = {
+    service: info.service,
+    domain: window.location.host,
+    environment: info.environment,
+    version: info.version,
+  };
+
   const reporter: IReporter = {
+    ...config,
     addMetadata: function (metadata: Metadata): void {
-      window.dataLayer?.push(metadata);
+      if (window.dataLayer) {
+        // Lazy load base metadata, e.g. if GTM isn't ready yet.
+        if (!loadedDataLayer) {
+          window.dataLayer.push(baseMetadata);
+          loadedDataLayer = true;
+        }
+
+        window.dataLayer.push(metadata);
+      }
     },
     trackEvent: function (event: ReporterEvent): void {
       reporter.addMetadata({
@@ -39,9 +64,11 @@ export function gtmReporter(): IReporter {
     setPageName: function (pageName: string): void {
       reporter.addMetadata({ pageName });
     },
-    reportError: function (): void {},
-    recordSession: function (): void {},
-    recordSessionStop: function (): void {},
   };
+
+  if (loadedDataLayer) {
+    reporter.addMetadata(baseMetadata);
+  }
+
   return reporter;
 }

package/src/reporters/index.ts

@@ -1,32 +1,216 @@
-import { LogLevel } from '..';
-import { Metadata, Metrics, ReportError, ReportUser } from '../types';
+import { isAboveLevel } from '../logger/utils';
+import {
+  IReporter,
+  LogLevel,
+  Metadata,
+  ReporterBreadcrumb,
+  ReporterEvent,
+  ReporterFilters,
+  ReportError,
+  ReporterType,
+  ReportUser,
+  TrackedReporterEvent,
+} from '../types';
+import { filterReporterMetadata } from '../utils';
 
-export interface ReporterEvent {
-  level?: LogLevel;
-  message: string;
-  metadata?: Metadata | undefined;
-  tags?: Metadata | undefined;
-  metrics?: Metrics | undefined;
+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);
+  }
 }
 
-export interface TrackedReporterEvent extends ReporterEvent {
-  occurred: Date;
+/**
+ * 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));
+  }
 }
 
-export interface ReporterBreadcrumb {
-  message: string;
-  category?: string | undefined;
-  metadata?: Metadata | undefined;
+/**
+ * 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?.();
+  }
 }
 
-export interface IReporter {
-  trackEvent(event: ReporterEvent): void;
-  addBreadcrumb(breadcrumb: ReporterBreadcrumb): void;
-  addMetadata(metadata: Metadata): void;
-  setUser(user: ReportUser | null): void;
-  setRouteName(routeName: string): void;
-  setPageName(pageName: string): void;
-  reportError(error: ReportError, metadata?: Metadata): void;
-  recordSession(): void;
-  recordSessionStop(): void;
+/**
+ * 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;
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './logger';
+export * from './reporter';

package/src/types/logger.ts

@@ -0,0 +1,85 @@
+export type Metadata = Record<string, any>;
+
+/**
+ * Options to Customize the Logger
+ */
+export type LoggerOptions = {
+  /**
+   * The min log level for events to be sent to the logger.
+   */
+  logLevel?: LogLevel;
+
+  /**
+   * Metadata to add to all logs.
+   */
+  metadata?: Metadata;
+};
+
+export enum LogLevel {
+  Debug = 'debug',
+  Info = 'info',
+  Warn = 'warn',
+  Error = 'error',
+}
+
+export interface LogLevelMethod {
+  (message: string, metadata?: Metadata): ILogger;
+  (message: string, ...meta: any[]): ILogger;
+  (message: any): ILogger;
+}
+
+export interface LogMethod {
+  (level: LogLevel, message: string, metadata?: Metadata): ILogger;
+  (level: LogLevel, message: string, ...meta: any[]): ILogger;
+  (level: LogLevel, message: any): ILogger;
+  (message: Record<string, any>): ILogger;
+}
+
+export interface Profiler {
+  logger: ILogger;
+  done(info?: { message?: string; level?: LogLevel; metadata?: Metadata }): boolean;
+}
+
+export type StructuredLog = {
+  level: LogLevel;
+  message: any;
+  [key: string]: any;
+};
+
+export interface LogTransportConfigBase {
+  /**
+   * The min log level for logs to be sent.
+   */
+  logLevel?: LogLevel;
+
+  /**
+   * Ignore specific metadata keys from being sent.
+   * This can be a regular expression, or a string to exact match.
+   * This is useful to prevent data of no use for the logger, or if the data keys are too long.
+   */
+  ignoreMetadataPatterns?: (string | RegExp)[];
+}
+
+/**
+ * A logger interface that is used to transport logs to a destination
+ */
+export interface ILogTransport extends LogTransportConfigBase {
+  /**
+   * Inbound log event to transport.
+   */
+  log: (logInfo: StructuredLog) => void;
+}
+
+/**
+ * A Logger is a service that can receive log messages.
+ */
+export interface ILogger {
+  startTimer(): Profiler;
+  child(metadata?: Metadata, name?: string): ILogger;
+
+  log: LogMethod;
+  debug: LogLevelMethod;
+  info: LogLevelMethod;
+  warn: LogLevelMethod;
+  error: LogLevelMethod;
+}

package/src/types/reporter.ts

@@ -0,0 +1,167 @@
+import { AmplifyReporterConfig } from '../reporters/amplifyReporter';
+import { DatadogReporterConfig } from '../reporters/datadogReporter';
+import { GTMReporterConfig } from '../reporters/gtmReporter';
+import { LogReporterConfig } from '../reporters/logReporter';
+import { LogLevel, Metadata } from './logger';
+
+export type ReporterConfigurations = {
+  /**
+   * Log reporter configuration.
+   * If not set, it will default to everything enabled.
+   */
+  log?: boolean | LogReporterConfig;
+
+  /**
+   * Datadog reporter configuration.
+   * If not set, the datadog reporter will not be used.
+   */
+  datadog?: DatadogReporterConfig;
+
+  /**
+   * Amplify/Pinpoint reporter configuration.
+   * If not set, the amplify reporter will not be used.
+   */
+  amplify?: AmplifyReporterConfig;
+
+  /**
+   *  Google Tag Manager reporter configuration.
+   * If not set, the gtm reporter will not be used.
+   */
+  gtm?: true | GTMReporterConfig;
+};
+
+export type ReporterType = keyof ReporterConfigurations;
+
+export type Metrics = Record<string, number>;
+
+export type ServiceInfo = {
+  /** The Application's name. */
+  service: string;
+  /** The Application's Environment */
+  environment: string;
+  /** The Application's Version. */
+  version: string;
+  /**
+   * Default metadata to add to Reporter events.
+   */
+  defaultMetadata?: Metadata;
+  /**
+   * The min log level for logs to be sent to the logger.
+   */
+  logLevel?: LogLevel;
+  /**
+   * The min event level for events to be sent to reporters.
+   */
+  eventLevel?: LogLevel;
+};
+
+export type ReportUser = { id: string; email?: string; username?: string; name?: string };
+
+export type ReportError = Error | string;
+
+export interface ReporterFilters {
+  /**
+   * Send only to these Reporters.
+   */
+  toReporters?: ReporterType[];
+  /**
+   * Don't send to these Reporters.
+   */
+  excludeReporters?: ReporterType[];
+}
+
+export interface ReporterEvent extends ReporterFilters {
+  /**
+   * The Severity of this event.
+   */
+  level?: LogLevel;
+  /**
+   * The event message/name.
+   */
+  message: string;
+  /**
+   * Event metadata.
+   */
+  metadata?: Metadata | undefined;
+  /**
+   * Event tags, if supported by the Reporter. (Otherwise, they will be added to metadata)
+   */
+  tags?: Metadata | undefined;
+  /**
+   * Event metrics, if supported by the Reporter. (Otherwise, they will be added to metadata)
+   * Metrics are numbers, and are used for aggregations.
+   */
+  metrics?: Metrics | undefined;
+}
+
+export interface TrackedReporterEvent extends ReporterEvent {
+  /**
+   * The time this event was created.
+   */
+  occurred: Date;
+}
+
+export interface ReporterBreadcrumb extends ReporterFilters {
+  /**
+   * The breadcrumb event message/name.
+   */
+  message: string;
+  /**
+   * The category of this breadcrumb (Useful for filtering out in specific reporters).
+   */
+  category?: string | undefined;
+  /**
+   * Breadcrumb metadata.
+   */
+  metadata?: Metadata | undefined;
+}
+
+export interface ReporterConfigBase {
+  /**
+   * Enable/Disable reporter endpoints from being called.
+   */
+  endpoints?: {
+    trackEvent?: boolean;
+    addMetadata?: boolean;
+    addBreadcrumb?: boolean;
+    setUser?: boolean;
+    setRouteName?: boolean;
+    setPageName?: boolean;
+    reportError?: boolean;
+    recordSession?: boolean;
+    recordSessionStop?: boolean;
+  };
+
+  /**
+   * The min event level for events to be sent to the reporter.
+   */
+  eventLevel?: LogLevel;
+
+  /**
+   * Categories of breadcrumbs to ignore sending to the reporter.
+   * This is useful to prevent data of no use for that reporter.
+   */
+  ignoreBreadcrumbCategories?: string[];
+
+  /**
+   * Ignore specific metadata keys from being sent to the reporter.
+   * This can be a regular expression, or a string to exact match.
+   * This is useful to prevent data of no use for the reporter, or if the data keys are too long.
+   */
+  ignoreMetadataPatterns?: (string | RegExp)[];
+}
+
+/**
+ * A Reporter is a service that can receive Analytics data.
+ */
+export interface IReporter extends ReporterConfigBase {
+  trackEvent(event: ReporterEvent): void;
+  addBreadcrumb(breadcrumb: ReporterBreadcrumb): void;
+  addMetadata(metadata: Metadata): void;
+  setUser(user: ReportUser | null): void;
+  setRouteName(routeName: string): void;
+  setPageName(pageName: string): void;
+  reportError?(error: ReportError, metadata?: Metadata): void;
+  recordSession?(): void;
+  recordSessionStop?(): void;
+}

package/src/utils.test.ts

@@ -0,0 +1,32 @@
+import { filterReporterMetadata } from './utils';
+
+describe('utils', () => {
+  describe('filterReporterMetadata', () => {
+    it('should remove attributes which match the ignore patterns', () => {
+      const inputAttributeMap = {
+        includeme: '5',
+        excludeme: 'false',
+        differentProp: 'boo',
+        deep: {
+          includeme: '5',
+          excludeme: 'false',
+          deepExcludeStr: 'boo',
+          deepExcludeRegex: 'boo',
+        },
+      };
+
+      const filtered = filterReporterMetadata(inputAttributeMap, {
+        ignoreMetadataPatterns: [/excludeme/g, /Prop/g, 'deep.deepExcludeStr', /deep\.deepExcludeRegex/g],
+      });
+      expect(filtered.includeme).toBeTruthy();
+      expect(filtered.excludeme).toBeFalsy();
+      expect(filtered.differentProp).toBeFalsy();
+
+      // deep
+      expect(filtered.deep.includeme).toBeTruthy();
+      expect(filtered.deep.excludeme).toBeFalsy();
+      expect(filtered.deep.deepExcludeStr).toBeFalsy();
+      expect(filtered.deep.deepExcludeRegex).toBeFalsy();
+    });
+  });
+});