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

package/src/reporters/datadogReporter.ts

@@ -1,28 +1,91 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { IReporter, ReporterBreadcrumb, ReporterEvent } from '.';
-import { Metadata, Profiler, ReportError, ReportUser, ServiceInfo } from '../types';
+import {
+  IReporter,
+  ReporterBreadcrumb,
+  ReporterEvent,
+  Metadata,
+  Profiler,
+  ReportError,
+  ReportUser,
+  ServiceInfo,
+  ReporterConfigBase,
+} from '../types';
 import { datadogLogs, HandlerType, StatusType } from '@datadog/browser-logs';
 import { datadogRum, DefaultPrivacyLevel } from '@datadog/browser-rum';
 import { ILogger, LogLevel } from '..';
+import { filterAttributeMap } from '../utils';
 
-export type DatadogReporterConfig = {
+export interface DatadogReporterConfig extends ReporterConfigBase {
+  /** The RUM application ID. */
   applicationId: string;
+  /** A Datadog client token (Generated in the RUM Page) */
   clientToken: string;
+  /** The Datadog site parameter of your organization. */
+  site: string;
+  /** The Application's version (Overrides the browser logger version) */
   version?: string;
-  site?: string;
+  /** Optional proxy URL */
   proxyUrl?: string;
-  forwardConsoleLogs?: boolean;
-  trackInteractions?: boolean;
+
+  /**
+   * Controls the percentage of overall sessions being tracked. It defaults to 100, so every session is tracked by default.
+   */
   sampleRate?: number;
+  /**
+   * Applied after the overall sample rate, and controls the percentage of sessions tracked as Browser RUM & Session Replay.
+   * It defaults to 100, so every session is tracked as Browser RUM & Session Replay by default.
+   */
   replaySampleRate?: number;
-  defaultPrivacyLevel?: DefaultPrivacyLevel;
+
+  /**
+   * Use a secure session cookie. This disables RUM events sent on insecure (non-HTTPS) connections.
+   */
   useSecureSessionCookie?: boolean;
+  /**
+   * Use a secure cross-site session cookie.
+   * This allows the RUM Browser SDK to run when the site is loaded from another one (iframe). Implies `useSecureSessionCookie`
+   */
   useCrossSiteSessionCookie?: boolean;
-  allowedTracingOrigins?: (string | RegExp)[];
+  /**
+   * Preserve the session across subdomains for the same site.
+   */
   trackSessionAcrossSubdomains?: boolean;
-  actionNameAttribute?: string;
+
+  /**
+   * Forward console.error logs, uncaught exceptions and network errors to Datadog.
+   * Defaults to false.
+   */
+  forwardConsoleLogs?: boolean;
+  /**
+   * Enables automatic collection of users actions.
+   */
+  trackInteractions?: boolean;
+  /**
+   * Enables automatic collection of user frustrations. Implies `trackInteractions`: true.
+   */
+  trackFrustrations?: boolean;
+  /**
+   * Allows you to control RUM views creation.
+   * You will need to call `Logger.setPageName()` to create a new view.
+   */
   trackViewsManually?: boolean;
-};
+  /**
+   * Specify your own attribute to be used to name actions.
+   * Defaults to `data-analytics-name` to coincide with analytics attributes used across reporters.
+   */
+  actionNameAttribute?: string;
+
+  /**
+   * By enabling Session Replay, you can automatically mask sensitive elements from being recorded through the RUM Browser SDK.
+   *
+   * See https://docs.datadoghq.com/real_user_monitoring/session_replay/privacy_options
+   */
+  defaultPrivacyLevel?: DefaultPrivacyLevel;
+  /**
+   * A list of request origins used to inject tracing headers, to be able to connect RUM and backend tracing.
+   */
+  allowedTracingOrigins?: (string | RegExp)[];
+}
 
 function getDatadogStatusType(level: LogLevel): StatusType {
   switch (level) {
@@ -52,6 +115,8 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
     env: info.environment,
     version: config.version ?? info.version,
 
+    sampleRate: config.sampleRate ?? 100,
+
     useSecureSessionCookie: config.useSecureSessionCookie ?? !isLocalhost,
     useCrossSiteSessionCookie: config.useCrossSiteSessionCookie ?? false,
     trackSessionAcrossSubdomains: config.trackSessionAcrossSubdomains,
@@ -68,26 +133,29 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
     env: info.environment,
     version: config.version ?? info.version,
 
+    sampleRate: config.sampleRate ?? 100,
+    replaySampleRate: config.replaySampleRate ?? 100,
+
     useSecureSessionCookie: config.useSecureSessionCookie ?? !isLocalhost,
     useCrossSiteSessionCookie: config.useCrossSiteSessionCookie ?? false,
     trackSessionAcrossSubdomains: config.trackSessionAcrossSubdomains,
 
-    // Set sampleRate to 100 to capture 100%
-    // of transactions for performance monitoring.
-    sampleRate: config.sampleRate ?? 100,
-    replaySampleRate: config.replaySampleRate ?? 100,
     trackInteractions: config.trackInteractions ?? false,
+    trackFrustrations: config.trackFrustrations ?? false,
+    trackViewsManually: config.trackViewsManually ?? false,
+    actionNameAttribute: config.actionNameAttribute ?? 'data-analytics-name',
+
     defaultPrivacyLevel: config.defaultPrivacyLevel ?? 'mask-user-input',
     allowedTracingOrigins: config.allowedTracingOrigins,
-    actionNameAttribute: config.actionNameAttribute ?? 'data-analytics-name',
-    trackViewsManually: config.trackViewsManually ?? false,
   });
 
