Set Up Your Application for Browser RUM

Injection Overview

Browser RUM works in the following way:

1. An end user requests a 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 from AWS asynchronously by the injected agent.
7. This second script packages the collected performance information and sends it via a web beacon to the EUM Cloud 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.

To instrument your application for Browser RUM you must set up your web application to insert the JavaScript agent file 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. 

Manual Injection

Manual injection is supported on all platforms and frameworks.  To set up a manually injected page, you:

• Download the JavaScript agent to your local environment

• Manually configure each page you wish to instrument to find the script where you stored it so that it can be executed as the page is constructed by the browser.

  You can also choose to point your page to an AppDynamics hosted version of the JavaScript agent instead of hosting it locally. See Options in Using Manual Injection for the Browser RUM JavaScript Agent for more information.

For detailed instructions on using manual injection in your application, see Manual Injection.

Automatic Injection

If you are using a Java or .Net app agent on the server-side, and your application is running in an environment that supports the Apache Jasper JSP compiler (for Java) or ASP.NET or ASPX (for .NET), you may be able to use automatic injection, where the server-side app agent completely manages injecting the code at runtime.  For detailed instructions on using automatic injection in your application, see Automatic Injection.

Assisted Injection

Assisted injection is available in two variants.  In both cases some of the work is done manually by you and some of the work is done by the server-side Java or .Net app agent.

Assisted Injection using Injection Rules (Java only)

In this type of assisted injection you configure rules that define which app server Java classes and methods write to the output stream of your application and the writer object that is used to do that writing.  AppDynamics intercepts the method and injects the JavaScript agent into the output stream. You also specify which server-side business transactions you wish to have instrumented in this way.

For detailed information on using this form of assisted injection, see Assisted Injection-Using Injection Rules - Java Only.

Assisted Injection using Attribute Injection

In this type of assisted injection you copy small code snippets appropriate to your framework into your page templates or other code that creates your pages.  This snippet contains two variables, JS_HEADER and JS_FOOTER, which the app agent replaces with the appropriate information in the response object at runtime.

For detailed information on using this form of assisted injection, see Assisted Injection-Using Attribute Injection.

Containter-based Injection

If you are using Nginx or Apache as a web container, or as a reverse proxy in front of your web container, you can use directives to inject the agent into the response object.  See Container Assisted Injection for more information.

Choosing an Injection Method

If you are uncertain which procedure to use to inject the  agent into your web pages, follow these guidelines, in this order:

• If you want to use Browser RUM and do not have any app agents on the server side, use manual injection. See Manual Injection.

• If automatic injection is available and works for your framework, use automatic injection.

Automatic injection requires the least amount of effort because you do not have to manually instrument every page. Check the matrices at Browser RUM Supported Environments  to see if automatic injection has been tested in your environment. Also see Automatic Injection.

• If you cannot use automatic injection, and you can edit the source code of your web pages, use manual injection. See Manual Injection.

• If you cannot use automatic injection, and you can edit the source code of your web application, use one of the kinds of assisted injection. See Assisted Injection-Using Injection Rules (Java Only) or Assisted Injection-Using Attribute Injection.

Verifying Injection with Manual Injection

Once the agent is injected, it can take the AppDynamic controller a few minutes to discover and recognize the page, which must happen before data will begin to appear. If, however, you have configured your page using manual injection and are not seeing Browser RUM metrics after running load for a while, check the web page to confirm that the JavaScript Agent for Browser RUM is present in the page. If it is not, try injecting the script again.

If after two attempts you still do not see Browser RUM metrics, try one of the other injection schemes if they are available for your platform.  See Check Browser RUM Configuration Issues for more troubleshooting information.

Reversing Injection

If you try one way to inject and it does not work, AppDynamics recommends that you undo the current injection configuration before implementing another one.

• To undo automatic injection, just clear the Enable Automatic Injection of JavaScript check box.
• To undo assisted injection using attribute injection, clear the Request Attribute Injection check.
• To undo manual manually delete the JavaScript Agent for Browser Monitoring from your web pages. 
• To undo assisted injection using injection rules, clear the Enable check box for each injection rule in the injection rules list.

If multiple copies of the agent exist on a page, the second copy does not execute.

Getting Full Timing Data for Associated Business Transactions

To get the full real execution time for correlated business transactions your injection method may need to write the JS_FOOTER data variable to your page. Manual injection gives the server-side agent the ability to write data only to the header of the page as it is being constructed by your web application.  It is possible that complete business-transaction timing information is not available at the moment that the header data is written. Using the footer allows the server-side agent to write timing data at the footer of the page, by which time a fuller picture of business transaction timing may be available.

You can write the JS_FOOTER data variable into the footer of a web page using the following techniques:

• If you use automatic injection for the injecting into the head section, you automatically get injection into the footer as well.

• If you use manual injection for the head section, for applications built on Java platforms you can use assisted injection-using injection rules to inject into the footer. Or for applications built on Java servlet or ASP.NET platforms, you can use assisted injection-using attribute injection.

If you cannot add the JS_FOOTER variable to your page, the timing shown for correlated business transactions may be the average response time for that transaction rather than the real execution time for that specific page.

HttpOnly Flags and the JavaScript Agent

HttpOnly is a flag servers can set on cookies to prevent their contents from being accessed by JavaScript.  This is often done for session cookies to hide the session identifier, as a security measure.  But the JavaScript Agent needs to be able to read special cookies set by the AppDynamics server-side agent (all prefixed with ADRUM) in order to collect correlation information.  If HttpOnly is set on these cookies, no server-side correlation information can be transmitted.  Make sure that your server does not set the the HttpOnly flag on any cookies prefixed with ADRUM.