apm_9.5--browser response time monitor guide
TRANSCRIPT
Configuration Guide Release 9.5
CA Application Performance Management for Browser Response Time Monitor
This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors.
Copyright © 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
CA Technologies Product References
This document references the following CA Technologies products and features:
■ CA Application Performance Management (CA APM)
■ CA Application Performance Management ChangeDetector (CA APM ChangeDetector)
■ CA Application Performance Management ErrorDetector (CA APM ErrorDetector)
■ CA Application Performance Management for CA Database Performance (CA APM for CA Database Performance)
■ CA Application Performance Management for CA SiteMinder® (CA APM for CA SiteMinder®)
■ CA Application Performance Management for CA SiteMinder® Application Server Agents (CA APM for CA SiteMinder® ASA)
■ CA Application Performance Management for IBM CICS Transaction Gateway (CA APM for IBM CICS Transaction Gateway)
■ CA Application Performance Management for IBM WebSphere Application Server (CA APM for IBM WebSphere Application Server)
■ CA Application Performance Management for IBM WebSphere Distributed Environments (CA APM for IBM WebSphere Distributed Environments)
■ CA Application Performance Management for IBM WebSphere MQ (CA APM for IBM WebSphere MQ)
■ CA Application Performance Management for IBM WebSphere Portal (CA APM for IBM WebSphere Portal)
■ CA Application Performance Management for IBM WebSphere Process Server (CA APM for IBM WebSphere Process Server)
■ CA Application Performance Management for IBM z/OS® (CA APM for IBM z/OS®)
■ CA Application Performance Management for Microsoft SharePoint (CA APM for Microsoft SharePoint)
■ CA Application Performance Management for Oracle Databases (CA APM for Oracle Databases)
■ CA Application Performance Management for Oracle Service Bus (CA APM for Oracle Service Bus)
■ CA Application Performance Management for Oracle WebLogic Portal (CA APM for Oracle WebLogic Portal)
■ CA Application Performance Management for Oracle WebLogic Server (CA APM for Oracle WebLogic Server)
■ CA Application Performance Management for SOA (CA APM for SOA)
■ CA Application Performance Management for TIBCO BusinessWorks (CA APM for TIBCO BusinessWorks)
■ CA Application Performance Management for TIBCO Enterprise Message Service (CA APM for TIBCO Enterprise Message Service)
■ CA Application Performance Management for Web Servers (CA APM for Web Servers)
■ CA Application Performance Management for webMethods Broker (CA APM for webMethods Broker)
■ CA Application Performance Management for webMethods Integration Server (CA APM for webMethods Integration Server)
■ CA Application Performance Management Integration for CA CMDB (CA APM Integration for CA CMDB)
■ CA Application Performance Management Integration for CA NSM (CA APM Integration for CA NSM)
■ CA Application Performance Management LeakHunter (CA APM LeakHunter)
■ CA Application Performance Management Transaction Generator (CA APM TG)
■ CA Cross-Enterprise Application Performance Management
■ CA Customer Experience Manager (CA CEM)
■ CA Embedded Entitlements Manager (CA EEM)
■ CA eHealth® Performance Manager (CA eHealth)
■ CA Insight™ Database Performance Monitor for DB2 for z/OS®
■ CA Introscope®
■ CA SiteMinder®
■ CA Spectrum® Infrastructure Manager (CA Spectrum)
■ CA SYSVIEW® Performance Management (CA SYSVIEW)
Contact CA Technologies
Contact CA Support
For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources:
■ Online and telephone contact information for technical assistance and customer services
■ Information about user communities and forums
■ Product and documentation downloads
■ CA Support policies and guidelines
■ Other helpful resources appropriate for your product
Providing Feedback About Product Documentation
If you have comments or questions about CA Technologies product documentation, you can send a message to [email protected].
To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at http://ca.com/docs.
Contents 7
Contents
Chapter 1: Preparation 9
Features and Requirements ....................................................................................................................................... 10
Implementation .......................................................................................................................................................... 11
Browser Considerations ............................................................................................................................................. 13
Application Considerations and Limitations ............................................................................................................... 15
Chapter 2: How to Install and Configure CA BRTM 17
How to Install and Configure CA BRTM ...................................................................................................................... 18
Install CA BRTM ................................................................................................................................................... 20
Make the CA BRTM Filter Available to Your Application..................................................................................... 22
Configure Agents for Metric Collection............................................................................................................... 23
Edit the web.xml ................................................................................................................................................. 26
Add the JavaScript Snippet to Web Pages .......................................................................................................... 27
(Optional) Deploy CA BRTM JavaScript to a Different Location .......................................................................... 28
Verify that Metrics Work..................................................................................................................................... 28
Chapter 3: How to Uninstall CA BRTM 29
Appendix A: Troubleshooting 31
Metrics Are Not Appearing in User Interface ............................................................................................................. 31
Nodes Are Not Displaying........................................................................................................................................... 33
Metric Counts Are Higher Than Expected .................................................................................................................. 33
JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying .............................................................. 34
Average Round Trip and Average Browser Render Time Metrics Not Displaying ...................................................... 34
Include or Exclude URLs Are Not Filtering Correctly .................................................................................................. 34
All WebLogic 10.3 Applications Are Instrumented ..................................................................................................... 35
Chapter 1: Preparation 9
Chapter 1: Preparation
This guide describes how to install and configure CA Application Monitoring for Browser Response Time Monitor.
This section contains the following topics:
Features and Requirements (see page 10) Implementation (see page 11) Browser Considerations (see page 13) Application Considerations and Limitations (see page 15)
Features and Requirements
10 Configuration Guide
Features and Requirements
Review this section for features and requirements for implementing CA BRTM.
Features
CA APM for Browser Response Time Monitor (CA BRTM) lets you monitor web page load performance metrics in the Webview and Workstation user interfaces. You can pinpoint the performance degradation to the browser, network, or the application server.
CA BRTM supports the following features in this release:
■ Manual and automatic insertion of the CA BRTM filter and JavaScript snippet
■ Browser web timings using the web timing API or without (for older browsers)
■ Metric aggregation by URL group
■ Control of instrumented pages using excludeList and includeList agent properties
Requirements
CA BRTM requires:
■ A licensed CA APM implementation with Java agents configured for applications.
■ Web pages that are built with the content type text/HTML, and are uncompressed and unencrypted.
See the APM Compatibility Guide on Customer Support Online for the supported platforms and other requirements.
The CA BRTM Package
The CA BRTM package includes:
■ CA BRTM dashboards and typeviews for viewing metrics in the Webview and Workstation.
■ CA BRTM agent extension – includes JavaScript for requesting browser metrics, and a JavaScript snippet that requests the JavaScript.
■ CA BRTM servlet filters – filters for CA BRTM requests and extracts metrics.
Implementation
Chapter 1: Preparation 11
Implementation
To understand metric collection, review this section.
How CA BRTM Metrics Are Collected
The high-level steps to collect the CA BRTM metrics are:
1. The monitored application is configured with a CA BRTM filter.
2. The monitored application web pages are automatically configured with the CA BRTM JavaScript snippet (default)
3. The web pages with the JavaScript snippet are sent to the browser.
4. The browser loads the pages.
5. The browser loads the CA BRTM JavaScript.
6. The JavaScript sends performance metrics to the application.
7. The CA BRTM filter and the APM agent intercept the metrics and sends them to the Enterprise Manager.
How CA BRTM Implements Browser Response Timings
When available, CA BRTM implements the W3C Navigation Timing API for browser response timings. Many browsers support the web timing API; here are a few:
■ Microsoft Internet Explorer, version 9 and above
■ Firefox, version 7 and above
■ Chrome
Metric Calculations Using Web Timing API
The following table describes how metrics are calculated for browsers that support the web timing API.
Metric Description Metric Calculation
Average Browser Render Time (ms)
The time for the browser to parse the page and load all components.
loadEventStart time – domLoading time
Average Round Trip Time (ms)
The time when the browser first requests a page, until the entire page response is received.
responseEnd time – requestStart time
Implementation
12 Configuration Guide
Metric Description Metric Calculation
Average DOM Construction Time (ms)
The time from navigation start to when the browser constructs the document object model (DOM).
Note: This time is not when all objects in the DOM are retrieved and loaded.
domContentLoaded time – navigationStart time
Average Page Load Complete Time (ms)
The time from navigation start to when the browser loads all components and the page is complete.
loadEventStart time – navigationStart time
Average Previous Page Unload Time (ms)
The time to unload the previously displayed page. If there is no page to unload (for example when a browser session is started), no value is available.
unloadEnd time – navigationStart time
Metric Calculations Using No Web Timing API
The following table describes how metrics are calculated for browsers that do not support the web timing API.
Metric Description Metric Calculation
Average DOM Construction Time (ms)
The time from navigation start to when the browser constructs the document object model (DOM).
Note: This time is not when all objects in the DOM are retrieved and loaded.
domcontentloaded event time – beforeunload event time
Average Page Load Complete Time (ms)
The time from navigation start to when the browser loads all components and the page is complete.
load event time – beforeunload event time
Average Previous Page Unload Time (ms)
The time to unload the previously displayed page. If there is no page to unload (for example when a browser session is started), no value is available.
unload event time – beforeunload event time
Browser Considerations
Chapter 1: Preparation 13
Browser Considerations
Review browser limitations and best practices that can affect metric generation.
Limitations of Older Browsers
For older browsers that do not support the web timing API, standard browser events are used to calculate timings. All calculations are relative to the navigation start time. The navigation start time begins when the user does any of the following tasks:
■ Clicks a link
■ Enters a URL in the address bar
■ Selects a bookmark
Understand the limitations when using older browsers that do not support the web timing API.
Topic What You Should Know
Metrics are not produced for an initial page
Because the navigation start time is not available, the beforeUnload event time is used. For an initial page, there is no associated previous page unload so no metrics are produced. Timings are available only when moving from one instrumented page to another.
Metrics reported only for instrumented pages
A session cookie is used to pass the beforeUnload and unload event times when navigating from one web page to the next. Inaccurate timing are produced when:
■ Not all application pages are instrumented.
■ The user navigates to a noninstrumented application and back to the instrumented application.
To prevent inaccurate metrics, the CA BRTM JavaScript reports metrics only when navigating between instrumented pages using links. Timings are not produced for browser refreshes or navigation by bookmarks.
Page Load Complete Time is based on the actual load event
The page load complete time is when the actual load event occurs. If a page load blocks waiting for user input, this time is included in the Page Load Complete time.
Browser Considerations
14 Configuration Guide
Limitations of New Browsers that Support the Web Timing API
Some newer browsers have these limitations:
■ For an initial page, there is no associated previous page unload
■ If a page load blocks waiting for user input, this time is included in the Page Load Complete time
Limitations and Best Practices for Internet Explorer
■ The CA BRTM JavaScript is loaded asynchronously so it does not block the loading and execution of any application JavaScripts and other components. However, Internet Explorer does not wait on asynchronous loads before it generates the load event.
■ The CA BRTM JavaScript is dependent on the browser load event. Metrics are not sent if the CA BRTM JavaScript misses the event callback because it took too long to load. A long load time can occur on a page refresh, where the JavaScript is reloaded rather than using a cached version.
■ To ensure metric generation, set the Internet Explorer setting "Check for new versions of stored pages" to "automatic" or "never."
Limitations on Metric Reporting
After a page load event is complete, application JavaScripts can request more page content or components. Currently, CA BRTM does not report this type of request. For example, if a user clicks a button on a page that results in an AJAX request, there is no new page load, and metrics are not generated.
Application Considerations and Limitations
Chapter 1: Preparation 15
Application Considerations and Limitations
Review the application considerations and limitations that can affect metric generation and display.
When Automatic JavaScript Snippet Insertion Will Not Work
The following exceptions require you to use the manual snippet insertion option:
■ JavaServer Faces applications
Automatic JavaScript snippet insertion is dependent on standard HTML tags such as <head>. Because JSF pages use a custom tag library on the server side, this option does not work. Use the manual snippet option.
■ JavaScript write() function pages
Automatic JavaScript snippet insertion can cause syntax errors for pages that use the JavaScript write() function to create HTML tags. For these pages, use the excludePattern property described in the section, Configure Agent for Metric Collection.
■ Applications with Common Include Files
If your application uses an include file, which adds a common head section to every page, consider using the manual JavaScript snippet insertion. The automatic snippet insertion incurs system overhead when it inserts the snippet to your application pages.
To disable automatic snippet insertion, see the section, Configure Agents for Metric Collection. To add the snippet manually, see the section, Add JavaScript Snippet to Web Pages.
WebSphere Applications
■ Content types other than text/html
Automatic JavaScript insertion is supported for pages only with a content type of text/html. If the CA BRTM filter cannot determine the content type, JavaScript insertion is bypassed (for example, static html pages). To accommodate these pages, set the following web container property to false:
com.ibm.ws.webcontainer.setcontenttypebysetheader
Or, use the manual snippet insertion option.
■ WebSphere Portal Server
This portal server uses a single web.xml configuration in wps.ear, which is common to all applications. Specify the CA BRTM filter in the web.xml of the wps.ear. To control individual applications for monitoring, use the url-pattern parameters that are described in Configure Agents for Metric Collection.
WebLogic 10.3 and Automatic Filter Insertion
Application Considerations and Limitations
16 Configuration Guide
The automatic JavaScript filter injection is active for all applications that are deployed on WebLogic 10.3. To monitor a single application, use the CA BRTM properties excludeList or includeList as described in Configure Agents for Metric Collection. Or, you can use the manual filter option.
Monitoring Pages That Contain Frames
By design, all metrics are averaged. Frames are requests like the main page that includes them. If you have a single URL group, the main page metrics get averaged as frame metrics. If you define your URL groups with the main page separate from the frames, you can achieve separate metrics. Separate metrics can be beneficial if a particular frame is causing slowness in the main page. If you want only main page metrics, use the excludeList property and exclude the frame URLs. For details, see Configure Agents for Metric Collection.
Application Security Constraints
If your application has security specifications that limit specific application paths, add /BRTM to the <url-patterns> in the <web-resource-collection> elements in your web.xml. For details, see the section, Edit the web.xml.
Chapter 2: How to Install and Configure CA BRTM 17
Chapter 2: How to Install and Configure CA BRTM
This section contains the following topics:
How to Install and Configure CA BRTM (see page 18)
How to Install and Configure CA BRTM
18 Configuration Guide
How to Install and Configure CA BRTM
To install and configure CA BRTM, application engineers and Administrators must work closely together to ensure success.
Prerequisites
The tasks in this scenario require:
■ Knowledge of the applications
■ URLs of the applications that require instrumentation
■ Application names of the URLs (name of ear/war) file as shown in Appserver Console)
■ Location of application web.xml
■ For WebLogic application servers, knowledge of how to modify the class path of startup scripts
How to Install and Configure CA BRTM
Chapter 2: How to Install and Configure CA BRTM 19
1. Install CA BRTM (see page 20).
2. Make the CA BRTM Filter Available to Your Application (see page 22).
3. Configure Agents for Metric Collection (see page 23).
4. Edit the web.xml (see page 26)
5. Add the JavaScript Snippet to Web Pages (see page 27).
6. (Optional) Deploy CA BRTM to a Different Location (see page 28).
7. Verify That Metrics Work (see page 28).
How to Install and Configure CA BRTM
20 Configuration Guide
Install CA BRTM
CA BRTM is a CA APM agent extension.
Follow these steps:
1. Review the CA APM Compatibility Guide and verify the supported versions of CA BRTM and CA APM components.
2. If necessary, upgrade CA Enterprise Manager and agents for CA BRTM.
3. Select an installation type (Interactive, Manual, or Silent) and complete the steps.
Interactive Installation
The wizard lets you install CA BRTM including the dashboards and typeviews.
Follow these steps:
1. Unzip the CA BRTM software to a directory.
2. Click CAAPMforBRTM<release>.<os>.exe.
3. After installation, if the lib directory of the application server is not under <appServerHome>/lib, move the BRTMFilter.jar or BRTMFilter_WebLogic.jar (under wily/core/ext) as follows:
■ WebSphere – Move to lib/ext of the application server
■ Tomcat – Move to /lib of the application server
■ WebLogic – Add the CA BRTMFilters to the classpath in the application server startup script
Manual Installation
Follow these steps:
1. Unzip the CA BRTM software to a directory.
2. Install the dashboards and typeviews.
a. <appserver>/wily/examples/BRTM/em/config/modules, and copy the BRTM_ManagementModule.jar file to the same folder on the Enterprise Manager.
b. <appserver>/wily/examples/BRTM/em/ext/xmtlv, and copy the BRTM.typviewers.xml file to same folder on the Enterprise Manager.
3. Edit the IntroscopeAgent.Profile.
a. Go to: <unzipDir>/wily/core/config, open SampleIntroscopeAgent.Profile, copy all content, and paste at the end of IntroscopeAgent.Profile ([set AGENT value for your book]/wily/config).
b. Edit the directivesFile line and include the brtm.pbl.
How to Install and Configure CA BRTM
Chapter 2: How to Install and Configure CA BRTM 21
Example: introscope.autoprobe.directivesFile=...brtm.pbl...
4. Copy and paste all pdb and pbl files from <unzipDir>/wily/core config to your <agentinstall>/wily/core/config.
5. Copy <unzipDir>/wily/core/ext/BRTM.jar to <agentInstall>/wily/core/ext.
6. Copy and paste the BRTMFilter.jar or BRTMFilter_weblogic.jar from <unzipDir>/wily/core/ext to:
■ WebSphere – /lib/ext of the application server
■ Tomcat – /lib of the application server
■ WebLogic – <agentInstall>/wily/core/ext, and add the filter to the classpath in the application server startup script.
Silent Installation
Follow these steps:
1. In SampleResponseFile.APM-BRTM.txt, edit the following CA BRTM parameters:
USER_INSTALL_DIR=
appServer=
filterInsertionMethod=
appServerHome=
2. Start the installer:
For Windows: installer.exe -f <absolute path to response file>
For Linux: installer.bin -f <absolute path to response file>
How to Install and Configure CA BRTM
22 Configuration Guide
Make the CA BRTM Filter Available to Your Application
Make the CA BRTM Filter available to your application.
Follow these steps:
1. Review the manual and automatic filter options.
If you use the automatic filter, the CA BRTM filter is added to the application at run time. However, the option that you use depends on your application and existing environment.
Important! CA BRTM only operates on uncompressed, unencrypted, HTML content. The CA BRTM filter runs before all other filters after the first request is received, after other filters, and before the response is sent. If the application implements its own compression within the application, the CA BRTM JavaScript snippet cannot be inserted.
This Option... Is Available For...
Manual ■ WebSphere
■ Tomcat
■ WebLogic
AND
If you already have filters installed on your application, use the manual option. Manually adding the filter lets you place it away from other filters, and from encryption or compression filters.
Automatic WebLogic 10.3 only.
If your application is using a compression web filter, use the manual option.
2. Confirm that the appropriate CA BRTM filter is available to your application.
Server Select a Filter Make Filter Available to Application
WebLogic ■ (Manual) BRTMFilter.jar
■ (Automatic) BRTMFilter_weblogic.jar
Open the startWebLogic.cmd file and edit the JVM classpath to include the *.jar file.
WebSphere (Manual) BRTMFilter.jar Move the *.jar file to <AppServerHome>/ lib/ext.
Tomcat (Manual) BRTMFilter.jar Move the *.jar file to <AppServerHome>/lib.
How to Install and Configure CA BRTM
Chapter 2: How to Install and Configure CA BRTM 23
Configure Agents for Metric Collection
Specify manual or automatic JavaScript snippet insertion, and configure CA BRTM properties for metric collection.
Note: If you change the name of IntroscopeAgent.Profile, manually update the file with CA BRTM changes or changes are not registered.
Follow these steps:
1. Go to: wily/core/config, open SampleIntroscopeAgent.Profile, copy all content, and paste it at the end of the IntroscopeAgent.Profile (agent/wily/config).
2. In the IntroscopeAgent.Profile, edit the directivesFile line to include the brtm.pbl.
Example: introscope.autoprobe.directivesFile=...brtm.pbl...
3. Set the CA BRTM JavaScript snippet property for automatic or manual snippet injection. By default, automatic injection is enabled.
■ To disable the automatic snippet injection, uncomment the line and set to false
Example: introscope.agent.brt.snippetInsertionEnabled=false
Note: If you disable the snippet insertion after enabling it (for example, because of an application problem), metrics continue to be displayed for browser cached pages. Eventually, metrics stop displaying.
■ To enable the automatic snippet injection if previously disabled, uncomment the line and set to true (default)
Example: introscope.agent.brt.snippetInsertionEnabled=true
Important! If you are using automatic snippet injection, pages must have the content type text/HTML or the JavaScript is not injected. For example, if you have an HTML page with the content type text/plain, the snippet is not inserted.
4. Define monitoring and metric collection properties unless you want the default values (monitor all nodes and pages, with a limit on incoming requests at 5000).
Monitoring by URL Groups
By default, if URL Group properties are not specified, then all BRTM metrics are aggregated into a single Default node on the Introscope Investigator tree. You can define a URL group for any useful category of requests that can be derived from a URL’s path prefix. The path prefix is the portion of the URL that follows the hostname. For example, in the URL: http://burger1.com/testWar/burgerServlet?ViewItem=11776, the path prefix is /testWar. For detailed syntax and examples of these properties, see the CA APM Java Agent Implementation Guide, Java Agent Properties section. In any of the examples, use "Introscope.agent.brt" instead of Introscope.agent.
Example: introscope.agent.brt.urlgroup.group.delta.pathprefix=/*
Monitoring by Pages
How to Install and Configure CA BRTM
24 Configuration Guide
The excludeList and IncludeList properties let you limit monitoring and metric reporting.
■ To monitor a few pages, and not monitor most application pages, use includeList.
■ To monitor a few pages, and monitor most application pages, use excludeList.
■ The includeList takes precedence over the excludeList.
■ If you specify an includeList, only URLs that match are monitored (unless they also match pages that are specified in the excludeList).
Syntax:
■ introscope.agent.brt.excludeList=
Excludes pages from monitoring and metric reporting. Valid entries are comma-separated path prefixes or path prefixes with parameters. Default = empty string (exclude nothing). Supports HTML URL encoding using the ASCII character set. You must URL encode any reserved or non-ASCII characters.
Example: Introscope.agent.brt.excludeList=/acmetest/
In this example, a URL such as: http://somedomain/acmetest/somepath/index.html, is excluded from monitoring.
■ introscope.agent.brt.includeList=
Includes pages for monitoring and metric reporting. Valid entries are comma-separated path prefixes or path prefixes with parameters. Default = empty string (include all URLs). Supports HTML URL encoding using the ASCII character set. URL- encode any reserved or non-ASCII characters.
Example: Introscope.agent.brt.includeList=/mytest/somepath/
In this example, a URL such as: http://somedomain/mytest/somepath/index.html is included in monitoring, but a URL such as:
http://somedomain/mytest/mypath/index.html is not included.
Request Limits for Monitoring
Sets the number of incoming requests before monitoring is stopped, using a 15-second interval. This property reduces excessive load on system resources when request volumes are high. Default = 5000 requests. Requires application restart.
■ introscope.agent.brt.throttleResponseLimit=5000
Stop and Start Metric Generation
Controls metric reporting to the Enterprise Manager. Default = true (generate metrics). Requires application restart.
How to Install and Configure CA BRTM
Chapter 2: How to Install and Configure CA BRTM 25
■ introscope.agent.brt.enabled=true
Exclude JavaScript write() function Pages
Excludes pages from automatic snippet insertion because write() and writeln()) functions are not supported.
■ introscope.agent.brt.excludePatterns=.write(\",.write(',.writeln(\",.writeln('
How to Install and Configure CA BRTM
26 Configuration Guide
Edit the web.xml
Review the following scenarios and complete if applicable.
Scenario: Your application has security constraints
If your application has security specifications that limit specific application paths, update the web.xml as follows: add /BRTM to the <url-patterns> in the <web-resource-collection> elements in your web.xml. Where the URL is: /<yourapplication>/BRTM.
Example:
<security-constraint>
<web-resource-collection>
<url-pattern>/html/*</url-pattern>
<url-pattern>/BRTM</url-pattern>
</web-resource-collection>
</security-constraint>
<security-constraint>
<web-resource-collection>
<url-pattern>/</url-pattern>
</web-resource-collection>
<auth-constraint />
</security-constraint>
Scenario: You are manually adding the CA BRTM Filter
Complete these steps only if you are using the CA BRTM manual filter.
Follow these steps:
1. Stop the application server.
2. Open the web.xml file for the monitored application.
If your application does not have a web.xml, create one. See your application server documentation for the correct syntax.
3. In the web.xml deployment descriptor, add the CA BRTM filter and URL filter mapping.
Important! To ensure that metrics are generated, use the following table to place the filter.
If Your Web.xml Has... Insert the CA BRTM Filter...
Other filters, and no encryption or compression filters
Before all other filters.
Other filters and/or compression and/or encryption filters
Immediately after the last compression and/or encryption filters.
How to Install and Configure CA BRTM
Chapter 2: How to Install and Configure CA BRTM 27
Example: Monitors All URLs
For more information about the filter and filter mapping, see the Servlet Specification.
<filter>
<filter-name>BRTFilter</filter-name>
<filter-class>com.wily.brt.filter.BRTFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>BRTFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
4. Start the application server.
Add the JavaScript Snippet to Web Pages
Review the section, Application Considerations and Limitations, and the following scenarios and determine if the steps apply to your implementation.
Scenario: You are using the manual JavaScript snippet insertion, and are deploying the JavaScript (apmbrtm.js) to the default location
Follow these steps:
1. Go to: /wily/core/config, open the snippet.js, and replace the following line:
brtm.src = window.location.protocol + '//APP_HOSTNAME:' + window.location.port + '/.../apmbrtm.js'; '
with:
brtm.src = '$BRT_CONTEXT_ROOT?WilyCmd=cmdJS';
2. Copy the content of snippet.js, open each HTML page, and paste the snippet.js content before the </head> tag and after other scripts.
Scenario: You are using the manual JavaScript insertion, but are deploying the JavaScript (apmbrtm.js) to a nondefault location
Follow these steps:
1. Go to: /wily/core/config, and open the snippet.js.
2. Copy the content of snippet.js
3. Open each HTML page and paste the snippet.js content before the </head> tag and after other scripts.
4. Go to the next section and complete steps to deploy the JavaScript to a nondefault location.
How to Install and Configure CA BRTM
28 Configuration Guide
(Optional) Deploy CA BRTM JavaScript to a Different Location
If you are using automatic or manual snippet insertion, but want to change the default location of the CA BRTM JavaScript (apmbrtm.js), complete this step. By default, if you set snippetInsertionEnabled=true, the snippet.js and the CA BRTM JavaScript (apmbrtm.js) is read from the BRTM.jar file.
To deploy the CA BRTM JavaScript in a different location, follow these steps:
1. Go to: agent/wily/config and open IntroscopeAgent.Profile.
2. Specify the snippet.js location in the property, introscope.agent.brt.snippetLocation=<location of snippet.js>.
Example: introscope.agent.brt.snippetLocation=c:\\appserver\\wily\\core\\config\\snippet.js
3. Go to: /wily/core/config and copy apmbrtm.js to the new deployment location (within the application or on another server).
4. Go to: /wily/core/config, open the snippet.js, and add the correct hostname and path to apmbrtm.js in this line:
Example: brtm.src = window.location.protocol + '//APP_HOSTNAME:' + window.location.port + '/.../apmbrtm.js';
Important! If you deploy apmbrtm.js on another server or a proxy web server, you may need to specify the port, rather than using the JavaScript window.location specification. Also, verify that the hostname is correct; an incorrect name can adversely affect your application and cause CA BRTM to fail.
Example: brtm.src = window.location.protocol + '//somedomain:8080/myapp/apmbrtm.js';
Verify that Metrics Work
Follow these steps:
1. Start the monitored application and create actions to generate metrics.
2. Verify that you see the snippet in a browser page using View Source Page.
3. Start the Introscope user interface.
4. Verify that you see timing metrics in the Investigator tree.
Example: Metric Browser, SuperDomain, TEST0088, Tomcat, Browser, URL Group, Default.
If you do not see metrics, see Troubleshooting or view the IntroscopeAgent.log file.
Chapter 3: How to Uninstall CA BRTM 29
Chapter 3: How to Uninstall CA BRTM
Based on how you installed CA BRTM, select instructions for uninstalling the product.
Interactive
Follow these steps:
1. Shut down the application server.
2. Remove the CA BRTM changes to the application web.xml.
3. Go to: <Wily Agent_Home>/UnstallerData/BRTM and run Uninstall_Introscope_BRTM.
Manual
Follow these steps:
1. Shut down the application server.
2. Remove the CA BRTM changes to the application web.xml.
3. Go to the section, Install CA BRTM, Manual Installation, reverse the steps and manually remove the components.
Chapter 3: How to Uninstall CA BRTM 31
Appendix A: Troubleshooting
This section contains the following topics:
Metrics Are Not Appearing in User Interface (see page 31) Nodes Are Not Displaying (see page 33) Metric Counts Are Higher Than Expected (see page 33) JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying (see page 34) Average Round Trip and Average Browser Render Time Metrics Not Displaying (see page 34) Include or Exclude URLs Are Not Filtering Correctly (see page 34) All WebLogic 10.3 Applications Are Instrumented (see page 35)
Metrics Are Not Appearing in User Interface
If the CA BRTM metrics are not displaying in the user interface, use the following table to troubleshoot.
Verify the Following Descriptions
Are browsers enabled for Java and cookies?
This is a requirement for CA BRTM metrics.
Does Enterprise Manager have enough connections?
Check the Enterprise Manager for alerts about not having enough connections to display CA BRTM metrics.
Are you using older browsers or Internet Explorer?
Review the section, Browser Limitations for details related to metrics not appearing.
Are you seeing the nodes you expect?
If you configured CA BRTM properties to include only certain nodes, excluded specific nodes, or filter by URL groups, you may not see nodes. Check these properties to make sure they reflect your intentions.
Did you deploy the CA BRTM JavaScript to a different location from the default?
Verify that the host, port, and path specified in the snippet are correct, and that apmbrtm.js can successfully be retrieved. For details, see the section, Deploy CA BRTM JavaScript to a Different Location.
Metrics Are Not Appearing in User Interface
32 Configuration Guide
Verify the Following Descriptions
Did you check your application browser page to verify that the CA BRTM JavaScript snippet is inserted?
Check the log files to verify that the snippet was inserted.
If you moved the snippet from the default .JAR to another location, verify the path of that location.
If you have verified above, and you are not getting metrics, it could be due to browser cached pages. If there is user traffic, metrics should eventually appear.
Is the page content type valid HTML? Is your content uncompressed and unencrypted?
If you are using automatic JavaScript injection, and you have pages text/plain content types, the JavaScript is not injected. Check the page content type and manually add the snippet for those pages.
CA BRTM only supports unencrypted, uncompressed data.
Did you change the name of IntroscopeAgent.Profile?
The installer recognizes the fixed file name only. If you change the file name, the CA BRTM installer does not update the profile file, but places a new IntrosopeAgent.Profile in wily/core/config. If you change the file name, manually add any CA BRTM changes.
Is the brtm.pbl file included in the list of directivesFiles in your IntroscopeAgent.profile?
Is the BRTM.jar file is in the wily/core/ext directory on the agent?
Nodes Are Not Displaying
Chapter 3: How to Uninstall CA BRTM 33
Nodes Are Not Displaying
Symptom:
I do not see nodes in the user interface.
Solution:
CA BRTM only represents URLs from the browser perspective. If you specify a URL Group format with a pathprefix value that includes the actual default page file name, it is not matched, and the node is not displayed. For example, if your application defines a default page to be index.html, and the browser user only enters //somedomain/myapp/, CA BRTM recognizes the URL as: /myapp/ not /myapp/index.html.
To fix this problem, specify a URL Group with a general pathprefix and a format of path_substring.
Symptom:
I do not see a node name until a valid metric is received.
Solution:
The behavior could be a normal response. For example, Average Page Unload is not available for an initial page. Until a page is refreshed or there is navigation from a subsequent page back to the initial page, the node name is not displayed.
Metric Counts Are Higher Than Expected
Symptom:
I see a count field (or metric) that is higher than I expect.
Solution:
If the JavaScript snippet insertion property is set to automatic: introscope.agent.brt.snippetInsertionEnabled=true (default), and you also manually added the snippet to web pages, the metrics are sent twice. Verify that the IntroscopeAgent.Profile setting, excluded pages, and web pages match your intentions.
JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying
34 Configuration Guide
JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying
Symptom:
I disabled automatic the JavaScript snippet insertion, but I still see metrics. Is that normal?
Solution:
Yes. For example, if you disabled the snippet insertion because of an application problem, metrics continue to be displayed for browser cached pages. Eventually, metrics stop displaying.
Average Round Trip and Average Browser Render Time Metrics Not Displaying
Symptom:
I do not see the Average Round Trip Time and Average Browser Render Time metrics.
Solution:
These metrics are available only if your browser supports the web timing API.
Include or Exclude URLs Are Not Filtering Correctly
Symptom:
I see metrics for a node that I've excluded, or I am not getting metrics for nodes that I have included in my agent properties.
Solution:
Check your exclude or include list properties for unsupported URL characters.CA BRTM supports HTML, URL encoding using the ASCII character set. Specifically, CA BRTM supports URLS that contain the main path, and query parameters starting with “?”. URL-encode any reserved or non-ASCII characters. The exception is using the # 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.
All WebLogic 10.3 Applications Are Instrumented
Chapter 3: How to Uninstall CA BRTM 35
All WebLogic 10.3 Applications Are Instrumented
Symptom:
I configured CA BRTM with the automatic filter, and all of my WebLogic 10.3 are automatically instrumented. I want instrumentation only on specific applications.
Solution:
This result is by design. See Application Considerations for other options.