Injection Overview

Web EUEM 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 EUEM 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 Web EUEM 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 Web EUEM 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 EUEM 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 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.

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 Web EUEM 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 End User Monitoring (EUEM) Compatibility  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 EUEM metrics after running load for a while, check the web page to confirm that the JavaScript Agent for EUEM is present in the page. If it is not, try injecting the script again.

If after two attempts you still do not see EUEM metrics, try one of the other injection schemes if they are available for your platform, or call AppDynamics Support.

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 manual and assisted injection using attribute injection, manually delete the JavaScript Agent for EUEM from your web pages or page templates.
• 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 must 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 is 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 is the average response time for that transaction rather than the real execution time for that specific page.

Learn More

• Manual Injection
• Automatic Injection
• Assisted Injection-Using Attribute Injection
• Assisted Injection-Using Injection Rules - Java Only