Advanced Browser Agent Configuration
You can modify the default monitoring to achieve the balance of visibility and performance that you require.
apmdevops102
You can modify the default monitoring to achieve the balance of visibility and performance that you require.
As an administrator, understand the Browser Agent cookies, and the business transaction properties and naming. You can also perform the optional configuration tasks.
Cookies
The Browser Agent uses the following cookies between the browser client and the application server. All the cookies are UTF-8 encoded.
Note:
For a list of supported browser platforms, see the Product Compatibility Matrix.Cookie | Description | Origin | Duration |
WMRUMC | Maintains the Browser Agent timing information for the current web page. | Browser | Browser session |
x-apm-brtm-bt-p | Maintains the browser type. | Browser | Browser session |
x-apm-brtm-bt-pv | Maintains the browser version. | Browser | Browser session |
x-apm-brtm-bt-url | Contains URL path information about the web page being monitored. | Browser | Browser session |
x-apm-brtm-geo | Maintains latitude and longitude of the browser client. This information is calculated only when geo-location is turned on. | Browser | Browser session |
x-apm-brtm-response-bt | Contains the Browser Agent business transaction context information for a Browser Agent request. | Application server | 30000 milliseconds |
x-apm-brtm-response-bt-< uniqueID > | Contains the Browser Agent business transaction context information for a Browser Agent AJAX request. The uniqueID in the name of the cookie is identical to the value set in the cookie x-apm-brtm-response-bt-id. | Browser | 30000 milliseconds |
x-apm-brtm-response-bt-id | Contains a unique ID to identify a Browser Agent AJAX request. | Browser | 2000 milliseconds |
x-apm-brtm-response-bt-page | Maintains the Browser Agent business transaction context information for the current web page. | Application server | 30000 milliseconds |
Configure Agents for Monitoring and Metric Collection
You can configure the Browser Agent properties for monitoring and metric collection unless you want to use the default values.
Follow these steps:
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Go to this section:############################################### Browser Agent Business Transaction Monitoring properties##############################################
- Enable the Browser Agent business transaction monitoring properties by uncommenting them or adding them, and specifying property values.
- Save and close the file.
- Restart the application if a property change requires it.
Browser Agent Business Transaction Monitoring Properties
The IntroscopeAgent.profile file includes the Browser Agent properties for monitoring and metric collection.
The Browser Agent supports the ASCII character set for displaying metrics. The exception is the hash (#) character as a fragment identifier, which is not part of the URL and is not interpreted on the server. Do not specify a fragment identifier in the exclude or include list. If the page URL does not have a business transaction match, the Browser Agent defaults to the URL metric. The Browser Agent supports URLs as follows:
- Server/Port (metric node)
- URL path (metric node) -- The Browser Agent does not add the query parameters.
For example:
Metric Path > <
Agent_Node
> | Business Segment | <Server
>/<Port
> | <URL_Path
> | <Browser_Metrics
> … The following properties show the default values. Some properties are deployed when you save the IntroscopeAgent.profile configuration file. You do not need to restart the application or application servers for a change to take effect.
introscope.agent.browseragent.ajaxMetricsEnabled
Toggles the capture of AJAX metrics.
Values: TRUE/FALSE
Default: TRUE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent is reporting AJAX metrics.
introscope.agent.browseragent.ajaxMetricsThreshold
Creates the metrics for the AJAX events that are greater than the defined threshold.
Values: Integer
Range: Equal to or greater than 0 milliseconds
Default: 100
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. The "Total Resource Load Time" for an AJAX call in milliseconds must at least meet this threshold for the Browser Agent to report it.
introscope.agent.browseragent.browserLoggingEnabled
Toggles the logging of messages in the browser console.
Values: TRUE/FALSE
Default: FALSE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent browser console logging is turned on or off.
introscope.agent.browseragent.checkHeadFilterPresence.enabled
Sets a flag back to the browser to send browser transaction traces where the correlation ID is set correctly. This action occurs when the Java agent is executing a transaction trace session by opening up the transaction trace session window.
Values: TRUE/FALSE
Default: TRUE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property does not require you to restart the application or application server.
Sustainability Metric: No
introscope.agent.browseragent.checkTailFilterPresence.enabled
Sets a flag back to the browser to send browser transaction traces where the correlation ID is set correctly. This action occurs when the Java agent is executing a transaction trace session and it is using a timing threshold session.
Values: TRUE/FALSE
Default: TRUE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property does not require you to restart the application or application server.
Sustainability Metric: No
introscope.agent.browseragent.contentencoding.enabled
Enables content encoding support property for the browser agent.
Values: TRUE/FALSE
Default: FALSE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent reports metrics for pages with content encoding enabled. If this value is FALSE, then the Browser Agent does not monitor requests whose response content is encoded, for example, gzip.
introscope.agent.browseragent.enabled
Agent: Controls the overall functionality of the Browser Agent for the agent. Creates metrics, transaction events, business transaction decoration, and insertion of JavaScript code.
Browser: Controls the overall functionality of the Browser Agent for the browser. Enables specific browser functionality.
Values: TRUE/FALSE
Default: FALSE
Visibility: IntroscopeAgent.profile file
Configuration Type: On the browser does not require you to restart the application or application server. On the agent does require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent feature is turned on or off. By default, the Browser Agent is turned off in the Java Agent.
introscope.agent.browseragent.excludeURLList
Excludes the full URLs in the excludeURLList from the Browser Agent monitoring. When you do not specify values, the Browser Agent only uses the includeURLList.
Notes:
- When matching is required on special characters, escape these characters with double backslashes: ["http://host:port/path1", ".*/path2", “.*my%20page\\.html\\?a1=b”]. A special character can be a question mark, dot, star, plus, and so on (those characters that have special meaning in regular expressions).
- All regular expressions must be specified as absolute patterns that span the entire URL. Examples: Exclude pages whose URL path ends with “myCustomPage.jsp” should be specified as [“.*myCustomPage.jsp”], instead of [“myCustomPage.jsp”]. Exclude pages whose URL path contains “custom” should be specified as [“.*custom.*”].
Values: String. Regular expression string. Regular expressions are supported for full URLs including protocol, host, port, pathname, and / or query string matching. We recommend that you follow the full URL that you obtain from the browser. When the URL is encoded, place the encoded URL in this list.
Default: []
Visibility: IntroscopeAgent.profile file
Configuration Type: This agent-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric displays the current value of this agent property.
introscope.agent.browseragent.geolocation.enabled
Toggles the reporting of geographic coordinates during a transaction trace.
If TRUE, this property provides a confirmation pop-up to allow or deny geolocation.
For the calls other than for AJAX, geolocation requires at least one callback to show performance data. The Browser Agent uses the Geolocation API for the browser. This API uses callbacks. A location for a user is not ready at the time it is requested. Instead, the location becomes available asynchronously and handled with callback functions. This behavior affects the Browser Agent users because geolocation is not available during a page load or page refresh.
Values: TRUE/FALSE
Default: FALSE
Visibility: IntroscopeAgent.profile file
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether geo-location is reported in the Browser Agent transaction trace components.
introscope.agent.browseragent.geolocation.highAccuracyEnabled
Toggles the mode of calculation of geographic coordinates.
Values: TRUE/FALSE
Default: FALSE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent considers using the high accuracy mode while it calculates the geo-location of its transactions.
introscope.agent.browseragent.geolocation.maximumAge
Specifies the maximum amount of time between successive geolocation calculations that the browser performs.
Values: Integer
Range: 5000 - 30000 milliseconds
Default: 10000
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the interval in milliseconds in which the Browser Agent geo-location calculation is repeated.
introscope.agent.browseragent.geolocation.timeout
Specifies the period that the browser waits for the geolocation calculation to succeed before it invokes an error.
Values: Integer
Range: 5000 - 10000 milliseconds
Default: 5000
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the maximum amount of time in milliseconds the Browser Agent waits for the geo-location calculation to complete.
introscope.agent.browseragent.includeURLList
Monitors only the URLs provided in the includeURLList.
Notes:
- If includeURLList and excludeURLList are both specified, the includeURLList is applied to the URL set to all URL requests. Then, the excludeURLList is applied to the result of that set. For example, if includeURLList=[“.*/mypath1/.*”] and excludeURLList=[“http://.*/mypath1/mypage.html”], then http://host:port/mypath1/mypage.html or http://host:port/mypath2/mypage.html are excluded, but http://host:port/mypath1/otherpage.html is not excluded.
- All regular expressions must be specified as absolute patterns that span the entire URL. Examples: Include only pages whose URL path ends with “myCustomPage.jsp” should be specified as [“.*myCustomPage.jsp”], instead of [“myCustomPage.jsp”]. Include only pages whose URL path contains “custom” should be specified as [“.*custom.*”].
Values: Regular expression string. Regular expressions are supported for full URLs including protocol, host, port, pathname, and / or query string matching. We recommend that you follow the full URL which you obtain from the browser. When the event that the URL is encoded, place the encoded URL in this list.
Note:
When matching is required on special characters, escape these characters with double backslashes: ["http://host:port/path1", ".*/path2", “.*my%20page\\.html\\?a1=b”]. A special character can be a question mark, dot, star, plus, and so on (those characters that have special meaning in regular expressions).Default: []
Visibility: IntroscopeAgent.profile file
Configuration Type: This agent-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric displays the current value of this agent property.
introscope.agent.browseragent.instrumentclass.autoskip.depth
Specifies the skip level to instrument the class for the browser agent. This property works when the introscope.agent.browseragent.contentencoding.enabled property is set to true. For example: if introscope.agent.browseragent.contentencoding.enabled property is enabled and introscope.agent.browseragent.instrumentclass.autoskip.depth is set to 2, the agent skips two times to run the browser agent for instrumented class. This behavior occurs if the current instrumentation is not at a servlet level. If the current instrumentation is in the servlet level, the browser agent continues to run.
Values: Integer
Range: 1 - 3
Default: 1
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property does not require you to restart the application or application server.
Sustainability Metric: No
introscope.agent.browseragent.jsExtensionLocation
Specifies the path of where the apmbrowseragentextensibility.js file is located or loaded from. Use forward slashes in the path. The apmbrowseragentextensibility.js file is loaded from the BrowserAgentExt.jar by default and secondarily from the <
Agent_Home
>/examples/APM/BrowserAgent/js directory.Values: String, the apmbrowseragentextensibility.js location
Default: BLANK
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: No
introscope.agent.browseragent.jsFunctionMetricsEnabled
Toggles the capture of JavaScript function metrics.
Values: TRUE/FALSE
Default: FALSE
Visibility: IntroscopeAgent.profile file
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent reports JavaScript function metrics.
introscope.agent.browseragent.jsFunctionMetricsThreshold
Creates the metrics for JavaScript function events that are greater than the threshold defined.
Values: Integer
Range: Equal to or greater than 0 milliseconds
Default: 100
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the threshold value for Browser Agent JavaScript function metrics. The "Average Execution Time" for JavaScript functions in milliseconds must at least meet this threshold for the Browser Agent to report it.
introscope.agent.browseragent.metricFrequency
Specifies the interval in which the Browser Agent metrics are dispatched to the agent from the browser. The default 0-ms value means that browser-specific requests to send metric data to the agent occur immediately after the application request is made. A frequency increase can cause batch mode to occur where multiple browser metric sets from different application requests are sent back to the agent.
Note:
Page metrics do not use this property. Page metrics are always sent when the page load timing is ready.Values: Integer
Range: Equal to or greater than 0 milliseconds
Default: 0
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the interval in milliseconds in which the Browser Agent metrics are dispatched from the browser to the Java Agent.
introscope.agent.browseragent.pageLoadMetricsEnabled
Toggles the capture of page metrics.
Values: TRUE/FALSE
Default: TRUE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the Browser Agent reports page load metrics.
introscope.agent.browseragent.pageLoadMetricsThreshold
Create the metrics for page events that are greater than the threshold defined.
Values: Integer
Range: Equal to or greater than 0 milliseconds
Default: 100
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the threshold value for Browser Agent page load metrics. The "Average Page Load Complete Time" in milliseconds must at least meet this threshold for it to be reported by the Browser Agent.
introscope.agent.browseragent.resource.count
Sustainability Metric: Yes. This metric indicates the current number of unique resources (for example, HTTP Requests) being monitored by the Browser Agent.
introscope.agent.browseragent.resourceLimit
Limits the number of resources that are defined per agent for all resources from a web browser. This property is set when the Browser Agent is enabled. When the clamp is reached, no more metrics are created for new resources.
A Uniform Resource Identifier (URI/URL) identifies an information resource. A resource can be a web page, image, video, or other piece of content. Numerous resource paths can appear in the Metric Browser tree. For example, resources can include business transactions, URL metrics, AJAX metrics, JavaScript function metrics, and so on.
Values: Integer
Range: 0 - 200
Default: 100
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the maximum number of unique resources (for example, HTTP Requests) to be monitored by the Browser Agent per Java Agent.
introscope.agent.browseragent.snippet.maxSearchingLength
Checks for the end of the closing </head> tag to insert the snippet.js file in the page dynamically from the Java Agent. If no head tag exists in the page, the agent checks for the <body> tag (starting body tag) instead. After the agent finds the </head> tag or <body> tag, the agent stops searching. If the </head> tag is found, snippet code is inserted before </head> tag. If the <body> tag is found, the agent inserts snippet code and <head> tag before <body> tag.
Determines the number of bytes from the start of the browser page to the end of the page. If you set the value to larger number, then for every request the Java agent loads that number of bytes into memory to perform the search for the </head> tag.
Values: Integer
Range: Equal to or greater than 0 bytes
Default: 32768
Visibility: IntroscopeAgent.profile file
Configuration Type: This agent-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the maximum number of bytes to search from the beginning of the HTML response to find the appropriate place where JS snippet is inserted.
introscope.agent.browseragent.snippet.maxSearchingReached.count
Sustainability Metric: Yes. Indicates the number of requests for which the appropriate place to insert the JS snippet exceeds the value set in introscope.agent.browseragent.snippet.maxSearchingLength.
introscope.agent.browseragent.snippetInsertionEnabled
Inserts the snippet.js file into the browser page using the APM agent. If FALSE, the Java agent does not dynamically insert the snippet.js into the response back to the Browser Agent. Manually insert the snippet.js (<
Agent_Home
>/examples/APM/BrowserAgent/js) into the <head> tags of the HTML page.Values: TRUE/FALSE
Default: TRUE
Visibility: IntroscopeAgent.profile file
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether automatic JavaScript snippet insertion is turned on or off. By default, automatic JavaScript snippet insertion is TRUE.
introscope.agent.browseragent.snippetLocation
Specifies the path of where the snippet.js file is located or loaded from. This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting. The snippet.js file is loaded from the BrowserAgentExt.jar by default and secondarily from the <
Agent_Home
>/examples/APM/BrowserAgent/js directory.Values: String, the path of the snippet.js location
Default: BLANK
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: No
introscope.agent.browseragent.sustainabilityMetrics.enabled
Toggles the creation of the Browser Agent-related sustainability metrics.
Values: TRUE/FALSE
Default: TRUE
Visibility: IntroscopeAgent.profile file
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: No
introscope.agent.browseragent.throttleResponse.count
Sustainability Metric: Yes. This metric indicates the total number of requests that the Browser Agent serves within the 15-second Java Agent interval.
introscope.agent.browseragent.throttleResponseLimit
Throttles the number of requests that can be sent in a 15-second interval. This property includes only the application-specific requests that the Browser Agent tracer computes. This property does not include the wily-specific requests that send browser-specific metric data.
Values: Integer
Range: 0 - 5000
Default: 1000
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property requires you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates the maximum number of requests to be served by the Browser Agent within the 15-second Java Agent interval.
introscope.agent.browseragent.unsupportedBrowsers.count
Sustainability Metric: Yes. This metric indicates the number of requests originating from browsers that are not compatible with the Browser Agent.
introscope.agent.browseragent.urlMetricOff
Disables the reporting of URL metrics and transaction trace events. URL metrics (not a business transaction) are not created when this property is set to TRUE.
Values: TRUE/FALSE
Default: FALSE
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This browser-specific property does not require you to restart the application or application server.
Sustainability Metric: Yes. This metric indicates whether the business transaction context Browser Agent metrics are turned on or off. By default, nonbusiness transaction context metrics are TRUE.
introscope.agent.browseragent.wilyURL
Specifies the full URL path for sending the Browser Agent browser metrics. This property uses the Java agent with the Browser Agent enabled.
Values: String, the path for the application that the Java agent instruments. Enclose the path with quotes.
Default: BLANK
Visibility: This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
Configuration Type: This agent-specific property does not require you to restart the application or application server. You might not want to send the Browser Agent browser metrics back to the same agent URL that is instrumenting the application. You can specify a different URL to the same application or a URL to another application server to send this data.
- If you are using a data source on the application other than another agent, the data has a specific post parameter specification.
- If you are using another agent, add the proper query string to the URL: (?WilyCmd=cmdMetrics)
In certain cases, the browser metric data is transferred using a post parameter map:
- The browser metric data includes: W3C and AJAX function response time calls. The metrics are under the Business Segment node.
- Transaction trace data (required)startTime: Start time of the transaction. The value is computed from the agent, which is the master clock format.duration: Computed from the browser such as page load time (Page Load), total resource time (asynchronous)
- Transaction Trace data (optional)CorBrowsGUID: This data is required to correlate the Browser Transaction Trace with the Introscope transaction trace.Custom Messages (exceptions, and so on)Geography Coordinates (longitude and latitude): This data is rendered when the introscope.agent.browseragent.geoLocaton.enabled property is TRUE. By default if geoLocation is not enabled, the coordinates are -255,-255.If TRUE, this property provides a confirmation pop-up to allow or deny geolocation.
- The parameter name value simple key tags each data set (metrics, transactional trace). This data is required.
Sustainability Metric: Yes. This metric indicates the URL to which the Browser Agent metrics are dispatched from the browser. By default, the Browser Agent dispatches all of its metrics with the URL of the current monitored webpage.
Business Transaction Naming
The Browser Agent leverages the business transaction matching logic that the Java agent uses, and decorates the business transaction with the browser type. If a business transaction has not been defined for the given request that the Java agent monitors, the Browser Agent will not have a business transaction to decorate as metrics. (When the Browser Agent does not have a business transaction to match, it uses URL metrics.)
The Browser Agent uses the following request to the application server:
- Application Response sent from the Application Server to the Browser ClientWhen the Browser Agent is enabled, the application response inserts the JavaScript snippet file into the browser page and also sends the following cookies back to the browser client:
- c: flag to indicate that a transaction trace should be created for the browser request
- CorBrowsGUID: ID to correlate the browser request with the application request (useful when a browser and application transaction traces are created)
- startTime: start time of the application request
- bs: Business Service that the Java agent identifies
- bt: Business Transaction that the Java agent identifies
- btc: Business Transaction Component that the Java agent identifies
The following cookie keys provide the Browser Agent context on the APM transaction that is being monitored so that browser metrics and transaction trace events have the context of the APM transaction:
- Application Request from the Browser Client to the Application ServerWhen the Browser Agent is enabled, the browser client sends back request cookies to the application server that decorates the business transaction:
- x-apm-brtm-bt-p: Platform type (Firefox, IE, Safari, Chrome)
- x-apm-brtm-bt-pv: Platform version (for the respective browser)
- Browser Client (special wily request) to the Application ServerThe Browser Agent sends a special wily type of request (not an application request) back to the application server. This request contains browser metrics and transaction trace events for the browser data. Data is packaged in the post parameter object.The Browser Agent also sends a wily type of request (not an application request) back to the application server to download the full apmbrowseragent.js file to monitor the browser.In both cases, the wily request does not implement the application stack.The Browser Agent and End-user Endpoints Monitoring impact the CEM integration. The Browser Agent and End-user Endpoints Monitoring decorate business transaction names with “via <Browser Type>.” This name does not match the CEM business transaction definition. When both CA CEM and the Browser Agent are monitoring the same business transactions and a CEM incident triggers a transaction trace, transactions that the Browser Agent monitors are not automatically traced. For more information about CEM and the Browser Agent, see TEC1845554.
Deploy the Browser Agent JavaScript to a Different Location
You can deploy the Browser Agent to a new location within the application or on another server. The Browser Agent JavaScript files, snippet.js, apmbrowseragent.js, and apmbrowseragentextensibility.js can be deployed elsewhere. By default, these files are read from the BrowserAgentExt.jar file in the <
Agent_Home
>/core/ext directory. We highly recommend that you always use the JavaScript snippet to download the Browser Agent JavaScript: apmbrowseragent.js.
To deploy the snippet.js file:
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Add the following property:introscope.agent.browseragent.snippetLocation=<location of snippet.js>Example:introscope.agent.browseragent.snippetLocation=c:/<appserver>/wily/core/ext/snippet.js
- Save and close the file.
To deploy the apmbrowseragent.js file:
We recommend that you use the default settings and do not configure the location of the apmbrowseragent.js file.
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Add the following property:Introscope.agent.browseragent.snippetLocation=<location of snippet.js>Example:introscope.agent.browseragent.snippetLocation=c:/<appserver>/wily/core/ext/snippet.js
- Save and close the file.
- Go to <Agent_Home>/core/ext and, from the BrowserAgentExt.jar, copy the apmbrowseragent.js file to the new deployment location.
- Open the snippet.js file in a text editor and locate this line:var BrowserAgentInstrumentationLocation = window.location.protocol + "//" + window.location.host + window.location.pathname;Change the line to:var BrowserAgentInstrumentationLocation = "http://localhost:9091/test/js/brtmtest.js";When you change this line, you change the Browser Agent JavaScript. The server Browser Agent configuration and extensibility JavaScript source code is removed. Manually add the JavaScript code into the new apmbrowseragent.js. The reason is when you use the default snippet code, it makes a request to the server for the client JavaScript file. This request gathers the Browser Agent configuration property, basic apmbrowseragent.js, and apmbrowseragentextensibility.js into one JavaScript file, and sends the request back to the client.
- Save and close the file.
To deploy the apmbrowseragentextensibility.js file:
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Add the following property:introscope.agent.browseragent.jsExtensionLocation=<deployment_location>Example:introscope.agent.browseragent.jsExtensionLocation=C:\apache-tomcat-8.0.33\<Agent_Home>\APM\browseragent\js\apmbrowseragentextensibility.js
- Save and close the file.
Filter Browser Pages from the Browser Agent
In some cases, you might want to filter web pages from the Browser Agent. For example, certain websites require user authentication before proceeding further:
- In certain cases, the application always caches the last recent page. When the authentication is complete, the browser redirects to the last recent page.
- The Browser Agent request (sends browser metrics) is the last page that is requested because it was the last page to reach the server. In this scenario, you see a blank page because the wily request renders an empty response. To prevent this wily request page from rendering after authentication is complete, do the following steps:
- Exclude the Login/Authentication page from the Browser Agent: avoids the Browser Agent requests to send any browser metrics until the authentication is complete.
- You can also update the wilyURL property to a static URL that does not get cached for redirection after the authentication is complete.
Follow these steps:
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Go to this section:############################################### Browser Agent Business Transaction Monitoring properties##############################################
- Enable the following properties by uncommenting them and specifying property values. If the include/exclude properties do not achieve expected results, try using the wilyURL property.
- introscope.agent.browseragent.includeURLList: Monitors only the web pages that are in the include list. If the exclude list has web pages, the exclude list takes precedence over the include list but does not override it.
- introscope.agent.browseragent.excludeURLlist: Excludes the monitoring of web pages in the exclude list.
- introscope.agent.browseragent.wilyURL: The browser metrics are sent from the Browser Agent back to the Browser Agent extension. By default, the browser wily request uses the URL that is being monitored with an extra query string “?WilyCMD=cmdMetrics.” However, with the wilyURL property, you can use a static URL to send all browser metrics to the Browser Agent extension.
- Save and close the file.
Filter Customized Servlets on the Application Server
The Browser Agent dynamically inserts the JavaScript snippet file in the application ServletResponse object before the response is sent to the browser client. This solution is generic and is compatible with most Java application servers. However, cases can occur where the dynamic insertion is not supported. For example, the ServletResponse object that the application stack uses gets modified by the application by casting it to another type of ServletResponse object. This behavior occurs after the Browser Agent executes the JavaScript insertion into the response object.
This case can occur for application server asynchronous requests/responses. For example, Oracle Server Bus (OSB) on WebLogic can implement this approach by using a FutureResponseServlet object and changing the cast of the ServletResponse during the application stack. If this issue occurs, the servlet class in question must be skipped. Use the following procedure for OSB on WebLogic, which is already located in the browseragent.pbd file, as an example.
Follow these steps:
- Go to <Agent_Home>/core/config and open the browseragent.pbd file in a text editor.
- Add and enable the following trace directive skips:SkipClassForFlag: weblogic.servlet.FutureResponseServlet BRTM_HttpServletTracing=TRUESkipClassForFlag: weblogic.servlet.FutureResponseServlet BRTM_HttpServletTypeSpecificServiceTracing=TRUE
- Save and close the file.
- Restart the application server for the agent.
Skip Filters in gzip Compressed Responses
gzip is a file format that compresses and decompresses files. You can configure the Browser Agent to skip filters in gzip-compressed responses.
Follow these steps:
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Go to this section:############################################### Browser Agent Business Transaction Monitoring properties##############################################
- Enable the following properties by uncommenting them and specifying property values:
- introscope.agent.browseragent.contentencoding.enabled: Enables content encoding support property for the browser agent.Note:This property is not included in the IntroscopeAgent.profile file; add it manually to change the setting.
- introscope.agent.browseragent.instrumentclass.autoskip.depth: Specifies the skip level to instrument the class for the browser agent.
- Save and close the file.
- (WebSphere Application Server 7 only) Go to <Agent_Home>/core/config and open the browseragent.pbd file in a text editor.
- Turn off the following trace directive:TurnOff: BRTM_WASStaticServletTracing
- Save and close the file.
- Restart the application server for the agent.
You can change the Browser Agent instrumentation from the first filter to the filter after the gzip filter. This instrumentation uses the value of introscope.agent.browseragent.instrumentclass.autoskip.depth property. Also, the Browser Agent supports multiple re-entrances to wrap a response. When you want to wrap the response again after some classes, you can configure the BrtmResetTracer in the browseragent.pbd file.
Follow these steps:
- Go to <Agent_Home>/core/config and open the browseragent.pbd file in a text editor.
- Add and enable the following trace directive skips:######################################################## BrtmResetTracer######################################################SetFlag: BRTM_SELFRESET_TracingTurnOn: BRTM_SELFRESET_TracingSetFlag: BRTM_RESET_TracingIdentifyTwoFlagIntersectionAsAggregateFlag: BRTMTracing BRTM_SELFRESET_Tracing BRTM_RESET_Tracing SetTracerClassMapping: BrtmResetTracer com.wily.introscope.agent.brtm.trace.BrtmResetTracer com.wily.introscope.probebuilder.validate.ResourceNameValidatorSetTracerOrdering: BrtmResetTracer -10000000IdentifyClassAs: org.eclipse.jetty.server.Dispatcher BRTM_RESET_TracingTraceOneMethodWithParametersIfFlagged: BRTM_RESET_Tracing forward(Ljavax/servlet/ServletRequest;Ljavax/servlet/ServletResponse;Ljavax/servlet/DispatcherType;)V BrtmResetTracer Servlets
- Save and close the file.
- Restart the application server for the agent.
Add the JavaScript Snippet Manually to Web Pages
You can manually add the JavaScript snippet (snippet.js) to web pages.
We highly recommend that you always use the JavaScript snippet to download the Browser Agent JavaScript: apmbrowseragent.js.
Follow these steps:
- Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
- Go to this section:###############################################Browser Agent Business Transaction Monitoring properties
- Change the following property to FALSE:introscope.agent.browseragent.snippetInsertionEnabled=FALSE
- Save and close the file.
- Copy the contents of snippet.js under <Agent_Home>/examples/APM/BrowserAgent/js and open each HTML page. Paste the snippet.js content before the </head> tag and after other scripts.
- Restart the application.