@crimson-education/browser-logger 2.0.2 → 3.0.1-pinpoint-middleware.0

package/README.md

@@ -1,6 +1,6 @@
 # Crimson Education Browser Logger
 
-An abstract logger and reporting utility for browser environments.
+A structured logger and analytics reporting utility for browser environments.
 
 This library contains a number of reporters that is will send analytics to.
 
@@ -34,30 +34,39 @@ Logger.init({
     application: 'test',
   },
 
-  datadog: {
-    applicationId: config.datadogApplicationId,
-    clientToken: config.datadogClientToken,
-    site: config.datadogSite,
-    proxyUrl: config.datadogTunnelProxyUrl,
-    version: config.datadogVersion,
-
-    sampleRate: config.environment === 'production' ? 50 : 0,
-    replaySampleRate: config.environment === 'production' ? 50 : 0,
-
-    forwardConsoleLogs: true,
-    trackInteractions: true,
-    trackFrustrations: true,
-    allowedTracingOrigins: ['https://my.api.domain']
-  },
-
-  amplify: {
-    region: config.awsRegion,
-    identityPoolId: config.pinpointIdentityPoolId,
-    analyticsAppId: config.pinpointAnalyticsAppId,
-
-    autoTrackEvents: true,
-    autoTrackPageViews: true,
-    autoTrackSessions: true,
+  reporters: {
+    log: true,
+
+    gtm: true,
+
+    datadog: {
+      applicationId: config.datadogApplicationId,
+      clientToken: config.datadogClientToken,
+      site: config.datadogSite,
+      proxyUrl: config.datadogTunnelProxyUrl,
+      version: config.datadogVersion,
+
+      sampleRate: config.environment === 'production' ? 50 : 0,
+      replaySampleRate: config.environment === 'production' ? 50 : 0,
+
+      forwardConsoleLogs: true,
+      logTransport: {
+        level: Logger.LogLevel.Info,
+      },
+      trackInteractions: true,
+      trackFrustrations: true,
+      allowedTracingOrigins: ['https://my.api.domain']
+    },
+
+    amplify: {
+      region: config.awsRegion,
+      identityPoolId: config.pinpointIdentityPoolId,
+      analyticsAppId: config.pinpointAnalyticsAppId,
+
+      autoTrackEvents: true,
+      autoTrackPageViews: true,
+      autoTrackSessions: true,
+    }
   }
 });
 
@@ -77,8 +86,7 @@ Logger.trackEvent({
   },
 });
 
