Have you ever wanted to customize which features of the New Relic browser agent you ship to your customers? Maybe you need to support different or older browsers than the browser agent does in its browser support matrix? Since the browser agent is open source, you have the option to fork the repository, modify the code, and build your own custom browser agent. But this process comes with the extra overhead of managing a forked repository: learning the code, building the system, testing tools, etc. Top it off with keeping up to date with the changes being made to the main browser agent repository and this task of managing a fork can be overwhelming.
The browser agent has a solution for this: an npm package that you can use instead. The npm package allows you to import the browser agent in your client-side application, pick which features to deploy, and include the agent in the same JavaScript build process you already use. In this blog post, you’ll learn how to do all of the above with examples, and where you can go to learn more.
Why should you check out the npm package? It can open the door to easy customization in these use cases:
- Shipping a subset of the included features of the browser agent.
- Supporting browsers that the browser agent does not natively support.
- Controlling which version of the browser agent is used in your application and when the version changes.
- Injecting different browser agent configurations into the HTML for different instances of your app (multiple environments or customers).
- Eliminating the total cost of ownership that comes with maintaining a forked repository of the open source browser agent.
Create a browser app and get its configuration values
To get started, you will need to create a new browser app in New Relic or locate an existing browser app that you would like to use with the npm package. This may be done with or without a corresponding APM agent. To create an app, follow these instructions:
- Open New Relic, and select Add Data from the navigation panel.
- Select Browser & mobile, then select the Browser monitoring data source.
- Choose your deployment method, either APM or Copy/Paste.
- Select an existing app monitored in APM, or name your new app and click Enable.
Next, you’ll need to get configuration values for your browser app in order to define options when instantiating the agent via the npm package:
- From the navigation panel in New Relic, select Browser to view your browser apps.
- Select the desired app and navigate to the Application settings page.
- From the Copy/Paste JavaScript box, copy the configuration values assigned to the NREUM object:
init,info, andloader_config. You will use these configuration values when instantiating the agent using the npm package.
Set up instrumentation with the npm package
To make the agent available to your application, install via NPM or Yarn.
$ npm install @newrelic/browser-agent --save
$ yarn add @newrelic/browser-agentFor best results, it is important that the browser agent loads as early as possible on the page. Since the browser agent is going to be bundled into your browser application, you need to pick a location that ensures it runs early, preferably first. Most browser applications will have a JavaScript or Typescript file that is referred to as the entry point. This is the first file that is executed when your site loads and is the best location to instantiate the browser agent.
Modify your browser application’s entry point source file so it looks similar to the next example.
import { BrowserAgent } from '@newrelic/browser-agent/loaders/browser-agent'
// The rest of your client-side application imports
// 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)
// The rest of your client-side application codeUpdate the options object with the values from the NREUM object in New Relic: the values for init, info, and loader_config. Build and deploy your browser application to apply the changes. Now you have the same full and automatic instrumentation of your site that you would get with Copy/Paste and APM injection methods.
Customize your instrumentation
The BrowserAgent class is a utility class that includes all the available features of the browser agent. The npm package also contains an Agent class that allows you to pass in an array of features that you would like to include. This allows you to customize what is being instrumented and reported to New Relic for your site.
Check out the next code snippet. This example includes all the current features that can be enabled for the browser agent. But you can pick and choose which ones you want to import and include in the features array.
import { Agent } from '@newrelic/browser-agent/loaders/agent'
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';
// The rest of your client-side application imports
// Populate using values in copy-paste JavaScript snippet.
const options = {
init: { ... }, // NREUM.init
info: { ... }, // NREUM.info
loader_config: { ... }, // NREUM.loader_config
features: [
Ajax,
JSErrors,
Metrics,
PageAction,
PageViewEvent,
PageViewTiming,
SessionTrace,
Spa
]
}
// The agent loader code executes immediately on instantiation.
new Agent(options)
// The rest of your browser application codeJavaScript toolchain support
Client-side build tools vary, but many of these tools offer useful features for integrating and customizing the browser agent npm package. For example, webpack can be configured to apply transformations to the browser agent npm package to provide support for browsers not in our browser support matrix. Check out the next code snippet for an example.
{
... // Other webpack config settings
rules: [{
test: /\.(js|jsx)$/i,
exclude: /node_modules\/(?!@newrelic\/browser-agent).*/,
use: 'babel-loader'
}],
... // Other webpack config settings
}In this webpack configuration, the exclude property of the babel rule has been updated so the browser agent npm package is also transformed by babel. Similar support for transforming npm package code is available in many other JavaScript build tools.
Video demo: Adding the customizable browser agent to a React app
Watch the next video from Johnathan Potter for a walkthrough of the process you just learned about. In this example, you’ll add the newrelic-browser-agent package to a React app.
Next steps
The browser agent npm package can provide more customization options for your instrumentation needs—you can unlock instrumentation for customers on older browsers, or in unique use-cases like gaming console browsers and smart TV applications. Continue exploring with these resources:
- Share your feedback, good or bad, around your use cases in the New Relic community forums.
- Visit the public open source newrelic-browser-agent repository for more information on configuring the agent.
- Learn more about browser monitoring in the New Relic documentation.
Don't have New Relic yet? Sign up for a free account. Your account includes 100 GB/month of free data ingest, one free full-platform user, and unlimited free basic users.
The views expressed on this blog are those of the author and do not necessarily reflect the views of New Relic. Any solutions offered by the author are environment-specific and not part of the commercial solutions or support offered by New Relic. Please join us exclusively at the Explorers Hub (discuss.newrelic.com) for questions and support related to this blog post. This blog may contain links to content on third-party sites. By providing such links, New Relic does not adopt, guarantee, approve or endorse the information, views or products available on such sites.
