CA Application Performance Management

Transcription

1 CA Application Performance Management for Browser Response Time Monitor Installation and Configuration Guide Release 9.6

2 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 is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. 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 , , and (c)(1) - (2) and DFARS Section (b)(3), as applicable, or their successors. Copyright 2014 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

3 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 for z/os (CA APM for IBM WebSphere Application Server for z/os) CA Application Performance Management for IBM WebSphere for Distributed Environments (CA APM for IBM WebSphere for 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)

4 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 CA NetQoS Performance Center CA Performance Center

5 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 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 techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

6

7 Contents Chapter 1: Preparation 9 Features and Requirements Implementation Browser Considerations Application Considerations and Limitations Chapter 2: How to Install and Configure CA BRTM 17 How to Install and Configure CA BRTM Install CA BRTM Make the CA BRTM Filter Available to Your Application Configure Agents for Metric Collection Edit the web.xml Add the JavaScript Snippet to Web Pages (Optional) Deploy CA BRTM JavaScript to a Different Location Verify that Metrics Work Chapter 3: How to Uninstall CA BRTM 29 Appendix A: Troubleshooting 31 Metrics Are Not Appearing in User Interface Nodes Are Not Displaying Metric Counts Are Higher Than Expected JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying Average Round Trip and Average Browser Render Time Metrics Not Displaying Include or Exclude URLs Are Not Filtering Correctly All WebLogic 10.3 Applications Are Instrumented Index 37 Contents 7

8

9 Chapter 1: Preparation This guide describes how to install and configure CA Application Management 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 14) Chapter 1: Preparation 9

10 Features and Requirements 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. 10 for Browser Response Time Monitor Installation and Configuration Guide

11 Implementation 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) Average Round Trip Time (ms) The time for the browser to parse the page and load all components. The time when the browser first requests a page, until the entire page response is received. loadeventstart time domloading time responseend time requeststart time Chapter 1: Preparation 11

12 Implementation 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) Average Previous Page Unload Time (ms) The time from navigation start to when the browser loads all components and the page is complete. 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. loadeventstart time navigationstart time 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) Average Previous Page Unload Time (ms) The time from navigation start to when the browser loads all components and the page is complete. 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. load event time beforeunload event time unload event time beforeunload event time 12 for Browser Response Time Monitor Installation and Configuration Guide

13 Browser Considerations 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 Metrics are not produced for an initial page Metrics reported only for instrumented pages Page Load Complete Time is based on the actual load event What You Should Know 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. 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. 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. Chapter 1: Preparation 13

14 Application Considerations and Limitations 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 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. 14 for Browser Response Time Monitor Installation and Configuration Guide

15 Application Considerations and Limitations 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 The automatic JavaScript filter injection is active for all applications that are deployed on WebLogic 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. Chapter 1: Preparation 15

16 Application Considerations and Limitations 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. 16 for Browser Response Time Monitor Installation and Configuration Guide

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) Chapter 2: How to Install and Configure CA BRTM 17

18 How to Install and Configure CA BRTM 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 18 for Browser Response Time Monitor Installation and Configuration Guide

19 How to Install and Configure CA BRTM 1. Install CA BRTM (see page 19). 2. Make the CA BRTM Filter Available to Your Application (see page 21). 3. Configure Agents for Metric Collection (see page 23). 4. Edit the web.xml (see page 25) 5. Add the JavaScript Snippet to Web Pages (see page 26). 6. (Optional) Deploy CA BRTM to a Different Location (see page 27). 7. Verify That Metrics Work (see page 28). 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. 4. Install and deploy the Management Modules and Typeviews in one of the following ways: If you have installed CA BRTM on the application server: Copy the BRTM_ManagementModule.jar file from <Agent_Home>/examples/BRTM/em/config/modules to the config/modules folder on the Enterprise Manager. Copy the BRTM.typviewers.xml file from <Agent_Home>/examples/BRTM/em/ext/xmtlv to the ext/xmtlv folder on the Enterprise Manager. Run the BRTM installer directly on the Enterprise Manager to deploy the Management Modules and Typeviews to the respective folder locations. 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. Chapter 2: How to Install and Configure CA BRTM 19

20 How to Install and Configure CA BRTM 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 4. Install and deploy the Management Modules and Typeviews as described previously. Manual Installation Follow these steps: 1. Unzip the CA BRTM software to a directory. 2. Install and deploy the Management Modules and Typeviews as described previously. 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. Example: introscope.autoprobe.directivesfile=...brtm.pbl 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. 20 for Browser Response Time Monitor Installation and Configuration Guide