+  const ignoreMetadataPatterns = config.ignoreMetadataPatterns ?? [];
+
   const reporter: IReporter = {
     trackEvent: function (event: ReporterEvent): void {
       const context = {
         level: event.level,
-        ...event.metadata,
+        ...filterAttributeMap(event.metadata ?? {}, ignoreMetadataPatterns),
         ...event.tags,
         ...event.metrics,
       };
@@ -95,6 +163,10 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
       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 = {
         ...breadcrumb.metadata,
         category: breadcrumb.category,
@@ -102,6 +174,8 @@ export function datadogReporter(info: ServiceInfo, config: DatadogReporterConfig
       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);
@@ -142,6 +216,8 @@ 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);
     },

package/src/reporters/gtmReporter.ts

@@ -1,6 +1,16 @@
 /* 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';
+import { filterAttributeMap } from '../utils';
+
+export type GTMReporterConfig = ReporterConfigBase;
 
 declare global {
   interface Window {
@@ -8,10 +18,26 @@ 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 = {
     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(filterAttributeMap(metadata, config.ignoreMetadataPatterns ?? []));
+      }
     },
     trackEvent: function (event: ReporterEvent): void {
       reporter.addMetadata({
@@ -23,6 +49,10 @@ export function gtmReporter(): IReporter {
       });
     },
     addBreadcrumb: function (breadcrumb: ReporterBreadcrumb): void {
+      if (config.ignoreBreadcrumbCategories?.includes(breadcrumb.category ?? '')) {
+        return;
+      }
+
       reporter.addMetadata({
         ...breadcrumb.metadata,
         event: breadcrumb.message,
@@ -39,9 +69,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,3 @@
-import { LogLevel } from '..';
-import { Metadata, Metrics, ReportError, ReportUser } from '../types';
-
-export interface ReporterEvent {
-  level?: LogLevel;
-  message: string;
-  metadata?: Metadata | undefined;
-  tags?: Metadata | undefined;
-  metrics?: Metrics | undefined;
-}
-
-export interface TrackedReporterEvent extends ReporterEvent {
-  occurred: Date;
-}
-
-export interface ReporterBreadcrumb {
-  message: string;
-  category?: string | undefined;
-  metadata?: Metadata | undefined;
-}
-
-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;
-}
+export * from './amplifyReporter';
+export * from './datadogReporter';
+export * from './gtmReporter';

package/src/types/index.ts

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

package/src/{types.ts → types/logger.ts}

@@ -1,19 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 export type Metadata = Record<string, any>;
 
-export type Metrics = Record<string, number>;
-
-export type ServiceInfo = {
-  service: string;
-  environment: string;
-  version: string;
-  defaultMetadata?: Metadata;
-};
-
-export type ReportUser = { id: string; email?: string; username?: string; name?: string };
-
-export type ReportError = Error | string;
-
 export enum LogLevel {
   Debug = 'debug',
   Info = 'info',
@@ -38,6 +25,9 @@ export interface Profiler {
   done(info?: { message?: string; level?: LogLevel }): boolean;
 }
 
+/**
+ * A Logger is a service that can receive log messages.
+ */
 export interface ILogger {
   startTimer(): Profiler;
   child(metadata?: Metadata, name?: string): ILogger;

package/src/types/reporter.ts

@@ -0,0 +1,107 @@
+import { ReporterType } from '..';
+import { LogLevel, Metadata } from './logger';
+
+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;
+};
+
+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 {
+  /**
+   * Categories of breadcrumbs to ignore sending to Amplify.
+   * This is useful to prevent data of no use for amplify.
+   */
+  ignoreBreadcrumbCategories?: string[];
+  /**
+   * Ignore specific metadata keys from being sent to Amplify.
+   * This can be a regular expression, or a string to exact match.
+   * This is useful to prevent data of no use for amplify, or if the data keys are too long.
+   */
+  ignoreMetadataPatterns?: (string | RegExp)[];
+}
+
+/**
+ * A Reporter is a service that can receive Analytics data.
+ */
+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;
+}

package/src/utils.test.ts

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

package/src/utils.ts

@@ -1,6 +1,8 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { ILogger, Profiler, LogMethod, LogLevelMethod, Metadata, LogLevel } from '.';
+import { ILogger, Profiler, Metadata, LogLevel } from './types';
+
+export type AttributeMap = Record<string, string[] | string | null>;
 
 export function consoleLogger(name?: string, options?: { metadata?: Metadata }): ILogger {
   const logger: ILogger = {
@@ -48,3 +50,16 @@ export function consoleLogger(name?: string, options?: { metadata?: Metadata }):
 
   return logger;
 }
+
+export function filterAttributeMap(
+  attributes: AttributeMap | Record<string, string>,
+  ignorePatterns: (string | RegExp)[],
+) {
+  const entries = Object.entries(attributes);
+
+  return Object.fromEntries(
+    entries.filter(
+      ([key]) => !ignorePatterns.some((pattern) => (typeof pattern === 'string' ? pattern === key : pattern.test(key))),
+    ),
+  );
+}

package/lib/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,oBAAY,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE3C,oBAAY,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C,oBAAY,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,QAAQ,CAAC;CAC5B,CAAC;AAEF,oBAAY,UAAU,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,oBAAY,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzC,oBAAY,QAAQ;IAClB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC;IAC3C,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC3C,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC;IAC5D,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC5D,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC;CAC9D;AAED,MAAM,WAAW,OAAO;IACtB,UAAU,IAAI,QAAQ,CAAC;IACvB,KAAK,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEnD,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,cAAc,CAAC;CACvB"}

package/lib/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAgBA,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;AACjB,CAAC,EALW,QAAQ,GAAR,gBAAQ,KAAR,gBAAQ,QAKnB"}