Configure the JavaScript Agent

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.

This page provides an overview of configurations for the JavaScript Agent. For instructions on how to configure the JavaScript Agent, see the following:

• Manual Injection
• Automatic Injection
• Assisted Injection

How Browser RUM Works

Browser RUM works in the following way:

1. An end user requests the first page from your web application.
2. Your web application executes whatever business logic that the particular page requires.
3. Your web application creates the response page to return to the end user. The response page includes:
   1. application specific information
   2. a copy of a small JavaScript script that knows how to collect relevant performance information about that page. This script is called the JavaScript Agent.
4. The page, with the JavaScript Agent included, is returned to the end user.  
5. As the page is being constructed in the browser, the script collects relevant information about the page's performance.
6. At approximately the same time as the onload event for the page fires, a copy of a somewhat larger JavaScript file, the JavaScript Agent extension, is downloaded asynchronously by the injected agent.
7. This second script packages the collected performance information and sends it via a web beacon to the EUM Server collector for processing.
8. Working together the two scripts continue to collect and send performance information as the end user navigates through the instrumented pages of your application.

JavaScript Agent Hosting Options

The JavaScript Agent consists of the three files adrum.js, adrum-ext.js, and adrum-xd.js. The first file is inserted into the page when it is downloaded from your web application. The second and third file are loaded asynchronously by the first. By default, adrum-ext.js, and adrum-xd.js are fetched the highly available Amazon CloudFront CDN infrastructure.

You have the following 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 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.

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 Cross-Domain Sessions Are Correlated

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 Cross-Domain Session Correlation

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};
...

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};
...

Alternate Geo Server Location

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 Customize the JavaScript Agent for instructions and examples on adding custom configuration.