Related pages:

This page describes how JavaScript Agent injection works, including the different injection types. 

To instrument your application for Browser RUM, you must configure your JavaScript Agent and insert it into the page that is returned to the end user as part of the normal process it follows. The act of inserting the agent is called injection. There are several ways to inject the JavaScript Agent for Browser RUM into your web pages. You also have several JavaScript hosting options to choose from that offer differing degrees of control, simplicity, and reliability.

To configure the JavaScript Agent, see Configure the JavaScript Agent.

How the JavaScript Agent Works

The JavaScript Agent consists of two files: adrum.js and adrum-ext.js.

  1. The file adrum.js is injected into each instrumented page, as close to the top as possible, as the page is served. The file loads synchronously at around 90 KB (30 KB with compression).
  2. This first JavaScript file starts a timer and does some quick configuration and setup.
  3. At the onload event, adrum-ext.js is fetched asynchronously to prevent blocking the page load. This is the code that does most of the heavy lifting. Once it has been fetched, it is cached for 24 hours on the browser. 
  4. When cross-domain session correlation is enabled, the first time a user visits a domain, the browser additionally loads the file adrum-xd.html to generate or load a piece of common information that enables cross-domain sessions. Future visits will not load adrum-xd.html again.
  5. When the page has completed loading, the collected data is bundled into a beacon and sent to the EUM Server by adrum-ext.js. 
  6. The data is processed by the EUM Server and then made available for pickup by the Controller.

Not all types of injection are supported on all frameworks and platforms. See the Script Injection columns in the Supported Platform Matrix for Browser Monitoring matrices to find out what types are supported for your application.

Injection Methods

There are three methods for injecting the JavaScript Agent. See the following for each injection method:

JavaScript Agent Hosting Options

The adrum.js file is inserted into the page when it is downloaded from your web application. The adrum-ext.js (and adrum-xd.html when cross-domain session correlation is enabled) file is loaded asynchronously by the adrum.js file. By default, adrum-ext.js and adrum-xd.html are fetched by the highly available Amazon CloudFront CDN infrastructure.

There are three hosting options for the JavaScript Agent:

  • AppDynamics CDN - All the JavaScript Agent files are from the host cdn.appdynamics.com. This is the simplest hosting option and ideal for testing.

  • Self-Hosting - You host all of the JavaScript Agent files. This option gives you the most control and is recommended for production. 

  • Shared Hosting - You host the main file adrum.js, but the other files that are loaded asynchronously are from the AppDynamics CDN. This choice offers control of the most important file of the JavaScript Agent and is ideal for small to medium-sized businesses that don't have the resources or prefer not to host the entire JavaScript Agent.

See Manual Injection of the JavaScript Agent for step-by-step instructions. 

Cross-domain session correlation

By default, Browser RUM sessions are restricted to one domain. Thus, when an end user navigates to a page in another domain or even subdomain, the session for that user is ended. You can, however, configure Browser RUM to enable sessions to continue across subdomains. Thus, when an end user navigates from http://example1.com/ to http://example2.com/, the session will continue as long as the configured session inactivity time has not expired.

How Sessions Are Correlated Across Multiple Domains

For sessions to be correlated across domains, each page is required to use HTTPS to load the file adrum-xd.html from the same URL. If your pages are fetching the files adrum-ext.js and adrum-xd.html files from the AppDynamics CDN (this includes the shared hosting use case), sessions will automatically be correlated across domains because the pages will be fetching the file adrum-xd.html from the AppDynamics CDN.

For those self-hosting the JavaScript Agent files, you will need to configure the JavaScript Agent to use HTTPS to load the adrum-ext.js file from the same URL. The  adrum-xd.html file is served from the location of the adrum-ext.js file. See the sections below for configuration instructions for the two use cases.

Configuration for Session Correlation Across Multiple Domains

AppDynamics CDN / Shared Hosting

When using the AppDynamics CDN or shared hosting, your JavaScript Agent configurations must enable cross-domain session correlation and use HTTPS to call the adrum-ext.js file. Thus, in your JavaScript Agent configuration make sure you have the following lines:

...
config.adrumExtUrlHttps = 'https://cdn.appdynamics.com';;
config.xd = {enable : true};
...
JS

Self-Hosting

When using self-hosting, your JavaScript Agent configurations must enable cross-domain session correlation and use HTTPS to call the adrum-ext.js file from the same URL. Thus, in your JavaScript Agent configuration make sure you have the following lines and that the value for adrumExtUrlHttps is the same for all pages requiring cross-domain session correlation.

...
// HTTPS is needed to fetch adrum-xd.html.
config.adrumExtUrlHttps = 'https://<your-adrum.ext-host>';
// This config enables cross-domain session correlation.
 config.xd = {enable : true};
...
JS

Set the Geo Server URL

By default, end-users' locations are resolved using public geographic databases. You can host an alternate geo server for your countries, regions, and cities instead of using the default geo server hosted by AppDynamics. See Install and Host a Custom Geo Server for Browser RUM.

Custom Configuration

You can add configuration for adrum.js to customize and extend the functionality of the JavaScript Agent. See Configure the JavaScript Agent for instructions and examples on adding custom configuration.

JavaScript Agent Limitations

The JavaScript Agent cannot monitor and report the activity of service workers or web workers. For example, if you use a service worker to make an XHR request, the JavaScript Agent will not be able to report it.