This page contains information about working on the New Relic Browser agent project in a local development environment. For info on implementing the Browser agent in your own application, see the resources below:
- Installing the Browser agent
- Troubleshooting Browser agent installation
- Introduction to browser monitoring
- Browser monitoring best practices
- Browser agent NPM package (pre-release)
We use webpack to automate builds of the agent. To build:
npm ci
npm run cdn:build:localBuild artifacts are placed in the /build directory.
To automatically rebuild the agent on each change:
npm run cdn:watchThe Browser agent is loaded onto a web page in two parts. To install a version of the agent build locally:
- Host the assets generated in the
/builddirectory via a local HTTP server (see instructions above to build the agent). - Insert the script below into the top of the
<head>tag of your webpage.
<!-- Browser agent configuration -->
<script type="text/javascript">
window.NREUM || (NREUM = {});
NREUM.info = {
licenseKey: "example",
applicationID: 123,
};
</script>
<!-- Browser agent loader script -->
<script src="http://localhost:8080/nr-loader-spa.js"></script>NOTE: Your browser might cache JS scripts, which means you may not see your changes when the agent files are re-built. To turn off caching in Chrome, open DevTools and check the Disable cache checkbox.
The prebuilt test server can serve the locally built agent files as noted under Debugging Tests below. To use this server, run the npm run test-server command.
The Browser agent uses a JSON configuration to set license key and application ID.
You can find the licenseKey and applicationID in the New Relic UI's Browser Application Settings page (one.newrelic.com > Browser > (select an app) > Settings > Application settings.)
Pick an agent type and update the following files from the table below:
- The file loaded as the Browser agent loader script from the HTML above using loader filename
| Agent type | loader filename |
|---|---|
| Lite | nr-loader-rum.min.js |
| Pro | nr-loader-full.min.js |
| Pro + SPA | nr-loader-spa.min.js |
The agent loader will automatically import any necessary chunks of code later on the page after being successfully initialized wiht configurations.
See the sections below for details about local and PR testing.
The Browser agent uses a tool called the JavaScript Integration test Loader (jil) to run
tests (located in /tools/jil).
Before running tests locally, be sure to install and build from the root directory to ensure all dependencies are loaded and the application is properly built.
npm install
npm run build:all
To run all tests on a specific browser/platform, you can either run on Saucelabs or point the testing framework to your own Selenium server.
To run tests on Saucelabs, you will need your own Saucelabs account. Export your Saucelabs username and access key in these environment variables - JIL_SAUCE_LABS_USERNAME, JIL_SAUCE_LABS_ACCESS_KEY. After that you can use the following command to run tests on a specific browser. Note that the browser/platform needs to be defined in this matrix file.
Here is an example of running all tests on the latest version of Chrome.
npm run test -- -s -b chrome@latest
Here is an example of using your own Selenium server:
npm run test -- -b chrome@latest --selenium-server=localhost:4444
- The browser agent is tested against this list of browsers and environments. Use of the browser agent with untested browsers may lead to unexpected results.
Important Notes:
jildoes not handle building the agent automatically; either runnpm run build:allafter each change, or usenpm run watchto automatically rebuild on each change.- To pass arguments to the testing suite using
npm run testyou must separate your arguments from the npm script using an empty--parameter as was exemplified above.
To run a single test in isolation, pass the path to jil:
npm run test -- tests/functional/api.test.js
To debug a unit test (/tests/browser) or the asset under test in a unit or functional test (/tests/assets), run the command below:
npm run test-server
Running this command starts a server, available at http://localhost:3333, with a list of all available unit tests and test HTML pages with the Browser agent installed. Select a unit test from the list to run the test itself in your browser, or select an asset from the list to debug.
Important: When running jil-server be sure to tell HTML files which Browser agent type you want by adding a ?loader=spa to the querystring. Here's an example:
http://localhost:3333/tests/assets/spa/fetch.html?loader=spa
| Agent type | querystring name |
|---|---|
| Lite | rum |
| Pro (default) | full |
| Pro + SPA | spa |
When you open a PR, the agent's functional and unit test suite will be run on the latest version of Chrome, Firefox and Safari to quickly validate the new code. If that passes, the PR will run functional and unit tests again against the full matrix of browsers and browser versions that are required to pass before approving a PR.
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
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 [email protected].
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.
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.