Table of Contents
Overview
A load balancer is a device that distributes network or application traffic across a number of servers. Load balancers are used to increase the capacity and reliability of applications.
When properly configured, F5 iRules utilize a scripting syntax that allows the load balancer to intercept, inspect, transform, and direct inbound or outbound application traffic.
In the event that the application's source is unable to be modified and all other forms of injection have failed or are not applicable (e.g., assisted injection through Java rules for a PHP-based application), clients with a F5 load balancer can request their network security team configure an iRule to intercept an application's response and inject HTML into the page source necessary for enabling EUM. This is similar to the format that manual injection uses, but HTML is inserted into the webserver's response rather than into the original source code.
For instructions on how to build, deploy, and test an iRule, we recommend consulting your F5 support team and network security team since they are most knowledgeable and equipped to handle such a request. From an AppDynanics perspective, you must be properly licensed for EUM and have End User Monitoring (EUM) enabled for an application in your AppDynamics Controller UI. Clients who have the limited option of injection via F5 iRules have seen success using a template similar to the iRule listed below.
Note: If you are using the 4.3.x EUM JavaScript Agent, click here for instructions.
Generic F5 iRule template (requires further customization)
when HTTP_REQUEST {
if { [HTTP::uri] contains "segments/in/uri" } {
set enableEum 1
HTTP::header remove "Accept-Encoding"
}
STREAM::disable
}
when HTTP_RESPONSE {
STREAM::disable
if { ( $enableEum == 1 ) && ( [HTTP::header "Content-Type"] starts_with "text/html" ) } {
set search "</title>"
set replace "</title>\
<script type='text/javascript' charset='UTF-8' src='//application.domain.com/adrum/adrum-config.js'></script>"
STREAM::expression {@${search}@${replace}@}
STREAM::enable
}
unset enableEum
unset search
unset replace
}
How to use this template
1) Matching Condition - The matching condition in your first "if statement."
Change the condition in the above template to match inbound traffic to your application. In the template, we match against segments in the application's URI. However, there are other properties that can be used (e.g., [HTTP::path], [HTTP::host], etc.).
[HTTP::uri] contains "segment/in/uri"
2) Compression - Does your application use compression?
If you are unsure if compression is being used, there is a simple Curl test to find out. The results will return one of three responses:
- "Content-Encoding: gzip"
- "Content-Encoding: deflate" or
- Nothing
If the first or second response comes back, that means the site is using compression. An empty response means that compression is not being used.
curl -sILH 'Accept-Encoding: gzip,deflate' <<URL>> | grep -i 'content-encoding'
Example:
curl -sILH 'Accept-Encoding: gzip,deflate' www.appdynamics.com | grep -i 'content-encoding'
Response:
content-encoding: gzip
If compression is being used, uncomment the following line from the template.
HTTP::header remove "Accept-Encoding"
If there isn't any compression, then keep the line commented out or remove it from the rule completely.
# HTTP::header remove "Accept-Encoding"
3) JavaScript Agent Config (adrum-config.js) - What is the JavaScript agent config file and where does it get hosted?
An agent config file (adrum-config.js) is injected directly into the page source. It is a small JavaScript file that contains the JavaScript Agent configuration options, such as the location of the adrum.js file, EUM application key, etc. The agent-config.js file is a self-hosted file.
<script type='text/javascript' charset='UTF-8' src='//application.domain.com/adrum/adrum-config.js'></script>
Before using the adrum-config.js file to initialize your JavaScript Agent configuration, you will need to update the file to match your EUM Application Key, hosted location of the JavaScript Agent files (adrum.js or adrum-latest.js), and the URL for the EUM Server (SaaS or On-Prem).
The adrum-config.js example below assumes you are using our EUM cloud to process the JavaScript Agent beacon data, as well as the latest JavaScript Agent hosted in our CDN. You will need to create a file similar to this and host it yourself. A customized version of this file can be downloaded from within your EUM Application's configuration as documented here.
window['adrum-start-time'] = new Date().getTime();
(function(config) {
config.appKey = 'EUM-APP-KEY';
config.adrumExtUrlHttp = 'http://cdn.appdynamics.com';
config.adrumExtUrlHttps = 'https://cdn.appdynamics.com';
config.beaconUrlHttp = 'http://col.eum-appdynamics.com';
config.beaconUrlHttps = 'https://col.eum-appdynamics.com';
config.xd = { enable: false };
config.spa = { "spa2": false };
}
)(window['adrum-config'] || (window['adrum-config'] = {}));
document.write(unescape('%3Cscript')
+ " src='//cdn.appdynamics.com/adrum/adrum-latest.js' "
+ " type='text/javascript' charset='UTF-8' "
+ unescape('%3E%3C/script%3E'));
4) JavaScript Agent Config Options – What is your application-specific configuration?
- EUM Application Key – What is your EUM Application Key as assigned in your Controller's UI?
This can be found by accessing your EUM Application Configuration via the controller UI. The key is typically eight letters long. Change the example key (EUM-APP-KEY) in the above template to your specific application key.
config.appKey = 'EUM-APP-KEY';
- JavaScript Agent Location - Where is the JavaScript agent being hosted?
If you intend to host the JavaScript agent file yourself, please update the source address for the adrum.js. Please see bolded lines in the example above for where to specify hosting location.
document.write(unescape('%3Cscript')
+ " src='//cdn.appdynamics.com/adrum/adrum-latest.js' "
+ " type='text/javascript' charset='UTF-8' "
+ unescape('%3E%3C/script%3E'));
- EUM Collector URL - Where should the agent send the beacon data?
If you are using an On-Prem EUM server, you will need to update the config.beaconUrlHttp and config.beaconUrlHttps above. For more information on how to find this URL, please refer to our documentation on manual injection found here.
config.beaconUrlHttp = 'http://col.eum-appdynamics.com';
config.beaconUrlHttps = 'https://col.eum-appdynamics.com';
-
JavaScript Agent Extension Location - Where should the agent download the adrum-ext.js file?
If you are hosting the JavaScript Agent extension file yourself, you will want to update the config.adrumExtUrlHttp and config.adrumExtUrlHttps above. For more information on how to find this URL, please refer to our documentation on manual injection found here.
config.adrumExtUrlHttp = 'http://cdn.appdynamics.com';
config.adrumExtUrlHttps = 'https://cdn.appdynamics.com';
- Cross-Domain Session Correlation - Do I want to monitor cross-domain sessions?
As described in our documentation here, cross-domain session correlation is disabled by default. If you wish to monitor sessions which span multiple domains, you will want to update config.xd in the template above.
config.xd = { enable: true };
- SPA2 Monoitoring - Do I want to enable SPA2 Monitoring?
As described in our documentation here, SPA2 Monitoring is disabled by default. If you wish to enable, you will want to update config.spa in the template above.
config.spa = { "spa2": true };
5) Other Points To Consider
- In some cases, the Stream profile must re-enable response re-chunking as documented in https://support.f5.com/csp/article/K6422.
- Although the above script template is typically successful, every client environment is different. Therefore, our team recommends that you consult a trained engineer responsible for managing your F5 load balancer. We also highly recommend testing in a sandbox or development environment before deploying any changes to your production environment.
Results
If properly configured, the iRule matches a condition for your application-specific traffic, the load balancer will inject the EUM-specific source via the adrum-config.js file into the response received by the browser. This will allow the Javascript Agent and the associated configurations to load in the browser, capture EUM data, and send the associated beacons back to the EUM Server.
<script type='text/javascript' charset='UTF-8' src='//application.domain.com/adrum/adrum-config.js'></script>
Sample Files (see attachments):
- adrum-config.js.txt
- iRule-template.txt
