@newrelic/browser-agent

New Relic Browser Agent

The New Relic browser agent instruments your web application or site and provides observability into performance, errors, and other behaviors.

• The instructions on this page pertain to installing the browser agent as an NPM package.

• 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 for info on these alternatives. Releases are deployed to customers gradually, so the version available via these other methods often lags the current release of this package.

• For questions and feedback on this package, please visit the Explorer's Hub, New Relic's community support forum.

• Looking to contribute to the browser agent code base? See DEVELOPING.md for instructions on building and testing the browser agent library, and CONTRIBUTING.md for general guidance.

Adding the agent package to your project

To make the agent available to your application, install via NPM or Yarn.

$ npm install @newrelic/browser-agent --save

$ yarn add @newrelic/browser-agent

Creating an app in New Relic One

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.

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.

Instantiating the agent

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.

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.

import { BrowserAgent } from '@newrelic/browser-agent/loaders/browser-agent'

// Populate using values in copy-paste JavaScript snippet.
const options = {
  init: { ... }, // NREUM.init
  info: { ... }, // NREUM.info
  loader_config: { ...} // NREUM.loader_config
}

// The agent loader code executes immediately on instantiation.
new BrowserAgent(options)

Turning off features at runtime

Features may be turned off at runtime, which may have a meaningful peformance impact in some cases.

In the example below, the page_view_timing and session_trace features are disabled.

const options = {
  info: { ... },
  loader_config: { ... },
  init: {
    page_view_timing: { enabled: false },
    session_trace: { enabled: false },
    ...
  }
}

The following features may be disabled by adding init entries as shown above. Note that the page_view_event feature may not be disabled.

• ajax
• jserrors
• metrics
• page_action
• page_view_timing
• session_trace
• spa

See the New Relic documentation site for information on the above features.

Composing a custom agent with selected feature modules

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.

The example below includes three feature modules: Metrics, PageViewEvent, and PageViewTiming.

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'

const options = {
  info: { ... },
  loader_config: { ... },
  init: { ... }
}

new Agent({
  ...options,
  features: [
    Metrics,
    PageViewEvent,
    PageViewTiming
  ]
})

The following feature modules are available for inclusion in the features array:

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';

Supported Browsers

Our supported browser list can be accessed here.

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.

// 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: { ... }
}

new Agent({
  ...options,
  features: [
    Metrics,
    PageViewEvent,
    PageViewTiming
  ]
})

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.

DON'T mix imports between the browser agent source code and transpiled distribution code. The below will break.

// THIS IS BAD - do not do this
import { Agent } from '@newrelic/browser-agent/loaders/agent'
import { Metrics } from '@newrelic/browser-agent/src/features/metrics'

Support

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:

https://discuss.newrelic.com/c/full-stack-observability/browser

Contribute

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.

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 [e-mail].

For more details on how best to contribute, see CONTRIBUTING.md

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

If you would like to contribute to this project, review these guidelines.

To all contributors, we thank you! Without your contribution, this project would not be what it is today. We also host a community project page dedicated to the Browser agent.

License

The Browser agent is licensed under the Apache 2.0 License.

The Browser agent also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third-party notices document.

Changelog

1.235.0 (2023-06-20)

Features

• Add error mode to session trace (#583) (98e3f18)
• Decorate error objects to facilitate future UI experiences (#574) (1167c98)
• Minor feature class changes to support testing new features (#571) (a717951)
• Remove unused data from session trace requests (276c4f6)
• Use new shared session for Session Trace feature (#545) (dbd995a)