apm_9.5--browser response time monitor guide

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.

http://www.ca.com/support

mailto:[email protected]

http://www.ca.com/docs

http://www.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

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


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



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.


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



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.



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.

■ 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 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


How to Install and Configure CA BRTM (see page 18)

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



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).



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.



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>



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.



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



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.



■ 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('



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.



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.



(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

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.


Appendix A: Troubleshooting


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


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


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


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


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.

apm_9.5--browser response time monitor guide

Documents