21 How to Install and Configure CA BRTM Silent Installation Follow these steps: 1. In the SampleResponseFile.APM-BRTM.txt file, edit the following CA BRTM parameters: USER_INSTALL_DIR= appserver= filterinsertionmethod= appserverhome= Note: For a successful installation of the Enterprise Manager extensions, ensure that both the USER_INSTALL_DIR and appserver parameters point to the EM_Home directory. 2. Install and deploy the Management Modules and Typeviews as described previously. 3. Start the installer: For Windows: installer.exe -f <absolute path to response file> For Linux: installer.bin -f <absolute path to response file> 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 AND Tomcat WebLogic 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. Chapter 2: How to Install and Configure CA BRTM 21

22 How to Install and Configure CA BRTM This Option... Automatic Is Available For... 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. 22 for Browser Response Time Monitor Installation and Configuration Guide

23 How to Install and Configure CA BRTM 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 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: 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 Chapter 2: How to Install and Configure CA BRTM 23

24 How to Install and Configure CA BRTM The excludelist and IncludeList properties let you limit monitoring and metric reporting. Syntax: To 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). 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: 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: is included in monitoring, but a URL such as: 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. introscope.agent.brt.enabled=true 24 for Browser Response Time Monitor Installation and Configuration Guide

25 How to Install and Configure CA BRTM 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(\",.writel n(' 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. Chapter 2: How to Install and Configure CA BRTM 25

26 How to Install and Configure CA BRTM 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... Other filters, and no encryption or compression filters Other filters and/or compression and/or encryption filters Insert the CA BRTM Filter... Before all other filters. Immediately after the last compression and/or encryption filters. 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. 26 for Browser Response Time Monitor Installation and Configuration Guide

27 How to Install and Configure CA BRTM 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. (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'; Chapter 2: How to Install and Configure CA BRTM 27

28 How to Install and Configure CA BRTM 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. 28 for Browser Response Time Monitor Installation and Configuration Guide

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 29

30

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 Are browsers enabled for Java and cookies? Does Enterprise Manager have enough connections? Are you using older browsers or Internet Explorer? Are you seeing the nodes you expect? Did you deploy the CA BRTM JavaScript to a different location from the default? Descriptions This is a requirement for CA BRTM metrics. Check the Enterprise Manager for alerts about not having enough connections to display CA BRTM metrics. Review the section, Browser Considerations for details related to metrics not appearing. 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. 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. Appendix A: Troubleshooting 31

32 Metrics Are Not Appearing in User Interface Verify the Following Did you check your application browser page to verify that the CA BRTM JavaScript snippet is inserted? Is the page content type valid HTML? Is your content uncompressed and unencrypted? Did you change the name of IntroscopeAgent.Profile? Descriptions 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. 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. 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? 32 for Browser Response Time Monitor Installation and Configuration Guide

33 Nodes Are Not Displaying 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. Appendix A: Troubleshooting 33

34 JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying 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. 34 for Browser Response Time Monitor Installation and Configuration Guide

35 All WebLogic 10.3 Applications Are Instrumented 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 and Limitations for other options. Appendix A: Troubleshooting 35

36

37 Index ( (Optional) Deploy CA BRTM JavaScript to a Different Location 27 A Add the JavaScript Snippet to Web Pages 26 All WebLogic 10.3 Applications Are Instrumented 35 Application Considerations and Limitations 14 Average Round Trip and Average Browser Render Time Metrics Not Displaying 34 B Browser Considerations 13 C CA Technologies Product References 3 Configure Agents for Metric Collection 23 Contact CA Technologies 5 E Edit the web.xml 25 F Features and Requirements 10 H How to Install and Configure CA BRTM 17, 18 How to Uninstall CA BRTM 29 I Implementation 11 Include or Exclude URLs Are Not Filtering Correctly 34 Install CA BRTM 19 J JavaScript Snippet Injection is Turned Off, But Metrics Are Still Displaying 34 M Make the CA BRTM Filter Available to Your Application 21 Metric Counts Are Higher Than Expected 33 Metrics Are Not Appearing in User Interface 31 N Nodes Are Not Displaying 33 P Preparation 9 T Troubleshooting 31 V Verify that Metrics Work 28 Index 37