• EnglishEspañol日本語한국어Português
  • Log inStart now

Instrument multiple apps with npm and NerdGraph

You can use our NerdGraph API to create a new browser application and retrieve the configuration values. This can be combined with the browser agent npm package to incorporate the configuration of the browser agent as part of your application build process or separate the configuration of the agent from the implementation of the agent within your application.

If you've never used NerdGraph to create or configure a browser application, first read this NerdGraph tutorial.

Set up the agent

Open your IDE and a terminal in the root of your project or where your frontend dependencies are managed. This is the location where you will run npm install --save @newrelic/browser-agent to install the npm package. Once installed, locate the main entry point file for your website. This may be <project_root>/src/index.js or <project_root>/src/index.ts but could be different in your application. If you have multiple entrypoints, select the one that loads the soonest in the browser and preferrably is not using the async or defer script element attributes.

Once you have located where you want to add the browser agent, add this code snippet in that file.

import { BrowserAgent } from '@newrelic/browser-agent/loaders/browser-agent'
// Remaining import statements
// Populate using values from NerdGraph
const options = {
init: { ... },
info: { ... },
loader_config: { ...}
}
// The agent loader code executes immediately on instantiation.
new BrowserAgent(options)
// Remaining code

The import statement for the browser agent should be the first thing in your source file. After the remaining import statements, immediately instantiate and configure the browser agent. Be sure to do this before any other code so the browser agent has a chance to load and capture data as early as possible.

Retrieve the configuration

The options object in the previous snippet needs to be populated with configuration information about the browser application from New Relic. For the purposes of this tutorial, we will use the New Relic UI with an existing browser application and the NerdGraph Explorer to complete the API calls.

Get browser application entity GUID

To use the NerdGraph API, you'll need to get the entity GUID for the browser application you're instrumenting.

Retrieve browser application config

Open the NerdGraph Explorer at api.newrelic.com/graphiql and use the below query to retrieve the config values for the browser application. If your New Relic account uses an EU data center, go to api.eu.newrelic.com/graphiql.

query {
actor {
entity(guid: '<guid>') {
... on BrowserApplicationEntity {
guid
name
browserProperties {
jsConfigScript
}
}
}
}
}

Replace the <guid> portion of the query with the entity GUID you retrieved earlier. Run the query and you should receive output like that shown here:

{
"data": {
"actor": {
"entity": {
"browserProperties": {
"jsConfig": {
"info": {
"applicationID": 1234567,
"beacon": "bam.nr-data.net",
"errorBeacon": "bam.nr-data.net",
"licenseKey": 123456789,
"sa": 1
},
"init": {
"ajax": {
"deny_list": [
"bam-cell.nr-data.net"
]
},
"distributed_tracing": {
"allowed_origins": [],
"cors_enabled": false,
"cors_use_newrelic_header": false,
"cors_use_tracecontext_headers": false,
"enabled": true,
"exclude_newrelic_header": false
},
"privacy": {
"cookies_enabled": true
}
},
"loader_config": {
"accountID": <redacted>,
"agentID": <redacted>,
"applicationID": <redacted>,
"licenseKey": "<redacted>",
"trustKey": 1672072
}
}
}
}
}
}
}

Tip

Need more information on using NerdGraph? See Introduction to NerdGraph.

Install the config

Copy the contents of the jsConfig property and replace the contents of the options object your source file.

Deploy using the npm package

With the npm package installed and properly configured, you can now build and deploy your browser application. Load your website in a browser and verify there are network calls being made to the beacon URI from the config.

Inject browser application config into HTML

As an alternative to placing the browser application configuration in your source code, you may want to inject the configuration into the HTML of your website. This is especially useful when your source code is reused across multiple websites.

Modify source code snippet

Modify the first snippet in your source code to import and instantiate the BrowserAgent class with no parameters.

import { BrowserAgent } from '@newrelic/browser-agent/loaders/browser-agent'
// Remaining import statements
// The agent loader code executes immediately on instantiation.
new BrowserAgent()
// Remaining code

Modify NerdGraph query

Modify the NerdGraph query to retrieve the browser application config as a JSON encoded script string. Run the new query remembering to replace <guid> with the browser application entity GUID retrieved earlier.

query {
actor {
entity(guid: '<guid>') {
... on BrowserApplicationEntity {
guid
name
browserProperties {
jsConfigScript
}
}
}
}
}

This will return a result like:

{
"data": {
"actor": {
"entity": {
"browserProperties": {
"jsConfigScript": "<script type=\"text/javascript\">\n;window.NREUM||(NREUM={});NREUM.init={distributed_tracing:{enabled:true},privacy:{cookies_enabled:true},ajax:{deny_list:[\"bam-cell.nr-data.net\"]}};\n\n;NREUM.loader_config={accountID:\"<redacted>\",trustKey:\"<redacted>\",agentID:\"<redacted>\",licenseKey:\"<redacted>\",applicationID:\"<redacted>\"};\n;NREUM.info={beacon:\"bam.nr-data.net\",errorBeacon:\"bam.nr-data.net\",licenseKey:\"<redacted>\",applicationID:\"<redacted>\",sa:1};\n</script>\n"
}
}
}
}
}

Install the config

Copy the contents of the jsConfigScript property. You will need to run the results through a JSON parser or replace the values of \" with ". The result will be a string containing a <script> element with all the browser application config information. Place the <script> element at the top of the <head> element, but below any <meta> elements, of your website HTML.

Next steps

This tutorial only scratches the surface of how you might use our NerdGraph API and the browser agent npm package. Some ideas for next steps:

  • Integrate the browser agent into your website builder application and use NerdGraph to retrieve the browser application config for each of your customers when they enable New Relic monitoring within your management dashboard.
  • Create a shared browser agent component in your organization's component library and automatically injects the configuration into the HTML using a CDN edge function that calls NerdGraph.
  • Modify your CI/CD pipeline to populate the source code with different browser application configurations from NerdGraph based on what environment is being deployed to.
Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.