@newrelic/browser-agent 0.0.9 → 0.1.230

package/README.md

@@ -1,258 +1,174 @@
-[![New Relic Experimental header](https://github.com/newrelic/opensource-website/raw/master/src/images/categories/Experimental.png)](https://opensource.newrelic.com/oss-category/#new-relic-experimental)
+[![Community Plus header](https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Community_Plus.png)](https://opensource.newrelic.com/oss-category/#community-plus)
 
 # New Relic Browser Agent
 
-The New Relic Browser Agent instruments your website and provides observability into the performance and behavior of your application. This NPM Library is an ***in-progress*** implementation of the New Relic Browser Agent, accessible through `NPM`. Please see the [Differences](#differences) and [Features](#features) sections to compare how this library differs from the other offerings of the New Relic Browser Agent.
+The New Relic browser agent instruments your web application or site and provides observability into performance, errors, and other behaviors.
 
-## Installation
+- The instructions on this page pertain to installing the browser agent as an NPM package (currently in pre-release).
 
-### Using Package Managers
+- The browser agent is also generally available as a copy-paste JavaScript snippet and via auto-injection by backend apps. See *[Install the browser agent](https://docs.newrelic.com/docs/browser/browser-monitoring/installation/install-browser-monitoring-agent/)* for info on these alternatives.
 
-Using [npm](https://npmjs.org):
+- For questions and feedback on this pre-release package, please visit the [Explorer's Hub](https://forum.newrelic.com/s/), New Relic's community support forum.
 
-```bash
-npm install @newrelic/browser-agent
-```
-
-or [yarn](https://yarnpkg.com/)
+- Looking to contribute to the browser agent code base? See [DEVELOPING.md](DEVELOPING.md) for instructions on building and testing the browser agent library, and [CONTRIBUTING.md](CONTRIBUTING.md) for general guidance.
 
-```bash
-yarn add @newrelic/browser-agent
-```
+## Adding the agent package to your project
 
-### Directly in HTML/JS
+To make the agent available to your application, install via [NPM](https://docs.npmjs.com/cli/v8/commands/npm-install) or [Yarn](https://classic.yarnpkg.com/lang/en/docs/cli/install/).
 
-Using [unpkg](https://unpkg.com/)
+```shell
+$ npm install @newrelic/browser-agent --save
+```
 
-See [Using Unpkg](#using-unpkg) for implementation details
+```shell
+$ yarn add @newrelic/browser-agent
+```
 
-ES6 compatible bundle
+## Creating an app in New Relic One
 
-```html
-<script src="https://unpkg.com/@newrelic/browser-agent/dist/bundled/es6/index.js"></script>
-```
+Before instrumenting your app using the NPM package, a Browser App should be configured in New Relic One. This may be done with or without a corresponding APM agent. Once the app has been created, the Copy/Paste JavaScript code on the app's *Application settings* page will contain the configuration values needed to define options when instantiating the agent via the NPM package.
 
-ES5 compatible bundle
+1. If a browser app does not already exist, create one:
+   - From the *New Relic One* navigation panel, click *Add Data*.
+   - Select the *Browser monitoring* data source.
+   - Choose the *APM* or *Copy/Paste* method.
+   - Select or name your app and click *Enable*.
+2. From the navigation panel, select *Browser* to view brower apps.
+3. Select the desired app and navigate to the *Application settings* page.
+4. From the *Copy/Paste JavaScript* box, copy the configuration values assigned to the `NREUM` object (`init`, `info`, and `loader_config`). You will use these configuration values when instantiating the agent using the NPM package.
 
-```html
-<script src="https://unpkg.com/@newrelic/browser-agent/dist/bundled/es5/index.js"></script>
-```
+## Instantiating the agent
 
-## Usage Examples
+For best results, import and instantiate the `BrowserAgent` class as close to the top of the `head` element of your app's HTML output as possible. The specific location and method will vary based on your application's architecture or framework.
 
-### Basic Setup
+Populate the `options` parameter using configuration values found in the the *Copy/Paste JavaScript* box in your browser app's *Application settings* page in New Relic One.
 
 ```javascript
-// << App.js >>
-// initialize the agent as close to 
-// the top level of the application as possible
-import NR from '@newrelic/browser-agent'
+import { BrowserAgent } from '@newrelic/browser-agent/loaders/browser-agent'
 
+// Populate using values in copy-paste JavaScript snippet.
 const options = {
-    // See 'Configuring your application'
+  init: { ... }, // NREUM.init
+  info: { ... }, // NREUM.info
+  loader_config: { ...} // NREUM.loader_config
 }
-const nr = new NR()
 
-nr.start(options).then(() => {
-    console.log("Browser Agent Initialized!")
-})
+// The agent loader code executes immediately on instantiation.
+new BrowserAgent(options)
 ```
 
-### Notice Errors After Setup
-```javascript
-// << SomeComponent.js >>
-// notice handled errors
-try { 
-    ...
-} catch (err){
-    nr.noticeError(err)
-}
+## Turning off features at runtime
 
-// thrown errors *anywhere* on the page will be captured if `auto` is enabled
-```
+Features may be turned off at runtime, which may have a meaningful peformance impact in some cases.
 
-### Setup Using unpkg
-
-```html
-<head>
-    <!-- Download and initialize as soon as possible to avoid missing early events -->
-    <script src="https://unpkg.com/@newrelic/browser-agent/bundled"></script>
-    <script>
-        const { BrowserAgent } = NRBA;
-        const options = {
-            // See 'Configuring your application'
-        }
-        const agent = new BrowserAgent()
-        agent.start(options).then(() => {
-            console.log("Browser Agent Initialized!")
-        })
-    </script>
-</head>
-```
+In the example below, the `page_view_timing` and `session_trace` features are disabled.
 
-### Notice Errors after Setup
 ```javascript
-// << somewhere in your app >>
-
-// notice handled errors
-try { 
+const options = {
+  info: { ... },
+  loader_config: { ... },
+  init: {
+    page_view_timing: { enabled: false },
+    session_trace: { enabled: false },
     ...
-} catch (err){
-    nr.noticeError(err)
+  }
 }
-
-// thrown errors *anywhere* on the page will be captured if `auto` is enabled
 ```
 
-### Instrumenting a Micro Front Ends or Multiple Targets
+The following features may be disabled by adding `init` entries as shown above. Note that the `page_view_event` feature may not be disabled.
 
-The New Relic Browser Agent can maintain separate configuration scopes by creating new instances. Separate NR instances can each report their own scoped data to separate New Relic applications. 
+- `ajax`
+- `jserrors`
+- `metrics`
+- `page_action`
+- `page_view_timing`
+- `session_trace`
+- `spa`
 
-```javascript
-// ---- App.js ----
-// Initialize as close to top of page as possible
-import { BrowserAgent } from '@newrelic/browser-agent'
-const options1 = {
-    // see 'Configuring your application'
-    licenseKey: 'abc',
-    applicationID: '123',
-    beacon: 'bam.nr-data.net'
-}
-const agent1 = new BrowserAgent() 
-agent1.features.errors.enabled = true // this is enabled by default, but just for visibility
-agent1.start(options1).then(() => {
-    console.log("Browser Agent (options1) Initialized!")
-})
+See the [New Relic documentation site](https://docs.newrelic.com/docs/browser/browser-monitoring/getting-started/introduction-browser-monitoring/) for information on the above features.
 
-const options2 = {
-    // see 'Configuring your application'
-    licenseKey: 'xyz',
-    applicationID: '987',
-    beacon: 'bam.nr-data.net'
-}
-const agent2 = new BrowserAgent() 
-agent2.features.errors.auto = false // do not capture global errors on this instance
-agent2.start(options2).then(() => {
-    console.log("Browser Agent (options2) Initialized!")
-})
 
-// --- NOTE ---
-// thrown errors *anywhere* on the page will be captured if `auto` is enabled in your instance
-// agent2 has disabled `auto`, and will not capture globally thrown errors
-
-// ---- NavBarComponent.js ----
-class MyComponent() {
-    try {
-        ...
-    } catch(err) {
-        agent1.noticeError(err)
-        // agent1 instance
-        // reports the error to applicationID '123', licenseKey 'abc'
-    }
-}
+## Composing a custom agent with selected feature modules
 
-// ---- SearchComponent.js ----
-class MyComponent() {
-    try {
-        ...
-    } catch(err) {
-        agent2.noticeError(err)
-        // agent2 instance
-        // reports to applicationID '987', licenseKey 'xyz'
-    }
-}
-```
+The examples above use the `BrowserAgent` class, which is the best option for most use cases. The class makes all browser agent features available but provides the ability to turn off individual features selectively.
+
+Using the base `Agent` class, it is also possible to compose a custom agent by passing an array called `features` in the `options` object, containing only the desired feature modules. Depending on which features are included, this may yield a smaller loader script and improved performance.
 
-## Configuring your application
+The example below includes three feature modules: `Metrics`, `PageViewEvent`, and `PageViewTiming`.
 
-The NR interface's `start` method accepts an `options` object to configure the agent:
+```javascript
+import { Agent } from '@newrelic/browser-agent/loaders/agent'
+import { Metrics } from '@newrelic/browser-agent/features/metrics'
+import { PageViewEvent } from '@newrelic/browser-agent/features/page_view_event'
+import { PageViewTiming } from '@newrelic/browser-agent/features/page_view_timing'
 
-```js
 const options = {
-  licenseKey: String // (required)
-  applicationID: String // (required)
-  beacon: String // (required)
-  // ... other configurations
+  info: { ... },
+  loader_config: { ... },
+  init: { ... }
 }
-nr.start(options)
-```
-
-### Get application ID, license key, beacon
-
-You can find `licenseKey`, `applicationID` and `beacon` values in the New Relic UI's Browser Application **Settings** page ([one.newrelic.com](https://one.newrelic.com) > Browser > (select an app) > Settings > Application settings.)
-
-![configuration](https://user-images.githubusercontent.com/4779220/169617807-110f3938-8af9-4aa8-b651-7712589b0792.jpg)
-
-## Features
-
-|Feature|Subfeature|Default|Description|
-|-|-|-|-|
-|errors |enabled |true|Enable's `noticeError` method|
-|errors |auto |false|Reports all global errors |
-
-> Features must be set before calling the .start() method.
-
-### JavaScript Errors
-
-This NPM package can currently capture JavaScript Error reporting in two ways. These errors will be reported to the appId & licenseKey specified in your [configuration](#configuring-your-application).
-
-```js
-import { BrowserAgent } from '@newrelic/browser-agent'
-const browserAgent = new BrowserAgent()
-
-// enable noticeError() API scoped to applicationID (enabled by default)
-browserAgent.features.errors.enabled = true
-
-// report global errors to applicationID (enabled by default)
-browserAgent.features.errors.auto = true
-
-// configure features before starting the agent
-browserAgent.start(options)
-```
-
-### Capture JavaScript errors via API
 
-```javascript
-// if browserAgent.features.errors.enabled === true (enabled by default)
-browserAgent.noticeError(new Error())
+new Agent({
+  ...options,
+  features: [
+    Metrics,
+    PageViewEvent,
+    PageViewTiming
+  ]
+})
 ```
 
-Set `browserAgent.errors.enabled` to `true` to report specific errors via the noticeError API.
-
-### Automatically capture global JavaScript errors
+The following feature modules are available for inclusion in the `features` array:
 
 ```javascript
-browserAgent.features.errors.auto = true
+import { Ajax } from '@newrelic/browser-agent/features/ajax';
+import { JSErrors } from '@newrelic/browser-agent/features/jserrors';
+import { Metrics } from '@newrelic/browser-agent/features/metrics';
+import { PageAction } from '@newrelic/browser-agent/features/page_action';
+import { PageViewEvent } from '@newrelic/browser-agent/features/page_view_event';
+import { PageViewTiming } from '@newrelic/browser-agent/features/page_view_timing';
+import { SessionTrace } from '@newrelic/browser-agent/features/session_trace';
+import { Spa } from '@newrelic/browser-agent/features/spa';
 ```
 
-Set `browserAgent.errors.auto` to `true` to report all errors on the page.
-
+## Supported Browsers
 
-## Differences
+Our supported browser list can be accessed [here](https://docs.newrelic.com/docs/browser/new-relic-browser/getting-started/compatibility-requirements-browser-monitoring/#browser-types).
 
-The Browser Agent delivered through NPM will eventually offer parity to its copy/paste and APM counterparts, but during this initial development phase, **it should not yet be treated as equivalent**.  Please see the following table describing the capabilities of each.  The availability of these features will change over time.
+If you desire more control over how the agent is built, our package also includes the source code. The source code is written to target the latest ECMAScript standards (ES2022). Please note that if you import the browser agent source code instead of the transpiled distribution code, you may need to alter your project's build system to apply transformations to the browser agent source code. Without these transforms, the code produced by your project's build system may not be compatible with your desired target browsers. Below is an example of how to import the source code.
 
-| Feature | APM Injected | Copy/Paste | NPM |
-| ------- | ------------ | ---------- | --- |
-| JavaScript Errors | Auto, API | Auto, API | `Auto, API` |
-| Page View | Auto | Auto | `None` | 
-| Page View Timings | Auto | Auto | `None` |
-| Ajax Tracking | Auto | Auto | `None` |
-| Page Actions | API | API | `None` |
-| Session Traces | Auto | Auto | `None` |
-| Browser Interactions (SPA) | Auto, API | Auto, API | `None` |
-| Multiple Configurable Instances of Browser Agent on One Page | No | No | `Yes` |
-| Configurable Code Splitting | No | No | `Yes` |
-| IDE Code Completion and Typings | No | No | `Yes` |  
+```javascript
+// Note the /src/ in the import paths below
+import { Agent } from '@newrelic/browser-agent/src/loaders/agent'
+import { Metrics } from '@newrelic/browser-agent/src/features/metrics'
+import { PageViewEvent } from '@newrelic/browser-agent/src/features/page_view_event'
+import { PageViewTiming } from '@newrelic/browser-agent/src/features/page_view_timing'
 
+const options = {
+  info: { ... },
+  loader_config: { ... },
+  init: { ... }
+}
 
-## Contributing
+new Agent({
+  ...options,
+  features: [
+    Metrics,
+    PageViewEvent,
+    PageViewTiming
+  ]
+})
+```
 
-We encourage your contributions to improve the Browser agent! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
+Neither the browser agent development team nor the New Relic support teams can support the numerous build systems that exist in the JavaScript ecosystem. If you run into issues, you may be asked to revert to importing from the transpiled distribution code.
 
-If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.
+**DON'T** mix imports between the browser agent source code and transpiled distribution code. The below will break.
 
-For more details on how best to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md)
+```javascript
+// THIS IS BAD - do not do this
+import { Agent } from '@newrelic/browser-agent/loaders/agent'
+import { Metrics } from '@newrelic/browser-agent/src/features/metrics'
+```
 
 ## License
 

package/dist/cjs/cdn/lite.js

@@ -0,0 +1,14 @@
+"use strict";
+
+var _agent = require("../loaders/agent");
+var _instrument = require("../features/page_view_event/instrument");
+var _instrument2 = require("../features/page_view_timing/instrument");
+var _instrument3 = require("../features/metrics/instrument");
+/**
+ * @file Creates a "Lite" agent loader bundle composed of the core Agent and a subset of available feature modules.
+ */
+
+new _agent.Agent({
+  features: [_instrument.Instrument, _instrument2.Instrument, _instrument3.Instrument],
+  loaderType: 'lite'
+});

package/dist/cjs/cdn/polyfills/lite.js

@@ -0,0 +1,4 @@
+"use strict";
+
+require("../polyfills.js");
+require("../lite");

package/dist/cjs/cdn/polyfills/pro.js

@@ -0,0 +1,4 @@
+"use strict";
+
+require("../polyfills.js");
+require("../pro");

package/dist/cjs/cdn/polyfills/spa.js

@@ -0,0 +1,4 @@
+"use strict";
+
+require("../polyfills.js");
+require("../spa");

package/dist/cjs/cdn/polyfills.js

@@ -0,0 +1,14 @@
+"use strict";
+
+require("core-js/stable/promise");
+require("core-js/stable/array/includes");
+require("core-js/stable/array/from");
+require("core-js/stable/array/find");
+require("core-js/stable/array/some");
+require("core-js/stable/object/assign");
+require("core-js/stable/object/entries");
+require("core-js/stable/object/values");
+require("core-js/stable/map");
+require("core-js/stable/reflect");
+require("core-js/stable/set");
+require("core-js/stable/weak-set");

package/dist/cjs/cdn/pro.js

@@ -0,0 +1,19 @@
+"use strict";
+
+var _agent = require("../loaders/agent");
+var _instrument = require("../features/page_view_event/instrument");
+var _instrument2 = require("../features/page_view_timing/instrument");
+var _instrument3 = require("../features/metrics/instrument");
+var _instrument4 = require("../features/jserrors/instrument");
+var _instrument5 = require("../features/ajax/instrument");
+var _instrument6 = require("../features/session_trace/instrument");
+var _instrument7 = require("../features/page_action/instrument");
+/**
+ * @file Creates a "Pro" agent loader bundle composed of the core Agent and all available feature modules except `spa`.
+ * This excludes collection of BrowserInteraction and BrowserTiming events.
+ */
+
+new _agent.Agent({
+  features: [_instrument.Instrument, _instrument2.Instrument, _instrument6.Instrument, _instrument5.Instrument, _instrument3.Instrument, _instrument7.Instrument, _instrument4.Instrument],
+  loaderType: 'pro'
+});

package/dist/cjs/cdn/spa.js

@@ -0,0 +1,19 @@
+"use strict";
+
+var _agent = require("../loaders/agent");
+var _instrument = require("../features/page_view_event/instrument");
+var _instrument2 = require("../features/page_view_timing/instrument");
+var _instrument3 = require("../features/metrics/instrument");
+var _instrument4 = require("../features/jserrors/instrument");
+var _instrument5 = require("../features/ajax/instrument");
+var _instrument6 = require("../features/session_trace/instrument");
+var _instrument7 = require("../features/spa/instrument");
+var _instrument8 = require("../features/page_action/instrument");
+/**
+ * @file Creates a "SPA" agent loader bundle composed of the core agent and all available feature modules.
+ */
+
+new _agent.Agent({
+  features: [_instrument5.Instrument, _instrument.Instrument, _instrument2.Instrument, _instrument6.Instrument, _instrument3.Instrument, _instrument8.Instrument, _instrument4.Instrument, _instrument7.Instrument],
+  loaderType: 'spa'
+});

package/dist/cjs/cdn/worker.js

@@ -0,0 +1,16 @@
+"use strict";
+
+var _agent = require("../loaders/agent");
+var _instrument = require("../features/metrics/instrument");
+var _instrument2 = require("../features/jserrors/instrument");
+var _instrument3 = require("../features/ajax/instrument");
+var _instrument4 = require("../features/page_action/instrument");
+/**
+ * @file Creates a "Worker" agent loader bundle composed of the core Agent and the subset of feature modules applicable
+ * in a service worker context.
+ */
+
+new _agent.Agent({
+  features: [_instrument.Instrument, _instrument2.Instrument, _instrument3.Instrument, _instrument4.Instrument],
+  loaderType: 'worker'
+});

package/dist/cjs/common/aggregate/aggregator.js

@@ -0,0 +1,168 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Aggregator = void 0;
+var _sharedContext = require("../context/shared-context");
+var _mapOwn = require("../util/map-own");
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+class Aggregator extends _sharedContext.SharedContext {
+  constructor(parent) {
+    super(parent);
+    this.aggregatedData = {};
+  }
+
+  // Items with the same type and name get aggregated together
+  // params are example data from the aggregated items
+  // metrics are the numeric values to be aggregated
+
+  store(type, name, params, newMetrics, customParams) {
+    var bucket = this.getBucket(type, name, params, customParams);
+    bucket.metrics = aggregateMetrics(newMetrics, bucket.metrics);
+    return bucket;
+  }
+  merge(type, name, metrics, params, customParams) {
+    var bucket = this.getBucket(type, name, params, customParams);
+    if (!bucket.metrics) {
+      bucket.metrics = metrics;
+      return;
+    }
+    var oldMetrics = bucket.metrics;
+    oldMetrics.count += metrics.count;
+
+    // iterate through each new metric and merge
+    (0, _mapOwn.mapOwn)(metrics, function (key, value) {
+      // count is a special case handled above
+      if (key === 'count') return;
+      var oldMetric = oldMetrics[key];
+      var newMetric = metrics[key];
+
+      // handling the case where newMetric is a single-value first
+      if (newMetric && !newMetric.c) {
+        oldMetrics[key] = updateMetric(newMetric.t, oldMetric);
+      } else {
+        // newMetric is a metric object
+        oldMetrics[key] = mergeMetric(newMetric, oldMetrics[key]);
+      }
+    });
+  }
+  storeMetric(type, name, params, value) {
+    var bucket = this.getBucket(type, name, params);
+    bucket.stats = updateMetric(value, bucket.stats);
+    return bucket;
+  }
+  getBucket(type, name, params, customParams) {
+    if (!this.aggregatedData[type]) this.aggregatedData[type] = {};
+    var bucket = this.aggregatedData[type][name];
+    if (!bucket) {
+      bucket = this.aggregatedData[type][name] = {
+        params: params || {}
+      };
+      if (customParams) {
+        bucket.custom = customParams;
+      }
+    }
+    return bucket;
+  }
+  get(type, name) {
+    // if name is passed, get a single bucket
+    if (name) return this.aggregatedData[type] && this.aggregatedData[type][name];
+    // else, get all buckets of that type
+    return this.aggregatedData[type];
+  }
+
+  // Like get, but for many types and it deletes the retrieved content from the aggregatedData
+  take(types) {
+    var results = {};
+    var type = '';
+    var hasData = false;
+    for (var i = 0; i < types.length; i++) {
+      type = types[i];
+      results[type] = toArray(this.aggregatedData[type]);
+      if (results[type].length) hasData = true;
+      delete this.aggregatedData[type];
+    }
+    return hasData ? results : null;
+  }
+}
+exports.Aggregator = Aggregator;
+function aggregateMetrics(newMetrics, oldMetrics) {
+  if (!oldMetrics) oldMetrics = {
+    count: 0
+  };
+  oldMetrics.count += 1;
+  (0, _mapOwn.mapOwn)(newMetrics, function (key, value) {
+    oldMetrics[key] = updateMetric(value, oldMetrics[key]);
+  });
+  return oldMetrics;
+}
+function updateMetric(value, metric) {
+  // when there is no value, then send only count
+  if (value == null) {
+    return updateCounterMetric(metric);
+  }
+
+  // When there is only one data point, the c (count), min, max, and sos (sum of squares) params are superfluous.
+  if (!metric) return {
+    t: value
+  };
+
+  // but on the second data point, we need to calculate the other values before aggregating in new values
+  if (!metric.c) {
+    metric = createMetricObject(metric.t);
+  }
+
+  // at this point, metric is always uncondensed
+  metric.c += 1;
+  metric.t += value;
+  metric.sos += value * value;
+  if (value > metric.max) metric.max = value;
+  if (value < metric.min) metric.min = value;
+  return metric;
+}
+function updateCounterMetric(metric) {
+  if (!metric) {
+    metric = {
+      c: 1
+    };
+  } else {
+    metric.c++;
+  }
+  return metric;
+}
+function mergeMetric(newMetric, oldMetric) {
+  if (!oldMetric) return newMetric;
+  if (!oldMetric.c) {
+    // oldMetric is a single-value
+    oldMetric = createMetricObject(oldMetric.t);
+  }
+  oldMetric.min = Math.min(newMetric.min, oldMetric.min);
+  oldMetric.max = Math.max(newMetric.max, oldMetric.max);
+  oldMetric.t += newMetric.t;
+  oldMetric.sos += newMetric.sos;
+  oldMetric.c += newMetric.c;
+  return oldMetric;
+}
+
+// take a value and create a metric object
+function createMetricObject(value) {
+  return {
+    t: value,
+    min: value,
+    max: value,
+    sos: value * value,
+    c: 1
+  };
+}
+function toArray(obj) {
+  if (typeof obj !== 'object') return [];
+  return (0, _mapOwn.mapOwn)(obj, getValue);
+}
+function getValue(key, value) {
+  return value;
+}