NerdGraph tutorial: 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.

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

{
  "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
            }
          }
        }
      }
    }
  }
}

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.

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

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

// Remaining code

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

{
  "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"
        }
      }
    }
  }
}

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.