-// Must init before you can create a logger.
-const logger = Logger.createLogger('app');
+export const logger = Logger.createLogger();
 
 // Attributed logging.
 logger.info('WOW!', {
@@ -86,7 +94,133 @@ logger.info('WOW!', {
 });
 ```
 
-### Reporters
+### Structured Logging
+
+Structured logging in this library is loosely based on Winston, and follows roughly the same interface as `@crimson-education/node-logger`.
+
+Call `Logger.createLogger()` to create a logger instance, it is recommended to re-use this as a global logger everywhere, and then call `.child()` to reuse metadata.
+
+Global metadata about the service will be added for transport usage after calling `Logger.init()`.
+
+You can add more Global Metadata at any time by calling `addMetadata()`.
+
+
+```ts
+export const logger = Logger.createLogger();
+
+const log = logger.child({
+  from: 'childLog',
+});
+
+log.info('My Log', { jobCount: jobs.length });
+
+const timer = log.startTimer();
+
+const result = await job(jobs);
+
+timer.done({ message: 'Job Completed', metadata: { id: result.id } });
+```
+
+### Reporting
+
+#### Opting out of events
+
+You can opt out of sending events to reporters on a global, or per call basis using the endpoints config.
+
+E.g. On calls
+
+```ts
+Logger.trackEvent({
+  message: 'my-event',
+  toReporters: ['log', 'datadog'],
+  excludeReporters: ['datadog']
+});
+```
+
+E.g. Globally
+
+```ts
+Logger.init({
+  reporters: {
+    log: true,
+    datadog: {
+      ...
+      endpoints: {
+        trackEvent: false,
+      }
+    }
+  }
+});
+```
+
+These will only send to the log reporter, it is recommended to use `toReporters` or `excludeReporters` separately as they overlap.
+
+#### Filtering out metadata
+
+You can filter what metadata gets sent to each reporter in the reporter config. 
+This accepts a string for exact match metadata keys, or a RegExp.
+You can use `.` to traverse metadata.
+
+```ts
+Logger.init({
+  reporters: {
+    log: {
+      ignoreMetadataPatterns: [
+        'internalError',
+        'user.email',
+        /error\.stack.*/g
+      ]
+    }
+  }
+});
+```
+
+### Filtering out Breadcrumb categories
+
+You can filter what breadcrumbs get sent to reports in the reporter config.
+
+```ts
+Logger.init({
+  reporters: {
+    log: {
+      ignoreBreadcrumbCategories: [
+        'fetch'
+      ]
+    }
+  }
+});
+
+// Not sent to the log reporter.
+Logger.addBreadcrumb({
+  ...
+  category: 'fetch',
+});
+```
+
+### Configure Reporters
+
+#### Log
+
+By default, the log reporter is enabled. This adds all reporter functions to logs. Set `reporters.log` to `false` to disable reporter logging.
+
+```ts
+import { config } from '../configuration';
+import * as Logger from '@crimson-education/browser-logger';
+
+Logger.init({
+  reporters: {
+    log: {
+      trackEventLevel: Logger.LogInfo.Debug,
+      endpoints: {
+        recordSession: false,
+        recordSessionStop: false,
+      }
+    }
+  }
+});
+```
+
+Check out the [`DatadogReporterConfig`](https://github.com/crimson-education/browser-logger/blob/main/src/reporters/datadogReporter.ts) for all of the configuration you can apply to Datadog reporting.
 
 #### Datadog
 
@@ -97,26 +231,32 @@ import { config } from '../configuration';
 import * as Logger from '@crimson-education/browser-logger';
 
 Logger.init({
-  ...
-  datadog: {
-    applicationId: config.datadogApplicationId,
-    clientToken: config.datadogClientToken,
-    site: config.datadogSite,
-    proxyUrl: config.datadogTunnelProxyUrl,
-    version: config.datadogVersion,
-
-    sampleRate: config.environment === 'production' ? 50 : 0,
-    replaySampleRate: config.environment === 'production' ? 50 : 0,
-
-    forwardConsoleLogs: true,
-    trackInteractions: true,
-    allowedTracingOrigins: ['https://my.api.domain']
+  reporters: {
+    datadog: {
+      applicationId: config.datadogApplicationId,
+      clientToken: config.datadogClientToken,
+      site: config.datadogSite,
+      proxyUrl: config.datadogTunnelProxyUrl,
+      version: config.datadogVersion,
+
+      sampleRate: config.environment === 'production' ? 50 : 0,
+      replaySampleRate: config.environment === 'production' ? 50 : 0,
+
+      forwardConsoleLogs: true,
+      logTransport: {
+        level: Logger.LogLevel.Info,
+      },
+      trackInteractions: true,
+      allowedTracingOrigins: ['https://my.api.domain']
+    }
   }
 });
 ```
 
 Check out the [`DatadogReporterConfig`](https://github.com/crimson-education/browser-logger/blob/main/src/reporters/datadogReporter.ts) for all of the configuration you can apply to Datadog reporting.
 
+This automatically adds a Datadog Log Transport that transmits Log data to Datadog, this can be customized in `DatadogReporterConfig` with `logTransport`, or disabled by setting `logTransport` to `false`.
+
 #### Amplify/Pinpoint
 
 To configure Amplify, this requires at least `region`, `identityPoolId` and `analyticsAppId`.
@@ -131,15 +271,16 @@ import { config } from '../configuration';
 import * as Logger from '@crimson-education/browser-logger';
 
 Logger.init({
-  ...
-  amplify: {
-    region: config.amplifyAwsRegion,
-    analyticsAppId: config.pinpointAnalyticsAppId,
-    identityPoolId: config.amplifyIdentityPoolId,
-
-    autoTrackEvents: true,
-    autoTrackPageViews: true,
-    autoTrackSessions: true,
+  reporters: {
+    amplify: {
+      region: config.amplifyAwsRegion,
+      analyticsAppId: config.pinpointAnalyticsAppId,
+      identityPoolId: config.amplifyIdentityPoolId,
+
+      autoTrackEvents: true,
+      autoTrackPageViews: true,
+      autoTrackSessions: true,
+    }
   }
 });
 ```
@@ -158,15 +299,16 @@ Auth.configure({
 });
 
 Logger.init({
-  ...
-  amplify: {
-    region: config.amplifyAwsRegion,
-    analyticsAppId: config.pinpointAnalyticsAppId,
-    identityPoolId: false,
-
-    autoTrackEvents: true,
-    autoTrackPageViews: true,
-    autoTrackSessions: true,
+  reporters: {
+    amplify: {
+      region: config.amplifyAwsRegion,
+      analyticsAppId: config.pinpointAnalyticsAppId,
+      identityPoolId: false,
+
+      autoTrackEvents: true,
+      autoTrackPageViews: true,
+      autoTrackSessions: true,
+    }
   }
 });
 ```
@@ -184,16 +326,18 @@ import * as Logger from '@crimson-education/browser-logger';
 
 // No configuration
 Logger.init({
-  ...
-  gtm: true,
+  reporters: {
+    gtm: true,
+  }
 });
 
 // With configuration
 Logger.init({
-  ...
-  gtm: {
-    ignoreBreadcrumbCategories: ['fetch']
-  },
+  reporters: {
+    gtm: {
+      ignoreBreadcrumbCategories: ['fetch']
+    }
+  }
 });
 ```
 
@@ -201,7 +345,8 @@ Check out the [`GTMReporterConfig`](https://github.com/crimson-education/browser
 
 ### Functions
 
-See the [src/index.ts](./src/index.ts) file for all exported functions of the Logger.
+See the [src/logger/index.ts](./src/logger/index.ts) file for all exported functions of the Logger.
+See the [src/reporter/index.ts](./src/reporter/index.ts) file for all exported functions of the Reporter.
 
 ### Improve Session Tracking with Component names
 

package/lib/index.d.ts

@@ -1,83 +1,13 @@
-import { ILogger, Metadata, ReporterBreadcrumb, ReporterEvent, ReporterFilters, ReportError, ReportUser, ServiceInfo, TrackedReporterEvent } from './types';
-import { DatadogReporterConfig, GTMReporterConfig, AmplifyReporterConfig } from './reporters';
-export * from './types';
-export declare let logger: ILogger | null;
-export declare type ReporterType = 'datadog' | 'gtm' | 'amplify';
-export declare type ReporterConfig = ServiceInfo & {
-    datadog?: DatadogReporterConfig;
-    amplify?: AmplifyReporterConfig;
-    gtm?: true | GTMReporterConfig;
-};
-/**
- * Initializes the logger and reporters.
- * @param config Reporter config options.
- */
-export declare function init(config: ReporterConfig): void;
-/**
- * Tracks an Analytics event.
- */
-export declare function trackEvent(event: ReporterEvent): void;
-/**
- * Tracks an Analytics event, recording the time since the last event, if available.
- */
-export declare function trackEventSinceLastAction(event: ReporterEvent): void;
-/**
- * Gets the last tracked event, if available.
- */
-export declare function getLastTrackedEvent(): TrackedReporterEvent | null;
-/**
- * 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 declare function addBreadcrumb(breadcrumb: ReporterBreadcrumb): void;
-/**
- * Adds global metadata to all events.
- * @param metadata Metadata to add.
- * @param filters Optional filters to specify which reporters to add metadata to.
- */
-export declare function addMetadata(metadata: Metadata, filters?: ReporterFilters): void;
-/**
- * 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 declare function setUser(user: ReportUser | null, filters?: ReporterFilters): void;
-/**
- * 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 declare function setRouteName(routeName: string, filters?: ReporterFilters): void;
-/**
- * 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 declare function setPageName(pageName: string, filters?: ReporterFilters): void;
-/**
- * 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 declare function reportError(error: ReportError, metadata?: Metadata, filters?: ReporterFilters): void;
-/**
- * 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 declare function recordSession(filters?: ReporterFilters): 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 declare function recordSessionStop(filters?: ReporterFilters): void;
-/**
- * Creates a Logger instance.
- * @param name Name of the Logger.
- * @param options Logger configuration options.
- */
-export declare function createLogger(name?: string, options?: {
-    metadata?: Metadata;
-}): ILogger;
+import { ReporterConfigurations, ServiceInfo } from './types';
+export * from './types';
+export * from './reporters';
+export * from './logger';
+export declare type LoggerConfig = ServiceInfo & {
+    reporters?: ReporterConfigurations;
+};
+/**
+ * Initializes the logger and reporters.
+ * @param config Reporter config options.
+ */
+export declare function init(config: LoggerConfig): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAEP,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,WAAW,EACX,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAGL,qBAAqB,EAErB,iBAAiB,EAEjB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB,cAAc,SAAS,CAAC;AAExB,eAAO,IAAI,MAAM,EAAE,OAAO,GAAG,IAAW,CAAC;AAEzC,oBAAY,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAEzD,oBAAY,cAAc,GAAG,WAAW,GAAG;IAEzC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAGhC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAGhC,GAAG,CAAC,EAAE,IAAI,GAAG,iBAAiB,CAAC;CAChC,CAAC;AAMF;;;GAGG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,cAAc,QAuB1C;AAkBD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAIrD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAgBpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,oBAAoB,GAAG,IAAI,CAOjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAIlE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAI/E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAI/E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAIpG;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAI7D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAIjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,CAUtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQ9D,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,oBAAY,YAAY,GAAG,WAAW,GAAG;IAAE,SAAS,CAAC,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAIhF;;;GAGG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,YAAY,QA2CxC"}