Precise For J2EE v87 UG

Precise for J2EE
Users Guide
Version 8.7
Precise for J2EE Users Guide

Copyright 2009 Precise Software Solutions, Inc. All rights reserved. Precise for J2EE version 8.7 Document release version 1.0 Precise, the Precise Logo, Precise i, Precise Enterprise, Precise Indepth, Precise Insight, Precise Savvy, SmarTune, Performance Warehouse, Precise Application Service Dashboard, Precise for Storage Tiering, Precise for Storage Tiering Plus Apps, Precise for Storage, and Precise Insight Inquire are trademarks or registered trademarks of Precise Software Solutions, Inc. or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners. The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of Precise Software Solutions, Inc. and its licensors, if any. Certain third-party software may be distributed, embedded, or bundled with this product or recommended for use in connection with its installation and use. Such third-party software is separately licensed by its copyright holder. The list that includes the names of the copyright and license agreements can be found in the Release Notes document. THE DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. PRECISE SOFTWARE SOLUTIONS, INC. SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. The Licensed Software and Documentation are deemed to be commercial computer software as defined in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS 227.7202, Rights in Commercial Computer Software or Commercial Computer Software Documentation, as applicable, and any successor regulations. Any use, modification, reproduction release, performance, display or disclosure of the Licensed Software and Documentation by the U.S. Government shall be solely in accordance with the terms of this Agreement. Precise Software Solutions, Inc. 3 Twin Dolphin Drive Suite 350 Redwood Shores, CA 94065
Third-party legal notices

Third-party software may be recommended, distributed, embedded, or bundled with this Precise product. Such third-party software is licensed separately by its copyright holder. All third-party copyrights associated with this product are listed in the accompanying release notes.
Technical support
For technical assistance, visit our customer portal at my.precise.com where you can find an extensive knowledge base, product updates and our online community forums. You can also contact our Customer Support Team via our customer portal, or go to www.precise.com/support for a list of our support access numbers in your country.
Document change history

Version - Book release Month Year Change description Location
Contents
Chapter 1 Precise for J2EE Basics
How most workspaces are structured ........................................................................................9 About the Workspace selection bar ...................................................................................10 Switching to a different workspace .............................................................................11 About the General Options bar ..........................................................................................11 About the Call Path ...........................................................................................................11 About the General toolbar .................................................................................................11 About the Main area ..........................................................................................................11 About Main area features ...........................................................................................12 About the Association area ...............................................................................................12 About display intervals ..............................................................................................................12 About the Time Frame .......................................................................................................12 About the Archive Data Selection page .....................................................................13 Selecting data for analysis ................................................................................................15 About the Loading data... message ...................................................................................15 About administration pages ......................................................................................................15 About the Java Virtual Machine Settings Administration page ..........................................15 About the Monitoring Configuration page ...................................................................15 About the Java Virtual Machine Settings Administration options ...............................16 About the Java Virtual Machine Settings page ..................................................................16 About the FocalPoint Administration page ........................................................................18 About Layout Options .................................................................................................18 About Archiving Options .............................................................................................19 About Database Options ............................................................................................19 Switching from MySQL to Oracle ...............................................................................19 About Security Options ..............................................................................................20 About the Findings Administration page ............................................................................20 About the Findings Analysis and Graph options ........................................................21 About the Call Graph threshold options .....................................................................21 About the Call Graph configuration options ...............................................................21 About Contributors by Category Page Analysis options ............................................21 About Findings Application Summary categories .......................................................23 About the Business Transactions Administration page .....................................................27 About the Business Transactions Administration options ..........................................27 Creating a business transaction .................................................................................28 About the System Status page .................................................................................................28 About the Status Details page ...........................................................................................29 About data collection in Precise for J2EE .................................................................................29 About Monitoring Configuration .........................................................................................29 About Monitoring Configuration icons ........................................................................30 About selecting a pattern for editing or viewing matching loaded classes and methods .......................................................................................................30 About Monitoring Configuration results ......................................................................30 About Status values ...................................................................................................31 About Type values .....................................................................................................31 About Monitoring Configuration controls ....................................................................31 About the Pattern Manager ...............................................................................................32 About Pattern Manager loaded classes and methods results ....................................33 About instrumentation modes ............................................................................................33
Contents
About Adaptive Instrumentation ........................................................................................34 Tips on Adaptive Instrumentation ...............................................................................35 About the Adaptive Instrumentation Wizard page ......................................................38 Procedures for Adaptive Instrumentation ...................................................................40 About the Expert Configuration page ................................................................................42 About Expert Configuration options ...........................................................................43 About the Statistics Administration page ...........................................................................44 About the Statistics Administration options ................................................................45 About the Add Statistics to Configuration page ..........................................................45 About the Copy Instrumentation page ...............................................................................46 Troubleshooting memory errors and adjusting heap sizes ................................................46 About JVM heap size for all JDKs ..............................................................................47 About increasing collector memory ............................................................................47 About permanent generation size for Sun JDKs ........................................................47 Setting initial system heap size for IBM JDKs ............................................................47 How to launch the Precise for J2EE user interface ..................................................................48 Launching Precise for J2EE from Precise StartPoint ........................................................48 Launching the user interface directly .................................................................................48
Chapter 2
Getting an overview of your environment in the Dashboard workspace

About the Dashboard workspace .............................................................................................50 About Portlets ....................................................................................................................51 About the time frame .........................................................................................................51 About the environment ......................................................................................................51 About the AppTier .............................................................................................................52 Configuring portlets ...........................................................................................................52 About the Dashboard portlets ...................................................................................................53 About the JVM List portlet .................................................................................................53 About the All JVMs Health portlet ......................................................................................54 About the All JVMs Threads portlet ...................................................................................54 About the Concurrent Active Thread Metrics portlet .........................................................55 About the Exception Seeker portlet ...................................................................................55 About the Grouped JVMs Health portlet ............................................................................56 About the Grouped JVMs Threads portlet .........................................................................57 About the Invocation Type Scalability portlet ....................................................................57 About the JDBC Metrics portlet .........................................................................................57 About the JVM Health portlet ............................................................................................58 About the Leak Seeker Metrics portlet ..............................................................................59 About the Lock Seeker Metrics portlet ..............................................................................59 About the Memory Metrics portlet .....................................................................................59 About the Method Scalability portlet ..................................................................................60 About the Portal Server Metrics portlet .............................................................................61 About the SQL Statements portlet .....................................................................................61 About the Findings Application Summary portlet ..............................................................62 Findings Application Summary Categories ................................................................63 About the Findings Application Summary portlet ..............................................................63 About the Statistics portlet .................................................................................................63 About the Top Business Transactions portlet ....................................................................64 About the Top Instrumented Methods portlet ....................................................................64 About the Top Methods by Invocation Type portlet ...........................................................65 About the Work Times of Invocation Types portlet ............................................................66 How to identify performance problems in the Dashboard workspace .......................................66 Diagnosing scalability issues .............................................................................................66 Identifying a CPU bottleneck .............................................................................................67
Contents
Identifying a memory bottleneck ........................................................................................67 Identifying which tier has a bottleneck ...............................................................................68 Detecting a service backlog ..............................................................................................68
Chapter 3
Examining performance over time in the Activity workspace

About the Activity workspace ....................................................................................................69 About Java virtual machines .............................................................................................69 About HTTP, EJB, and portlet service requests ................................................................69 About URI, Java class, and method names ......................................................................70 About invocations ..............................................................................................................70 About Work Time ...............................................................................................................71 About invocation context ...................................................................................................71 About Activity workspace tabs ..................................................................................................71 About the Highlights tab ....................................................................................................72 About the Hotspots tab ......................................................................................................73 About the Hotspots - Deep Summary view ................................................................74 About the Hotspots - Per Caller view .........................................................................75 About the Hotspots - Call Graph view ........................................................................75 About the Invocations tab ..................................................................................................75 About the Business tab .....................................................................................................77 About the SQL tab .............................................................................................................77 About the SQL - Deep Summary view .......................................................................78 About the SQL - Per Caller view ................................................................................78 About the Single SQL Statement screen ...................................................................78 About the Locks tab ...........................................................................................................79 About the Locks - Deep Summary view .....................................................................80 About the Locks - Per Caller view ..............................................................................80 About the Exceptions tab ..................................................................................................80 About the Exceptions - Deep Summary view .............................................................81 About the Exceptions - Per Caller view ......................................................................81 How the Activity workspace can help you identify performance problems ...............................81 Analyzing performance bottlenecks using SmarTune findings ..........................................81 Analyzing Java method contributions to application performance .............................81 Analyzing application server performance ........................................................................82 Identifying slow HTTP service requests (Servlets or Java Server pages) .........................82 Isolating slow database queries ........................................................................................83 Identifying CPU consumers ...............................................................................................83 Viewing business transaction performance for specific application functions ...................83
Chapter 4
Examining application server metrics in the Statistics workspace

About Statistics workspace tabs ...............................................................................................85 About the Findings tab ......................................................................................................86 About the Counters tab .....................................................................................................86 How the Statistics workspace can help you identify performance problems ............................87 Investigating database connection pool size .....................................................................87
Chapter 5
Examining usage and trends in the Memory workspace

About the Memory workspace ..................................................................................................88 About the Memory workspace tabs ..........................................................................................88 About the Heap tab ...........................................................................................................88 About the Garbage Collection tab .....................................................................................89 About the Leak Seeker tab ................................................................................................89
Appendix A
Configuring Precise for J2EE instrumentation
Contents
About using custom instrumentation ........................................................................................91 About modifying instrumenter configuration files ...............................................................91 Enabling an additional configuration file .....................................................................92 Adding your own custom instrumentation configuration file .......................................92 About custom instrumenter configuration ..........................................................................93 About instrumenting interfaces ...................................................................................94 About instrumenting classes ......................................................................................98 About instrumenting all calls from a method ............................................................102 About instrumenting calls to methods ......................................................................102 About preventing instrumentation for classes, methods, and calls to methods .......103 About instrumenting calls to EJB business method implementations .............................106 About the Calls to EJB instrumentation feature .......................................................106 About instrumenter configuration file reference ...............................................................108 About the master configuration file ...........................................................................109 About the instrumenter configuration files ................................................................110 About the structure of instrumenter configuration files .............................................111 About common instrumenter configuration matching techniques ............................114 Including application server classes in Leak Seeker instrumentation .............................116 About using the instrumentation configuration utility ..............................................................116 About system requirements .............................................................................................116 About how the ICU works ................................................................................................116 About prerequisites to using the ICU ...............................................................................117 About obtaining data files for the ICU ..............................................................................117 About running the ICU .....................................................................................................117 Loading data files for analysis .........................................................................................118 About identifying methods of interest ..............................................................................118 Enabling or disabling instrumentation for a method ........................................................119
Glossary Index
121 132
Chapter
Precise for J2EE Basics

This section includes the following topics:

How most workspaces are structured About display intervals About administration pages About the System Status page About data collection in Precise for J2EE How to launch the Precise for J2EE user interface
How most workspaces are structured

Though each workspace is structured differently, most workspaces consist of two different areas. Each area can include different control elements, such as tabs and view controls, and displays information in various formats, such as tables, graphs, or charts. The various areas are related to each other in that performing an action in one area affects the information displayed in other areas on the page. For example, the current workspace displayed contains an upper and a lower area. The lower area (Association area) shows information in a table format. Each row in the table represents an application. The upper area (Main area) displays general information on the selected entity as well as related applications. The entities displayed in the Association area are associated with the selected entity or related application displayed in the Main area. At times, the relationship between the entity displayed in the Main area and those displayed in the Association area is that of parent to child, and sometimes it merely represents that there is a relationship between the selected entity and the entities displayed in the Association area. It is possible to click a row and drill down to an additional level below the selected level or use the filter function to determine which information is displayed in the table. When you perform an action on an element in the lower area (in this case the Association area), the information displayed in the upper area (in this case the Main area) changes to reflect the action you requested. See About the Main area on page 11. See About the Association area on page 12. Most Precise for J2EE workspaces contain the following elements:

Workspace selection bar General options bar Call path Status bar Analysis tabs Main area Association area
Precise for J2EE Basics How most workspaces are structured
10
Precise icons
The figure below shows the common workspace elements. Figure 2-1 Workspace terminology
Workspace selection bar Status bar
General options bar Analysis tabs
Main area
Association area
Table settings
About the Workspace selection bar

Precise for J2EE consists of different workspaces. Click on the corresponding workspace in the Workspace selection bar in order to move between different workspaces. The Workspace Selection bar consists of the following:

Dashboard Activity Statistics Memory
The table below describes which tasks can be performed in each workspace. Table 2-1 Workspace
Dashboard
Precise for J2EE workspaces Description

The Precise for J2EE Dashboard is an easy-to-use tool for visualizing the overall health and status of all instrumented application server instances. The Precise for J2EE Dashboard provides support for detailed views of individual application servers as well as top-level summary views of multiple application servers. The Dashboard workspace is the Precise for J2EE home page. See About the Dashboard workspace on page 50.
Activity
The Activity workspace enables you to investigate your JVM invocation tree in a deep or shallow manner, and to track SQL execution, locks and exceptions in the same manner. See About the Activity workspace on page 69.
Precise for J2EE Basics How most workspaces are structured
11
Table 2-1 Workspace

Statistics
Precise for J2EE workspaces Description

The Statistics workspace displays Application Server metrics. See About Statistics workspace tabs on page 85.
Memory
The Memory workspace allows you to examine memory usage, garbage collection, and Leak Seeker data. See About the Memory workspace on page 88.
Switching to a different workspace

You can easily switch between the different workspaces using the Workspace Selection bar. When you start your Precise product, the default workspace opens. The button of the selected workspace is displayed in orange. To select a workspace
Click a button on the Workspace Selection bar to display information on the selected entity in a different workspace.
About the General Options bar

The General Options bar is located at the top-right of the Precise for J2EE user interface pages. The General Options bar provides the following buttons and links:
Settings Displays the general toolbar below the General Options bar and the Precise for J2EE administration pages in the main workspace area. Opens a Help window. Indicates that Precise for J2EE is processing a user request. Click the Precise logo on the right side of the General Options bar to display the Precise for J2EE software product version, build number, and to view the EULA.
Help System-working dots Precise logo
About the Call Path

The Call Path is located below the Workspace selection bar. The Call Path shows your current location within the invocation tree of your application.
About the General toolbar

Clicking Settings in the General options bar at the top right of the J2EE user interface displays the General toolbar. The General toolbar appears just below the Precise logo and the General options bar. It consists of:

Status click to view the System Status page Configure selected by default, and the main workspace area displays the administration pages
About the Main area

The center of the Precise for J2EE user interface is the main workspace area. When you select a workspace in the workspace selection bar, the home page for the workspace displays in the main workspace area. For the Activity, Statistics, and Memory workspaces, data displayed in the main area of the user interface is specific to the context shown in the Call Path. The Analysis tabs available at the top level of the Activity workspace display the following:

Highlights Hotspots
Precise for J2EE Basics About display intervals

12
Invocations Business SQL Locks Exceptions
As you navigate through Precise for J2EE, the Analysis tabs change to enable you to view metrics relevant to the open page. The main area occupies many Precise for J2EE pages. The information displayed in this area changes as you select views, modes, and reports and drill down to underlying data.
About Main area features

The main area may contain graphs, tables, or both. The range of time that the page graphs or tables summarize is displayed in the time frame drop-down box. The times displayed are local times on the FocalPoint server where the page was generated. Graph titles contain the units of the values displayed in the graph. You can see information for a time slice that belongs to a time series by moving the mouse over the point on the line graph that represents the time slice.
About bar graphs for a time slice

The user interface displays time slice data in bar graphs. Bar graphs summarize one slice of data and generally compare several values of similar type, such as time or throughput. For example, contributors of a higher level metric are displayed as bars in the graph, with their type and percentage work time displayed by putting the mouse over the area of interest (see the Workspace terminology figure). Each displayed metric value is an average of observations within the slice.
About line graphs for a time series

The user interface displays time series data in line graphs. Line graphs summarize many slices of data. You can change the number of items plotted by selecting or unselecting check boxes located to the right of the graph. Each point in the graph represents the total metric value for a time slice included in the time series.
About the Association area

The Association area lists entities that have similar attributes and that are related to the selected entity named in the Workspace heading. The information displayed in the Association area is arranged in a tabular format.
About display intervals

Precise for J2EE displays either a single aggregation interval, called a time slice, or a range of intervals, called a time series. You can display the most recent time slice or series received from the Precise for J2EE Collector or you can display earlier time slices or series. By default, all workspaces display the most recent time series.
About the Time Frame

You can change the time frame using the Time Frame drop-down list. Changing the time frame in one workspace changes it in all workspaces. The timestamps on the data are the time of the Precise for J2EE FocalPoint. The first item in the Time Frame drop-down list is always the currently selected time slice or series. The length of the aggregation interval and the number of intervals in a series are configured in the FocalPoint Administration page. The Time Frame drop-down list also allows you to select previous time series such as the last hour, last 8 hours or last day. Selecting More... opens the Time Frame dialog box where you can select other time frames. The Time Frame dialog contains the information described in the table below, in addition to the following buttons:

13
Archive Chooser OK Cancel
The table below describes the Time Frame options. Table 2-2 Option
Archive Folder
Time Frame options Description

List of available data folders. Select the folder from which you wish to display data. By default, Precise for J2EE contains one Active archive folder:
Active is the folder containing current data for all monitored JVMs. The length of time for which data is collected in the Active archive is set by the Aging Timespan parameter in the FocalPoint Administration page.
JVM
Server host name and JVM ID of a monitored JVM. The list of JVMs contains all monitored JVMs for which your role(s) has access. Select a specific time frame.
From/To Day/Month/Year/Hour/Minutes Last n Hours/Days/Weeks/Months Use a previously saved time frame Save these definitions for future use as
Enter a number and select a time interval.
This option is available if you have selected and saved a time frame. Select the name that you gave the time frame, when you saved it, from the drop-down list. Specify a time frame, then check this box to save the defined time frame with a name of your choosing. The time frame will be available in the Use a previously saved time frame option. Note: The saved time frame remains part of active data and will be purged according to the Aging Timespan setting in the FocalPoint Administration page. To permanently retain data from a specified time frame, you must create your own archive folder using the data export and import scripts. For details on using these scripts, see the Precise Administration Guide.
Archive Chooser
Opens the Archive Data Selection page where you choose data from the currently selected archive or select a different inactive archive label.
See About Archiving Options on page 19.
About the Archive Data Selection page

The Archive Data Selection pages enable you to select specific data stored in archive files. You also use the Archive Data Selection page to choose whether to display data from the Active archive, the currently selected Inactive Archive, or to select a different inactive archive. By default, the Inactive Archive is Demo. To open the Archive Data Selection page 1 In the Time Frame dialog box, click Archive Chooser. The Archive Data Selection page contains a Next button, in addition to the four radio buttons listed below:
Analyze a single slice or series of slices Analyze an entire archive file Use data from the Active Archive Use data from the Inactive Archive demo (or change the inactive archive label)
14
After the data has been selected, click Next and Precise for J2EE automatically loads it into the Analysis Agent. Archived Data Summary pages containing the same information as the JVM Data Summary pages are then generated and displayed.
The table below describes the archive data selection options. Table 2-3 Option
Analyze a single slice Analyze an entire archive file Use data from the Active Archive Use data from the Inactive Archive
Archive Data Selection page options Description

Allows you to load a single time slice from the selected archive and view its data in bar graphs. Allows you to load all the slices in the archive. Enables you to load archive data from the active archive. The active archive contains the most recent data accumulated by Precise for J2EE. Allows you to load archive data from an inactive archive, such as Demo. If the data that you want to analyze is not part of the selected Inactive Archive, click the change the inactive archive label hyperlink. Then type overflow or the name of an inactive archive that you have previously imported. See the Precise Administration Guide for information on exporting and importing archive data. Opens the Archive File Selection page where you select the file to display from the archive.
Next
About the Archive File Selection page

When you click the Next button in the Archive Data Selection page, the Archive File Selection page opens. This page displays a list of items that represent archive files stored under the active or inactive archive label that you selected in the Archive Data Selection page. Each archive file represents a 24-hour span of data slices that were previously collected from the displayed JVM and Host. The Archive File name indicates the logical begin time of the 24-hour span of slices stored in the file. If there is no data collected for the period, an Archive File will not be displayed. To the right of the Archive File name is displayed the number of slices in the file followed by Service Request Average Completions per slice. The Slice Count is the number of slices in the archive file. The performance summary shows the performance across all of the slices in the archive file as a value and a bar chart. The bar chart allows you to easily compare performance of slices contained in the archive files. For the Active archive, the metric title and value will change automatically depending on the navigation context when this page was opened, for example, from Precise Insight. Click the hyperlinked text of the archive file to select it. If you chose to analyze the entire file in the Archive Data Selection page, the JVM Data Summary page will be displayed. If you chose to analyze a time slice, the Archive Slice Selection page will be displayed, enabling you to specify which time slice you want to analyze.
About the Archive Slice and Series Selection page

If you chose to analyze a single time slice in the Archive Data Selection page, the Archive Slice and Series Selection page opens when you select the archive file in the Archive File Selection page. This page displays a list of items that represent time slices stored in the archive file you selected in the Archive File Selection page. Each item contains begin and end radio-button selectors, begin and end time of the slice, the aggregation interval, and a performance summary of activity. Click the begin and end radio-buttons to select the beginning and ending of the period to display. The begin and end may be the same or different slices. The performance summary shows the performance of each slice as a value and a bar chart. The bar chart allows you to easily compare performance of slices. The metric title and value will change automatically depending on the navigation context when this page was opened. This page is opened from Precise products such as Precise Insight, to provide an opportunity to select a smaller sub-range of slices from a long time range. Click the begin and end radio button for one slice or a range of slices and then click the Next button to load the data into the Analysis Agent. If you want to select an ending slice from the next archive file, select the last item in the slice list as the ending slice and click the Next button to display the slices from the next archive file.
Precise for J2EE Basics About administration pages
15
Selecting data for analysis

The display of the most recent time slice or series is updated periodically as new data is collected. For extended detailed analysis, it is recommended that you select a previous time frame to analyze so that you are using a static view of the data. To select data to analyze 1 2 3 4 In any workspace, select the JVM (Instance) whose data you want to analyze. In the Time Frame drop-down list, choose the time frame to analyze. If the time frame is not in the drop-down list, select More.... In the Time Frame dialog box, choose an archive file, JVM, and time frame, and click OK, or click Archive Chooser and select archived data.
About the Loading data... message

Precise for J2EE displays the Loading Data... message when you click hyperlinked user interface features in Precise for J2EE. The Loading Data... message indicates that data for the next page is being loaded into the Analysis Agent from the Precise for J2EE database. After the data has been loaded, Precise for J2EE generates the page for the selected data. Click the Back button of your browser to stop loading data. Loading files that are not helpful to the user may slow down the loading process. To learn how to reduce the loading time, contact Precise Technical Support.
About administration pages

The Precise for J2EE user interface contains pages for configuring the user interface and how data is displayed. Other pages are used to configure how Precise for J2EE collects data. See About the Java Virtual Machine Settings Administration page on page 15. See About the Java Virtual Machine Settings page on page 16. See About the FocalPoint Administration page on page 18. See About the Findings Administration page on page 20. See About the Business Transactions Administration page on page 27. See About data collection in Precise for J2EE on page 29.
About the Java Virtual Machine Settings Administration page

The Java Virtual Machine Settings Administration page enables you to modify the configuration of data aggregation and collection for each Precise for J2EE Collector and monitored JVM. This page also allows you to configure instrumentation and Application Server Metrics for each monitored JVM. To open the Java Virtual Machine Settings Administration page
In the General Options bar, click Settings.
About the Monitoring Configuration page

The Precise for J2EE Collector has its own Monitoring Configuration page which automatically opens to the JVM tab. From the Settings page, you can click the Monitoring Configuration hyperlink to open and configure any J2EE Collector settings. To view the Monitoring Configuration page 1 In the General Options bar, click Settings.
16
Click the Monitoring Configuration hyperlink to view the Monitoring Configuration dialog. See About Monitoring Configuration on page 29.
Note: Though not recommended, you can also configure instrumentation manually. See About custom instrumenter configuration on page 93.
About the Java Virtual Machine Settings Administration options

The table below shows the Java Virtual Machine Settings Administration options. Table 2-4 Option
Collector
Java Virtual Machine Settings Administration options Description

List of installed Collectors. Selecting a Collector causes the JVMs served by that Collector to be displayed in the Java Virtual Machine list. Identifies the name of a JVM monitored by the selected Precise for J2EE Collector. Selecting a JVM enables the settings icons used to configure the selected JVM. The list of JVMs contains the monitored JVMs for your role(s). Opens the Java Virtual Machine page with controls for editing the current JVM-specific settings. See About the Java Virtual Machine Settings page on page 16.
Java Virtual Machine
Instrumentation
Collection & Filtering
Opens the Java Virtual Machine page to view or modify start-up settings, aggregation interval, and other JVM-specific options. Opens the Statistics Administration page with controls for selecting application server metrics to be collected for the specified JVM. See About the Statistics Administration page on page 44.
Statistics
Run Adaptive Instrumentation now
Opens the Adaptive Instrumentation Wizard page where you configure and run Adaptive Instrumentation. See About the Adaptive Instrumentation Wizard page on page 38.
Run Copy Instrumentation now
Opens the Copy Instrumentation Wizard page where you can copy instrumentation configuration files from one JVM to another. See About the Copy Instrumentation page on page 46.
Open Expert Configuration
Opens Expert Configuration where you can manage the instrumentation of the selected JVM at the method level. See About the Expert Configuration page on page 42.
About the Java Virtual Machine Settings page

The Java Virtual Machine (JVM) Settings page enables you to edit the current settings for the JVM selected in the Java Virtual Machine Settings Administration page. To open the Java Virtual Machine Settings page 1 In the Java Virtual Machine Settings Administration page, click Settings. The Java Virtual Machine Settings page contains OK and Cancel buttons, in addition to the options described in the table below.
17
The table below describes the Java Virtual Machine Settings options. Table 2-5 Option
Instrumentation Mode
Java Virtual Machine Settings Description

Controls the trade-off between increased application visibility and the increased overhead resulting from higher levels of instrumentation.

Basic mode provides visibility of common J2EE interfaces, while keeping overhead low. Standard mode provides visibility of common J2EE interfaces as well as non-standard Java/J2EE components, but with limited instrumentation and flexibility to add additional instrumentation. Expert mode provides maximum visibility and flexibility but with higher overhead.
Clicking Click here for information about Instrumentation Modes displays information about when to use each mode. See About instrumentation modes on page 33. Leak Seeker Track Select the data that Leak Seeker collects. Leak Seeker can collect data on leaking Java objects, and the largest leaking collections, arrays, and string buffers. By default, Leak Seeker is not enabled. Objects: Leak Seeker reports the allocation sites with most live objects, excluding collections, arrays, and string buffers. Collections: Leak Seeker reports allocation sites for the collections with the largest number of objects. The size reported aggregates the size of all objects contained in the collections allocated at that site. Arrays: Leak Seeker reports allocation sites for the arrays with the most objects. The size reported is a sum of the sizes of the arrays allocated at that site. String Buffers: Leak Seeker reports allocation sites for string buffers with the most entries. The size reported is the sum of all the sizes of the data buffers allocated that site. Note: When enabling LeakSeeker, we recommend that you first enable Leak Seeker Track Objects since collecting this data uses fewer resources (execution time and memory). Only use Leak Seeker Track Collections, Arrays, or String Buffers when you suspect they are the source of the memory leaks. The number of objects tracked is limited and an error message will be displayed when the limit is reached. Note: After enabling Leak Seeker, you must restart the JVM. Aggregation Interval Controls the time span over which the Precise for J2EE Collector aggregates JVM data. At the end of this interval, the summarized data is sent to the Archive Agent. This interval comprises one time slice of data. Note: Shorter aggregation intervals cause more data to be transferred to the Precise for J2EE database. When a lot of data is being collected and reported about the monitored application, you may notice slower performance if the aggregation interval is less than five minutes. As a general rule, aggregation intervals less than five minutes are not recommended for production environments. Memory/Garbage Collection Interval SQL Statements Collected per Context Minimum threshold for SQL statements to collect Enable IXP Direct Connect for this JVM Controls the time interval used for JVM memory data gathering.
Controls the maximum number of top-N SQL statements collected for each JDBC invocation.
Controls the minimum threshold for collecting SQL statements.
Controls whether Expert Configuration connects directly to the monitored JVM instead of getting its data through the Precise for J2EE Collector. Enabling IXP Direct Connect improves the performance of Expert Configuration. Available when IXP Expert Configuration Direct Connect is enabled. Specifies the port number that Expert Configuration uses to connect to the monitored JVM when IXP Direct Connect is enabled. By default, the port number is 20764, but any port number can be used as long as that port has been opened. Note: If Expert Configuration Direct Connect is enabled for more than one JVM running on the same machine, each JVM must be assigned a unique port number.
Expert Configuration Direct Connect Port
18
Table 2-5 Option
Java Virtual Machine Settings Description

Enables the user to define any of the following:

Filtering methods
no filtering - all data will be collected filter by percent of total response time - filters all execution trees where total response time % was less than the defined threshold
Note: The total response time % is calculated by finding the relative percent of the execution tree from all execution trees response time in the time slice.
filter by average response time - collect only execution trees which had an average response time greater than the threshold
About the FocalPoint Administration page

The FocalPoint Administration page lets you do the following:

Configure the user interface Select an inactive archive to analyze Modify the archiving, display, and Archive Agent network configuration Select Oracle or MySQL as the Precise for J2EE short-term database Enable HTTPS for communication between the user interface and the Precise for J2EE FocalPoint
To open the FocalPoint Administration page 1 In the General Options bar, click Settings. Then click the FocalPoint tab. The FocalPoint Administration page contains an Update button, in addition to the information contained in the table below. The values displayed on this page are the current values of the FocalPoint and are not saved on a per user basis. Click Update to save any changes made on this page.
About Layout Options

The table below shows Layout Options. Table 2-6 Option
Refresh Enabled?
Layout Options Description

Controls whether or not automatic page refresh is enabled in the user interface. If this check box is not selected, the automatic page refresh feature for all Current and Recent pages is disabled. Note: You can still select the browsers Refresh button to refresh page contents. Alternately, the Refresh button in the General toolbar can be used to enable or disable refresh for a given browser session independent of this configuration.
Refresh Interval
Automatic page refresh timer. When refresh is enabled, the Current and Recent pages are refreshed at this interval. Controls the number of plotted time series line graph items in Recent and Archive series pages.
Recent Items Charted Recent Slices
Controls the number of time slices plotted in time series graphs. These time slices are stored in the archive for each JVM monitored by the Precise for J2EE Collector. Each time slice summarizes JVM activity for the aggregation interval specified in the Java Virtual Machine Settings page. Controls whether the Dashboard or Activity workspace is the home page for Precise for J2EE. When the Activity workspace is used as the Precise for J2EE home page, the first page displayed in the Activity workspace is the Java Virtual Machine Summary page. When the Dashboard is used as the home page, the first page displayed when moving to the Activity workspace is the JVM Data Summary page for the JVM chosen in the Dashboard.
Start Page
19
About Archiving Options

The table below shows Archiving Options. Table 2-7 Option
Aging Timespan
Archiving Options Description

Controls the time span, in hours, of Precise for J2EE Collector data stored in the active archive. For example, to keep one week of recently collected data, the aging time span should be set to 168 hours = 7 days * 24 hours per day. When data is older than this time span, and Overflow is disabled (not selected), the data is deleted from the archive. The Archive Agent periodically scans the age of data stored in the archive. If data is older than the Aging Timespan, the old data is either deleted or labeled as overflow and not deleted. If this check box is selected, old active archive data is labeled as overflow and not deleted. If this check box is clear, old active archive data is deleted. Overflow data is not actively managed by Precise for J2EE, and significant amounts of data may accumulate. To analyze overflow data, change the Inactive Archive Data label to overflow in the Archive Data Selection page. Note: The overflow archive should rarely be enabled, because storing and displaying large amounts of data may impede the performance of the Precise for J2EE user interface. Instead, when you want to retain interesting or critical data, add data to the Demo archive folder or create your archive folder using the data export and import scripts. For details on using these scripts, see the Precise Administration Guide.
Overflow Enabled
Inactive Archive Label
Inactive archives, such as the Demo archive that is delivered with Precise for J2EE, are used to permanently store interesting sets of data. By default, the inactive archive, Demo, is selected. To change the inactive archive that is available for analysis, type overflow, if overflow is enabled, or type the name of another inactive archive that you have imported. See the Precise Administration Guide for information on exporting and importing archive data.
About Database Options

The table below shows Database Options. Table 2-8 Option
Database Type Host Port User
Database Options Description

Select the Precise for J2EE short-term data repository. Database host name Database port number User name that Precise for J2EE uses to connect to the Oracle or MySQL database. By default, the user is Indepth. If you have customized the user name, enter it here. Password that Precise for J2EE uses to connect to the Oracle or MySQL database. By default the password is Indepth. To change the password, enter a new password here. Name of the database, also known as the database SID. If you have customized the database name, enter the new name here.
Password
Database Name
Switching from MySQL to Oracle

When the Precise for J2EE FocalPoint is installed, a MySQL database instance is installed as the short-term data repository. If you have Oracle installed, you can create Precise for J2EE database schemas and use Database Options to configure Oracle database information. The process to switch from MySQL to Oracle requires that you first run scripts to create a new Oracle schema. Then you use the Precise for J2EE User Interface Settings page to configure the FocalPoint to use the Oracle database. For information on the scripts to create the Oracle schema, see the Precise Administration Guide.
20
To switch from MySQL to Oracle 1 Write down the database information for the Oracle database. You will enter this information when running the scripts and when updating the database information in the FocalPoint Administration page. Identical information must be entered in both places. Run the scripts to create the Precise for J2EE schema in the Oracle database. If you wish, you can also customize the username and password that Precise for J2EE uses to connect to the database. Information on the scripts and customization can be found in the Precise Administration Guide. In the FocalPoint Administration page, select Oracle as the database type. In the FocalPoint Administration page, enter the host name and port number for the Oracle database. If you have customized the user name, password, or database name, enter the names in the appropriate text fields. Warning: Enter the information exactly as it was entered in the Oracle scripts. If you update the FocalPoint Administration page with different information, you will not be able to communicate with the FocalPoint. For more information, see the Precise Frequently Asked Questions. 5 6 7 Click Update. Restart the Precise for J2EE FocalPoint. (Optional) Stop the MySQL database by running: UNIX: <i3_root>/products/j2ee/bin/stopMySQL.sh Windows: <i3_root>\products\j2ee\bin\stopMySQL.bat
3 4
About Security Options

The Precise for J2EE FocalPoint communicates via HTTP or HTTPS with the Precise for J2EE user interface. By default, HTTPS is not enabled. To enable HTTPS, you must select HTTPS Enabled, then restart the FocalPoint. When you do this, a digital certificate is installed with the Precise for J2EE FocalPoint. You can also create and install your own self-signed certificate. For information on installing your own certificate, see the Precise Administration Guide. Note: To launch J2EE FocalPoint from Precise or vice-versa, both must be able to communicate using the same protocol, namely HTTP or HTTPS.
About the Findings Administration page

The Findings Administration page allows you to configure the thresholds for Findings analysis and graph display. You also use the Findings Administration page to select the contributor category and application summary analyses. To open the Findings Administration page 1 In the General Options bar, click Settings. Then click the Findings tab. The Findings page contains an Update button, in addition to the information described in the table below. The values displayed in this page are the current values of the system. Click Update to save any changes made on this page.
21
About the Findings Analysis and Graph options

The table below shows the Findings Analysis and Graph options. Table 2-9 Option
High Contribution Red Threshold >= Medium Contribution Orange Threshold >= Low Contribution Yellow Threshold >=
Findings Analysis and Graph options Description

Threshold for identifying nodes as high contributors. Nodes whose values equal or exceed this value are filled red. The default high contribution threshold is 15%. Threshold for identifying nodes as medium contributors. Nodes whose values equal or exceed this value are filled orange. The default medium contribution threshold is 7.5%. Threshold for identifying nodes as low contributors. Nodes whose values equal or exceed this value are filled yellow. The default low contribution threshold is 1%. Note: Low Contribution Yellow Threshold >= Hotspots methods are hidden when their contribution is less than this value.
See About the Memory workspace on page 88.
About the Call Graph threshold options

The table below shows the Call Graph threshold options. Table 2-10 Option
High Contribution Red Threshold >= Medium Contribution Yellow Threshold >= Low Contribution Green Threshold >= Very Low Contribution Gray Threshold >= this value
Call Graph threshold options Description

Threshold for identifying nodes as high contributors. Nodes whose values equal or exceed this value are filled red. The default high contribution threshold is 15%. Threshold for identifying nodes as medium contributors. Nodes whose values equal or exceed this value are filled yellow. The default medium contribution threshold is 7.5%. Threshold for identifying nodes as low contributors. Nodes whose values equal or exceed this value are filled green. The default low contribution threshold is 1%. Graph nodes and Hotspots methods are hidden when their contribution is less than this value. The default minimum contribution percentage is 0.1%.
About the Call Graph configuration options

The table below shows the Call Graph configuration options. Table 2-11 Option
Maximum Disk Cache Size
Call Graph configuration options Description

Sets the maximum disk space allotted for caching Method Call graphs. Each hour, Precise for J2EE checks the size of the cache and removes the oldest data, if the maximum disk cache size has been exceeded. The default maximum disk cache is 200 MB. Set the height and width in pixels of Method Call graph panels.
Method Call Graph Layout Screen Size
About Contributors by Category Page Analysis options

Precise for J2EE Findings analyzes numerous categories of significant contributors including categories specific to application server vendors and categories applicable to all application servers. By default, all categories are enabled. Methods matching enabled categories appear in the Activity workspace Findings on the Highlights tab and can be displayed in a SmarTune portlet on the Dashboard. Findings analyzes methods using the first contributor category
22
appropriate for that method. If a category is not enabled (not selected), Findings analysis does not attempt to apply the category to the method. The table below explains each WebLogic contributor category. Table 2-12 WebLogic contributor categories Description of Findings analysis
Contribution of stateless session beans as measured from the application server's pool. Contribution of stateful session beans from the application server's cache as measured by the ejbActivate() and ejbPassivate() methods of the EJB life cycle. Contribution related to entity bean persistence as measured by the ejbLoad() and ejbStore methods of the EJB life cycle.
Contributor category
Stateless Session EJB Stateful Session EJB
Entity EJB
The table below explains each WebSphere contributor category. Table 2-13 WebSphere contributor categories Description of Findings Analysis
Contribution related to EJB cache performance as measured by the create method of the EJB life cycle. Contribution of stateful session beans from the application server's cache as measured by the ejbActivate() and ejbPassivate() methods of the EJB life cycle. Contribution related to entity bean persistence as measured by the ejbLoad() and ejbStore methods of the EJB life cycle.
Contributor Category
EJB Cache
Stateful Session EJB
Entity EJB
The table below explains each Oracle contributor category. Table 2-14 Oracle contributor categories Description of Findings Analysis
Contribution of stateless session beans as measured from the application server's pool. Contribution of stateful session beans from the application server's cache as measured by the ejbActivate() and ejbPassivate() methods of the EJB life cycle. Contribution related to entity bean persistence as measured by the ejbLoad() and ejbStore methods of the EJB life cycle.
Stateless Session EJB Stateful Session EJB
Entity EJB
The table below explains contributor categories that apply to all application servers. Table 2-15 General contributor categories Description of Findings Analysis
Contribution of obtaining database connections from a database pool as measured by the getConnection() method of the JDBC API. Contribution of database queries as measured by execute(), executeQuery(), andexecuteUpdate() methods of the JDBC API. Contribution of database activity outside the scope of SQL Access methods. This category measures JDBC API calls for instrumented invocations of type JDBC such as ResultSet processing methods or closing of database connections. Contribution of EJB activity as measured by all other EJB business methods (instrumented invocations of type EJB) not designated as vendor-specific life cycle methods identified by the previous categories.
JDBC Connection Pool
SQL Access
JDBC Access
EJB Access
23
Table 2-15
General contributor categories Description of Findings Analysis

Contribution of naming and directory services as measured by the lookup() method of JNDI. Contribution of getSession() time to HTTP service requests. Contribution of XML activity as measured by the instrumentation of XML parsers, transformers, DOM, xerces, and xalan. Contribution of JMS activity as measured by the instrumentation of javax.jms.* implementations. Contribution of JMS activity as measured by the instrumentation of general javax.transaction.* implementations and vendor specific implementations. Contribution of Java IO activity as measured by the instrumentation of java.io.* implementations. Contribution of Java IO activity as measured by the instrumentation of java.xml.soap, rpc, ws, and registry implementations. Contribution of accessing synchronized code as measured by the instrumentation of synchronized code blocks or methods. Contribution of methods that exceed the minimum contribution percentage but which are not analyzed by any other categories.
JNDI Access HTTP Session Access XML Access
JMS Access Java Transaction Access
Java IO Access Web Services Access
Synchronized Method Access Application Methods
About Findings Application Summary categories

Findings analyzes numerous application server performance categories, including many for specific application server vendors and versions. The Statistics workspace can be displayed in a Findings Application Summary portlet on the Dashboard. If a category is not enabled (not selected), Findings does not attempt to analyze the category. The table below explains application summary categories. Table 2-16 Application summary categories Description of Findings Analysis
Identifies a downward trend of free heap memory. Identifies excessive usage of the heap. Identifies excessive time spent in the Garbage Collection activity. Identifies an upward trend of concurrent active threads, which can indicate an increasing load on the JVM.
Application Summary Category

Maximum Free Memory Heap Used Memory Garbage Collection Time Concurrent Active Threads
The table below explains WebLogic 8.1 application summary categories. Table 2-17 WebLogic 8.1 application summary categories Description of Findings Analysis
Evaluates if Idle threads are available.

ExecuteQueue Idle Threads Shortage Database Connection Availability
Evaluates if Idle Database Connections are available.
24

ExecuteQueue Idle Threads Shortage Database Connection Availability Waiting for Database Connection Leaked Database Connections JMS Consumer Messages Pending JMS Producer Messages Pending
Evaluates if database connection requests are waiting.
Evaluates if database connections are leaked.
Evaluates if consumer message pending count is greater than zero.
Evaluates if producer message pending count is greater than zero.

ExecuteQueue Idle Threads Shortage Database Connection Availability Waiting for Database Connection Leaked Database Connections JMS Server Messages Pending JMS Session Messages Pending
Evaluates if server message pending count is greater than zero.
Evaluates if session message pending count is greater than zero.

ExecuteQueue Idle Threads Shortage Database Connection Availability Waiting for Database Connection
25
Table 2-20
WebLogic 9.2 application summary categories Description of Findings Analysis


Leaked Database Connections JMS Server Messages Pending JMS Session Messages Pending

ExecuteQueue Idle Threads Shortage Database Connection Availability Waiting for Database Connection Leaked Database Connections JMS Server Messages Pending JMS Session Messages Pending
The table below explains WebSphere 5.0 application summary categories. Table 2-22 WebSphere 5.0 application summary categories Description of Findings Analysis
Evaluates if maximum available threads are in use.

Thread Pool Maximum Threads in Use Database Connection Pool Maximum Connections in Use Waiting for Database Connection
Evaluates if maximum available connections are in use.

Thread Pool Maximum Threads in Use
26
Table 2-23
WebSphere 5.1 application summary categories Description of Findings Analysis


Database Connection Pool Maximum Connections in Use

Thread Pool Maximum Threads in Use Database Connection Pool Maximum Connections in Use

Thread Pool Maximum Threads in Use Database Connection Pool Maximum Connections in Use
The table below explains Oracle 10.1.2 application summary categories. Table 2-26 Oracle 10.1.2 application summary categories Description of Findings Analysis
Evaluates the JDBCDriver for leaked connections when a connection was obtained from the connection pool and never returned.

JDBC Connection Leak
The table below explains Oracle 10.1.3 application summary categories. Table 2-27 Oracle 10.1.3 application summary categories Description of Findings Analysis
Evaluates the JCAConnectionPool for opened JCA connections that were obtained from the pool and never closed.

JCA Connection Leak
The table below explains SAP 6.4 application summary categories. Table 2-28 SAP 6.4 application summary categories Description of Findings Analysis
Evaluates Application Thread Pool size.

Application Thread Pool Availability
27
Table 2-28
SAP 6.4 application summary categories Description of Findings Analysis

Evaluates Thread Pool size.

Application Thread Pool Waiting Tasks
Application Thread Pool Evaluates Application Thread Pool size. Waiting Tasks Queue Overflow System Thread Pool Availability Managed Connection Pool Availability Evaluates System Thread Pool Size.
Evaluates Managed Connection Pool Size.
About the Business Transactions Administration page

Business transactions are named groups of HTTP or EJB service requests that Precise for J2EE has already identified as service time contributors. Setting up a business transaction allows you to display aggregated data for the group of methods in the Dashboard and Activity workspaces. You use the Business Transactions Administration page to create or modify business transactions. To open the Business Transactions Administration page
In the General Options bar, click Settings. Then click the BusinessTransactions tab.
The Business Transactions Administration page contains the options shown in the table below.
About the Business Transactions Administration options

The table below shows the Business Transactions Administration options. Table 2-29 Option
Current Business Transactions
Business Transactions Administration options Description

Lists business transactions that have been created. You can select a business transaction from the list to view, edit, or delete. Opens the Create New Business Transaction page. You can name a new business transaction, select the JVM for which it will be configured, and add contexts for the business transaction. Opens the Create New Business Transaction page with the method calls included in the selected business transaction. You can add or remove method calls from the business transaction and assign or remove the business transaction to all or selected JVMs. Note: At times, you may notice that data on a business transaction changes or disappears, even though the methods appear to be part of the business transaction. This is a result of changes in instrumentation made by Adaptive Instrumentation or Over-Instrumentation Protection. For example, if Adaptive Instrumentation was run after the business transaction was created, Adaptive Instrumentation may have disabled instrumentation for methods that were included in the business transaction in order to meet the overhead budget. As a result, the business transaction will not display data or the data displayed may be incomplete, even though you see that the methods are included in the business transaction.
Create New
View/Modify
Delete
Deletes the selected business transaction. Note: Delete Selected removes the business transaction from all JVMs. To remove the business transaction from specific JVMs, use View Selected.
Precise for J2EE Basics About the System Status page
28
Creating a business transaction

Creating a business transaction requires familiarity with your application's top-level methods. In addition, if your application uses a Model View Controller (MVC), you will need to turn on parameter capture in Precise for J2EE, so that method names and parameters will be displayed when searching for method calls to include in the business transaction. See the Precise Administration Guide for information on configuring Precise for J2EE to use parameter capture. To create a business transaction 1 2 3 In the Business Transactions Administration page, click Create New. In the Business Transaction name field, enter a name for the business transaction. Select the JVM(s) where the business transaction will be available. Click All JVMs, if you want the business transaction to be available on all JVMs. To create the Business Transaction for a specific JVM, click Selected JVMs, then select the JVM in the list. Click Add Context(s) to add method calls to the business transaction. Search for the method calls by entering the exact class or method name, or use the wildcard character, *, then click Search. Search returns methods running on at least one selected JVM that match the search criteria. Only HTTP or EJB service requests can be assigned to a business transaction. In addition, methods must be uniquely assigned to business transactions, so a given method can belong to only one business transaction. In some cases, search results may contain the same class and method multiple times. This occurs because the application calls the class and method from different threads, but Precise for J2EE cannot distinguish the top-level entry point. In this situation, you should include all identical classes and methods of interest in the business transaction. In the list of search results, check the box(es) beside the methods you want to include in the business transaction. To select all of the check boxes, click Select All. To unselect all of the check boxes, click None. To invert current check box selections, click Invert. To add the methods to the business transaction, click Add. In the Create New Business Transaction page, click Save.
4 5
6 7 8 9 10 11
About the System Status page

When you click Settings, and then Status in the General Options bar of any Precise for J2EE page, the General Toolbar displays the Status link to open the System Status page. The System Status page displays the overall status of each Precise for J2EE component. The Host:Port, Active and Status headings are shown for each component. It also enables you to access detailed status information for each component by clicking the Details hyperlinked text to the right of the status indicator of each component. In addition, this page enables you to access the Administration page for each component by clicking the components hyperlinked text or by clicking Configure in the General toolbar. See About data collection in Precise for J2EE on page 29. The System Status page displays the host name and port number used by each Precise for J2EE component to the right of the component name. The System Status page uses the following activity and status icons:
The component is Active and responds when the user interface tries to communicate with it using the displayed host name and port number The user interface does not receive an expected response when communicating with the component The component is running normally and no problems have been detected. Severity = Normal
Precise for J2EE Basics About data collection in Precise for J2EE
29
The component has encountered a problem. User intervention is recommended. Severity = Moderate The component has encountered a serious problem that has impacted the collection or archiving of data. Immediate user intervention is recommended. Severity = High
About the Status Details page

Each Precise for J2EE component (user interface, Analysis Agent, Archive Agent, and Precise for J2EE Collector) has its own Status Details page. The layout of the page is the same for all components. Each message contains a status indicator, the source or value of the message, and a description of the problem. To open the Status Details page 1 2 In the General Options bar, click Settings, and then Status to open the System Status page. In the System Status page, click the Details hyperlink to the right of the status indicator for an Precise for J2EE component.
About data collection in Precise for J2EE

Default Precise for J2EE instrumentation collects data on Java entities, memory usage, locks, exceptions, and other categories that affect application server performance. Precise for J2EE also allows you to visualize and customize data collection using one of the following features:

About Monitoring Configuration About the Pattern Manager About instrumentation modes About Adaptive Instrumentation About Expert Configuration page About the Statistics Administration page About the Copy Instrumentation page Troubleshooting memory and adjusting heap sizes
Note: Automatically loading classes onto a computer may be very time consuming because some of the loaded files are not helpful to the user. To shorten the loading time, the user can list specific class names to be ignored during loading. For more details, contact Precise Technical Support.
About Monitoring Configuration

Monitoring Configuration in Precise for J2EE enables the user to easily view and edit JVM instrumentation definitions that influence application monitoring. Monitoring Configuration displays the impact of the definitions on the actual instrumentation status of the application methods. At the top of the screen, the selected JVM name appears and its last updated start time (date and time). Last Updated on (start time) displays the date and time when the classes were last updated. JVM Loaded Classes display (in parenthesis) the total number of known classes that were loaded in the JVM based on the last updated time. Note: When there are no pending changes, the list in the table displays actual monitoring status of classes and methods in the JVM. If pending changes exist, the list in the table displays estimated status of classes and methods in the JVM.
30
About Monitoring Configuration icons

On the Monitoring Configuration page appears a number of icons.
Table 2-30 Icon

Search
Monitoring Configuration icons Description

Appears next to the searching fields. Clicking this icon activates the search in the Loaded Classes and Methods table. Appears next to the searching fields. Clicking this icon clears the search fields and shows unfiltered results in the Loaded Classes and Methods table. Click the refresh icon to retrieve currently loaded classes and methods from the JVM while updating the table and the Last updated on time. When the user clicks Save, this special warning icon (both at the top of the screen and in a popup message) displays if there exist pending changes. When the user clicks Save, this error icon (both at the top of the screen and in a popup message) displays if there is a parsing error in the custom.xml file.
Clear
Refresh
Warning
Error
About selecting a pattern for editing or viewing matching loaded classes and methods
There are 4 user-selectable editing or viewing options:

All Classes and Methods - shows all loaded default classes and associated methods (no filtering by status) Configured (Monitored & Blocked) - shows all statuses except for <blank> that are retrieved (for example: classes and methods including monitored, monitored (partial), pending, etc) Not Configured - shows only <blank> and pending statuses that can be retrieved Pending - shows only pending statuses
The selected view is applied directly by clicking on one of the above relevant viewing options. In addition to selecting a view option, the user can also apply search criteria. There are also options available for search (filtering) patterns:

Package/Class pattern Method pattern
Click the Search (spyglass) icon to search and select an already existing pattern name, or begin typing a pattern name into the appropriate field. Precise for J2EE has a unique auto-complete feature which displays a list of all pattern names with letters that match the typed letters in the field. The table displays results based on the selected viewing option and the search criteria. Click the Clear (X) icon to clear any searched pattern name, or simply delete the pattern name field content. See About Monitoring Configuration icons on page 30.
About Monitoring Configuration results

The table displays the results (actual instrumentation status) for the selected viewing option. By default, the first row in the table is always selected (shown in gray). The result table shows classes in pages of 100 classes. Paging icons are available at the lower right side of the table, along with the total number of classes. The classes in the results table are collapsed and can be extracted by clicking the plus icon. When extracted, the members that apply to the filter and search criteria will be shown. If All Classes and Methods was the selected viewing option, the table displays the following results:

Class (the class name) Method (the method name)

31
Status (See About Status values on page 31.) Type Notes (additional information for a specific class) Note: JDBC methods will not appear in the loaded methods list. Methods invoking JDBC calls will appear with an indicator in the Notes column as Calls JDBC methods.
Class names are sorted in alphabetical order. If a class is expanded, by default methods are sorted alphabetically.
About Status values

Status can have any of the values shown below in the table.
Table 2-31 Name

Monitored
Available Status values Description

For a class, it means that all of its loaded methods are instrumented. For a method, it means that the method is instrumented.
Monitored (partial)
For a class, it means that only some of its loaded methods are instrumented. For a method, it means that only some of the signatures are instrumented.
Blocked
For a class, it means that all of its loaded methods are ignored. For a method, it means that it is ignored.
Blocked (partial)
For a class, it means that all of its loaded methods are either ignored (exists at least once) or not instrumented (exists at least once). For a class, it means that all of its loaded methods are not instrumented (but not ignored). For a method, it means that it is not instrumented (not ignored).
<Blank>
Pending
Relevant for classes or methods after a change was performed and the JVM was not restarted. The Class will have a pending status if it has at least one pending method.
About Type values

The type is used to categorize classes and methods as meaningful parts of the monitored application. Predefined types can contain HTTP, EJB and others. User defined types can be added when defining classes/methods to be monitored. (If no type is defined, the Custom default type is used.) The types are the foundation for displaying service time breakdown into its components in the Precise for J2EE User Interface (for example, how much time is spent in EJBs or in JDBC methods). The type of methods is either defined by the user, or by the products predefined definitions. The type of classes can be defined by the user or by the products predefined definitions, or (when no specific definition exists) as a combination of all of its methods types.
About Monitoring Configuration controls

Monitoring Configuration enables the user to easily view and edit monitoring status of the loaded classes or methods. It covers a broad spectrum of use cases, serving both novice and experienced users. Use Monitoring Configuration to monitor the status of classes and methods directly, or via the Manage Patterns screen. Class names are shortened for screen display and method names are displayed without a signature. In the case of an error while reading (parsing) Monitoring Configuration, an error icon and message will appear.
32
Note: A Pending Changes message will appear at the top of the screen after the user has made any changes to instrumentation definitions, and restart has not yet been performed. If the Monitor button is enabled, the user can monitor a selected row in the table according to class or method status and view the class and method results. To monitor one or more loaded classes or methods 1 2 3 In the table, click to select one or more loaded classes or methods for monitoring. Click Monitor. Click Save to save your changes, or Cancel to close the screen without saving changes. Note: Restart JVM after saving your changes. The user can stop monitoring a selected row in the table according to class or method status. To stop monitoring a loaded class (classes) or methods 1 2 3 In the table, click to select one or more loaded classes or methods to stop monitoring. Click Stop Monitor. Click Save to save your changes, or Cancel to close the screen without saving changes. Note: Restart JVM after saving your changes. The user can exclude a selected row in the table according to class or method status. To exclude (ignore) a loaded class (classes) or methods 1 2 3 In the table, click to select one or more loaded classes or methods to exclude. Click Exclude. Click Save to save your changes, or Cancel to close the screen without saving changes. Note: Restart JVM after saving your changes. Click Manage Patterns to edit or view the matching classes or methods. After selecting a search pattern, click Monitor Search Results to monitor the search criteria pattern. After clicking the monitor search result, assign a type to the pattern in the opened pop-up message. Use Monitor Search Results to create and monitor patterns.
About the Pattern Manager

Use the Pattern Manager to manage monitoring patterns to view or edit types and matching classes. Note: User-Defined classes can be edited (to add, edit, or delete) types, classes, and methods. At the top of the screen, the selected JVM name appears and the its Last JVM start time (date and time). The Monitoring Patterns table displays configured patterns (classes and methods, and their assigned types). Click Add Pattern (above the table) to create a new pattern name to the table. Click on the + icon in the table to open and view all members of a selected class. To add a class or method pattern 1 For a new class pattern, click Add Pattern.
33
Begin typing the class name and the Pattern Manager will automatically display current classes which start with the same matching letters. Select the appropriate class name from the list, or (for example, in case it will be deployed later to the JVM) at the right of a name in the list. For a selected class pattern, click the blank field in the Method Pattern column for the selected class row. Begin typing the method name and the Pattern Manager will automatically display current methods which start with the same matching letters. Select the appropriate method name from the list or (for example, in case it will be deployed later to the JVM) at the right of a method name that does not appear in the list.
3 4
About Pattern Manager loaded classes and methods results

The table (lower pane) displays the results (actual instrumentation status) for the selected classes or methods that match the selected definition row (upper pane). The JVM Loaded Classes and Methods displays (in parenthesis) the total number of classes that were loaded. Also displayed is the date and time when the classes were Last updated. Click the Refresh icon to refresh the screen and update all viewed data. Click on the + icon in the table to open and view all members of a selected class. The table displays the following results:

Class (the class name) Method (the method name) Status (See About Status values on page 31.) Type (the assigned type, custom by default) Notes (additional information for a specific class)
About instrumentation modes

Precise for J2EE allows users to set and modify instrumentation on the fly without the need to restart monitored applications. To provide this unique flexibility, Precise for J2EE installs smart probes in application components as they are loaded into memory. The probes can then process user requests for dynamic modification of the instrumentation set. This state-of-the-art technology comes at the cost of additional overhead to running applications. To provide users with maximum flexibility in balancing visibility versus overhead, Precise for J2EE supports three modes of instrumentation: Basic, Standard, and Expert. You select the instrumentation mode in the Java Virtual Machine Settings page. The three modes differ in the following ways:

The initial overhead (the overhead caused by the out-of-the-box monitoring probes) The flexibility users have in modifying instrumentation using advanced instrumentation tools The cost of (dynamically) instrumenting additional components or methods The need to restart the monitored application server for the changes to take effect
34
The table below describes each instrumentation mode. Table 2-32 Instrumentation modes Description
This mode provides visibility of common J2EE interfaces (JSPs, Servlets, EJBs, etc.) while keeping the overhead at the minimum. To monitor other Java/J2EE components (such as home-grown applications), you manually modify instrumentation configuration files, add the components that you need to monitor, and then restart the application server. You can use Adaptive Instrumentation in this mode to tune instrumentation for service requests and common J2EE interfaces. Use this mode if:

Instrumentation mode
Basic
You need to keep the overhead at the absolute minimum in exchange for reduced visibility. You are mainly interested in monitoring service requests and key J2EE interfaces. You are not interested in monitoring other components or alternatively, you can manually identify these components and define them in the configuration files. You are also willing to restart the application servers when you make this type of modification.
Standard
This mode provides visibility of standard J2EE interfaces as well as of non-standard Java/J2EE components. However, to keep the overhead low, Precise for J2EE applies a reduced set of its probes that provides limited flexibility. The initial overhead is relatively low in this mode, however, the cost of instrumenting additional components is higher than in Basic mode. You can use Adaptive Instrumentation in this mode to discover root causes of performance problems in non-standard Java/J2EE components. This is the default mode. Use this mode if:

Your main concern is to get good visibility of standard J2EE interfaces but you would also like to monitor other components. You prefer to rely on Adaptive Instrumentation to automatically find the best instrumentation set rather than manually configure the instrumentation.
Expert
This mode provides maximum visibility and flexibility with a higher overhead. As with the Basic mode, common J2EE interfaces are covered out of the box, but in Expert mode, you can use Adaptive Instrumentation to automatically uncover additional contributors to performance, as needed, without restarting the monitored application servers. You can also use Expert Configuration to enable or disable instrumentation of specific components. In this mode, the initial overhead is the highest, as Precise for J2EE's probes are fully deployed to provide maximum flexibility. Use this mode if:

You need to get maximum visibility and are willing to accept a higher initial overhead. You need maximum flexibility in fine-tuning the instrumentation set to provide the best visibility for a given overhead budget. You need to make frequent changes to the instrumentation set without restarting the application server.
About Adaptive Instrumentation

Adaptive Instrumentation in Precise for J2EE automates custom instrumentation to provide application information most relevant to root cause analysis of performance problems. Adaptive Instrumentation surveys application activity during a load. Then Adaptive Instrumentation analyzes the data collection results, known as survey data, to generate a custom instrumentation configuration. You control the amount of overhead that the configuration may impose on your applications performance by giving Adaptive Instrumentation an instrumentation budget. A low budget results in less instrumentation and a lower overhead, while a higher budget trades off performance for additional instrumentation and more information about your application. The figure below shows the Adaptive Instrumentation workflow.
35
Figure 2-2
Adaptive Instrumentation workflow
Tips on Adaptive Instrumentation

Adaptive Instrumentation is a powerful tool for gathering the data required for root-cause analysis of application performance problems. To get the most from Adaptive Instrumentation, you probably need to execute Adaptive Instrumentation more than once, while you keep the following tips in mind. See About the Adaptive Instrumentation Wizard page on page 38. See Procedures for Adaptive Instrumentation on page 40.
About calibration of Adaptive Instrumentation

Precise for J2EE uses byte-code instrumentation technologies to measure all Java method invocations from almost any calling context. Byte-code instrumentation is a powerful technology, but it must be used judiciously since it adds a tiny bit of processing to each instrumented method call. These processing additions can add up to higher than expected overhead, especially when an application hot spot is instrumented. An application hot spot is one or more methods invoked millions or billions of times in a short span of time. A good example of a hot spot is a set of methods inside a parser that are invoked more than 10 million times over a few minutes. Instrumenting inside application hot spots will likely cause high overhead. To avoid instrumentation inside hot spots, you run Adaptive Instrumentation twice. The first time, Adaptive Instrumentation collects data for calibration purposes. The second time, Adaptive Instrumentation collects data as a survey of the application's activity. The calibration removes the effects of hot spot monitoring overhead by ignoring highly invoked methods. Be sure that the application activity during data collection includes any highly invoked methods. You must restart the JVM after the calibration phase or the calibration results will not be applied. Note: There is no control in the Precise for J2EE User Interface to select the two data collection phases. You simply run Adaptive Instrumentation and then restart the monitored JVM. Then you run Adaptive Instrumentation again. After the calibration phase, you run Adaptive Instrumentation again to collect data on application activity. This data collection measures the application from as normal an overhead level as possible because the hot spots were
36
excluded by the calibration. Again ensure that the application activity during data collection includes any highly invoked methods. When you restart following the activity phase, any remaining or new hot spots are ignored. In some cases, you may need to perform several new activity survey data collections because elimination of one hot spot may cause another hot spot to surface.
About Adaptive Instrumentation policies

Adaptive Instrumentation determines which methods to instrument by dividing the activity recorded within the collected survey data into two categories, service requests and threads. Adaptive Instrumentation then applies a set of policies to each type of data. As each policy is applied, Adaptive Instrumentation selects methods to instrument. Adaptive Instrumentation continues applying policies and selecting methods to instrument until the instrumentation exceeds the budget in each area. You can track the application of each policy in the Adaptive Instrumentation Status page of the Adaptive Instrumentation Wizard page. The following policies are built into Adaptive Instrumentation:
Retain and Ignore Existing Instrumentation Detects and retains pre-existing (default) instrumentation. May also disable default instrumentation if the budget setting in the Adaptive Instrumentation Wizard page is set low enough. Depending on the budget setting, Adaptive Instrumentation may reduce the number of methods instrumented in Expert Configuration. Instruments additional Servlet, JSP, and EJB methods that were not detected by the first policy. Discovers and instruments Java methods that contribute the most to the application work time, and their call paths. Discovers and instruments the single longest running Java method call path. Discovers additional entry points into the other Threads area and instruments the Java methods they call. Discovers and instruments the longest service time call paths and sub-paths. This policy instruments the remaining long paths that were not found by the Longest Service Time Path policy. Discovers and ignores all instrumentation in Java application areas with highly invoked methods that would otherwise exceed the budget. A JVM restart is required to load this policys changes to instrumentation for improved visibility or lower overhead. When you first begin to monitor a Java application, create two new Adaptive Survey Data Collections and restart the JVM after each data collection, so that the Survey Calibration benefits are incorporated into your instrumentation.
Service Requests Work Time
Longest Service time Path Root Contexts
All Longest Service Time Paths Survey Calibration
About your current instrumentation

Adaptive Instrumentation works with the instrumentation currently present in the monitored application. Adaptive Instrumentation first applies the Retain and Ignore Existing Instrumentation policy to the survey data in order to select the methods to instrument. When existing instrumentation is retained, as it is by default, this policy uses the available overhead budget first for existing instrumentation at the expense of other instrumentation that would be suggested by other policies. Depending on the amount of existing instrumentation and the overhead budget you set, other policies may not be applied, or if the overhead budget setting is lower than the overhead imposed by the existing instrumentation, Adaptive Instrumentation will reduce the amount of existing instrumentation. Optionally, you can disable the Retain and Ignore Existing Instrumentation policy. In this case, Precise for J2EE ignores any default and custom instrumentation, and Adaptive Instrumentation gains full control over the enabling of instrumentation throughout the application. To disable this policy, edit the PRECISE_J2EE_HOME/config/HeatseekerPolicyConfiguration.xml file. Find the <policy> element with a <class-name> of com.precise.javaperf.heatseeker.policy.IgnoreInstrumentation and change the <enabled> element from true to false.
About the data collection period

The most critical part of Adaptive Instrumentation is the data collection period. The Adaptive Instrumentation policies use the data that is collected to decide what to instrument. Therefore, you must ensure that the data collection includes as much representative application activity as possible but excludes startup activities.
37
Before you start Adaptive Instrumentation data collection, make sure that you run at least one iteration of an application functionality test, such as a load test, or wait until your workload has exercised all the paths in the application. During this warm-up period, application pages are initialized, the underlying Java classes are loaded, and caches are created and filled. You should exclude this application initialization activity from the data collection because it is not part of the normal runtime of the application and may influence the results of Adaptive Instrumentation. In addition, you may need to lengthen the data collection phase because the application may take longer to execute its tasks. The increase in application service time is caused by monitoring overhead inside hot spots. The application service times should eventually be reduced after the calibration phase because the Adaptive Policies evaluate the instrumentation to learn where the hot spots are and avoid them. However, since Adaptive Instrumentation only analyzes the activity during the data collection, if some application activity is inadvertently excluded from the data collection because the data collection duration was too short, then some application hot spots may be instrumented. The data collection duration should be long enough for the application workload or load test to execute all application call paths. For example, the data collection period should include enough time to warm up, run, and cool down a load test. A good rule of thumb is to increase the data collection duration to 4x baseline (or more) for calibration phases and 2x for survey data collection phases. In cases of high initial overhead, you should run multiple calibration phases with an application JVM restart between each new data collection. The test itself must include all application activity to be analyzed. The activity mix should also be similar to that of the target system. If portions of the workload are not exercised, the generated instrumentation does not include the missed workload. In addition, if the workload or application structure changes, the Adaptive Instrumentation data should be collected again and the policies applied to generate new instrumentation.
About overhead budget

You usually define the final overhead budget after evaluating and comparing the differences of several different overhead budget settings. Factors such as the analysis goal, the application structure, and the workload determine what you consider an acceptable amount of overhead and level of information detail. Low levels of overhead are usually required for high volume production environments, where an overhead budget of 13% is typically sufficient for low overhead and good performance detail. Higher levels of detail and overhead are often tolerated during performance testing and development. For these activities, an overhead budget of 515% is typical. To find an acceptable balance of performance data and overhead, run Adaptive Instrumentation initially with a low overhead budget. After you have collected a set of Adaptive Instrumentation data, examine the performance data and adjust the overhead budget as needed. You can then apply the new setting without collecting additional data or restarting the monitored JVM. In some cases, as the budget is raised, the Survey Calibration policy will stop ignoring methods that were previously ignored. You can recognize this condition by examining the Survey Policy results in the Adaptive Instrumentation Wizard page. Those newly instrumented methods will not actually be instrumented and visible in the Precise for J2EE User Interface until after the monitored JVM is restarted. A higher overhead budget does not necessarily result in an increase in the count of instrumented methods. When determining the methods to instrument, Adaptive Instrumentation policies consider a number of factors, which includebut are not limited toinvocation frequency and contribution to application work time. At some point, further increasing the overhead budget does not result in additional instrumentation. Usually, this is the case when no additional methods exist, or when the remaining method invocations occur so frequently that they cannot be instrumented safely.
About JVM startup resources

Adaptive Instrumentation data collection may lengthen the JVMs startup time. To decrease the memory and CPU resources that the JVM uses during startup, you can disable survey instrumentation and survey data collection by selecting Basic instrumentation mode in the Java Virtual Machine Settings page. Typically, you should use Basic mode after Adaptive Instrumentation has generated and saved a set of suitable instrumentation results and when the workload and application is not expected to change in the near future. See Using Adaptive Instrumentation with a stable application or workload on page 42.
38
About monitoring overhead and instrumentation modes

The Java Virtual Machine Settings dialog allows you to adjust the instrumentation mode. Standard and Expert modes inject survey and conditional instrumentation into every method. The trade off for the high visibility into performance in Standard and Expert modes is higher overhead. The high overhead is temporary and may be reduced by Adaptive Instrumentation calibration. Recall, however, that you must re-start the JVM to realize the low overhead produced by the calibration. In production environments, restarting the JVM may not be possible. If this is the case, then Basic instrumentation mode should be used in those environments. You may select Basic instrumentation mode from the Settings page following the Post-Installation tasks of the AppTier, before you start the JVM to complete the installation. Basic instrumentation mode limits instrumentation to a few well known APIs, but it may not be interesting if important code is custom code. To limit the restart risk to production systems, yet instrument the code of interest, we recommend that you run Adaptive Instrumentation in your staging or test environment and verify that the performance visibility and overhead are acceptable. Then use Copy Instrumentation to move the instrumentation to the production system.
About the Adaptive Instrumentation Wizard page

The Adaptive Instrumentation Wizard page contains the settings for Adaptive Instrumentation. You run Adaptive Instrumentation for the Collector and JVM selected in the Java Virtual Machine Settings Administration page. Adaptive Instrumentation runs in all instrumentation modes. To open the Adaptive Instrumentation Wizard 1 In the Expert Configuration page or in the Java Virtual Machine Settings Administration page, click Run Adaptive Instrumentation now. The Adaptive Instrumentation Wizard page opens.
See About the Java Virtual Machine Settings page on page 16. Warning: Redeploying or restarting the application JVM that you are monitoring while running Adaptive Instrumentation data collection or analysis may cause Precise for J2EE to collect incorrect data or instrument unexpected methods. Always redeploy the application either before or after running Adaptive Instrumentation.
About the Adaptive Instrumentation Execution settings

Adaptive Instrumentation settings apply to the JVM ID that appears near the top of the Adaptive Instrumentation Wizard page. See Tips on Adaptive Instrumentation on page 35. See Using Adaptive Instrumentation for a new or changed application or workload on page 40. Note: Make sure to apply a representative load on the application at the time Adaptive Instrumentation is executing the data collection. Adaptive Instrumentation analyzes the usage patterns identified during the data collection duration. The more representative these patterns are the more effective Adaptive Instrumentation will be. The table below shows the settings that control the execution of Adaptive Instrumentation. Table 2-33 Option
Enable Adaptive Instrumentation
Adaptive Instrumentation controls Description

Checking this box enables Adaptive Instrumentation and allows you to select other Adaptive Instrumentation execution settings. Disabling Adaptive Instrumentation will remove Adaptive Instrumentation results and data collection capabilities from the JVM's configuration.
Please specify the desired The percentage in this text box defines the acceptable overhead for the generated instrumentation as a overhead budget relative percentage of application service time. Based on this setting, Adaptive Instrumentation constrains the amount of generated instrumentation and the corresponding overhead. If you want Precise for J2EE to collect additional Java method details, increase the overhead budget. If you want to reduce Java method details, lower the overhead budget. An overhead of zero disables all instrumentation.
39
Table 2-33 Option
Adaptive Instrumentation controls Description

Checking this box instructs Adaptive Instrumentation to collect new survey data and overwrite the previous survey data. When this box is checked, you can set the survey data collection duration using the Adaptive Instrumentation Data Collection Duration control. Leaving this box unchecked, enables the reuse of survey data previously collected for Adaptive Instrumentation. Note: If you select this option, Precise for J2EE does not collect new survey data and runs the Adaptive Instrumentation policies on the last set of data collected. If no survey data has been collected previously, Adaptive Instrumentation requires the collection of survey data.
Collect new Survey Data
Adaptive Instrumentation Survey Data Collection Duration
The number in this drop-down list defines the duration of the Adaptive Instrumentation data collection. During this time, the application should be exercised by user activity or a load test representative of the target runtime environment. The activity that occurs during this period is analyzed by Adaptive Instrumentation and used by the policies to select methods to instrument. Checking this box instructs Adaptive Instrumentation to apply changes made in Expert Configuration when running Adaptive Instrumentation. Applied changes will override the overhead budget setting.
Apply Changes from Expert Configuration
About the Adaptive Instrumentation progress

When the Adaptive Instrumentation Wizard runs, the Wizard displays the Adaptive Instrumentation Status page. The task bar indicates the current stage of execution. Steps 13 comprise survey data collection and are omitted if new survey data is not being collected. Click Next in the Adaptive Administration wizard to continue. The table below describes the next steps in the Adaptive Instrumentation Wizard. Table 2-34 Step
1 2 3 4 5 6 7
Next steps in the Adaptive Instrumentation Wizard Description

Begin data collection. Wait between beginning and end of data collection. During this time you should be running a load test. End data collection. Run Adaptive Instrumentation analysis. Enable Adaptive Instrumentation results to be loaded at startup. Apply results to the running JVM. Complete Adaptive Instrumentation.
The table below shows the Adaptive Instrumentation Wizard messages. Table 2-35 Adaptive Instrumentation Wizard messages Description
Displayed when you click Next. This message indicates that the collection of survey data or the Adaptive Instrumentation analysis has begun. Displayed when Precise for J2EE collects and saves the beginning or ending survey data. Displayed at the beginning of the Adaptive Instrumentation analysis. Loading the data files may take a few minutes, depending on the speed of the Agent machine and the complexity of the analyzed application. Displayed when Precise for J2EE runs instrumentation policies on the survey data. This status specifies the name of the policy being applied, such as Work Time Policy.
Status Message
Starting Adaptive
Collecting Data Now Loading Data Files
Policy Name
40
Table 2-35
Adaptive Instrumentation Wizard messages Description

Indicates the count of additional methods instrumented by the running policy and the area of the application where these methods were found. Methods can be found in the Service Request area or the Threads area. Indicates the percentage of the overhead budget for the specified application area that remains after the current policy has completed. When the remaining budget is insufficient to continue, the policies stop the instrumentation of more methods in the specified application area. Displayed when the remaining budget is insufficient to continue the instrumentation in the specified application area. In this case, the policies stop the instrumentation of methods in this area. Indicates the accumulated total number of methods instrumented by the policies for all application areas. Shows the number of methods of each types that are instrumented. Displayed when Precise for J2EE overwrites the configuration file, Heatseeker.xml, with new Adaptive Instrumentation results. Displayed when Precise for J2EE applies the new instrumentation results to the JVM using Conditional Instrumentation.
Status Message
Instrumented n Methods
Budget Remaining is n%
Budget Exhausted
Total Instrumented Method Count Saving Startup Configuration Applying Adaptive Instrumentation
Procedures for Adaptive Instrumentation

How you use Adaptive Instrumentation depends on whether the application you are monitoring is recently deployed or modified or whether the application has been deployed for some time and is stable. See Tips on Adaptive Instrumentation on page 35. See About the Adaptive Instrumentation Wizard page on page 38.
Using Adaptive Instrumentation for a new or changed application or workload

Use the following procedure if you are running Adaptive Instrumentation for the first time on a monitored application, or after a monitored application has been modified. When you execute this procedure, Adaptive Instrumentation collects survey data about your application, applies the policies to this data, and configures instrumentation that is in keeping with your overhead budget. Finally, Adaptive Instrumentation saves the instrumentation configuration and applies it to the JVM. This procedure asks you to run Adaptive Instrumentation twice to apply the results of the Survey Calibration policy. In most cases the Survey Calibration policy discovers and ignores some instrumentation in Java application areas with highly invoked methods that would otherwise exceed the budget. A JVM restart is required to load this policys changes. See Tips on Adaptive Instrumentation on page 35. To run Adaptive Instrumentation for a new or changed application or workload 1 2 3 In the Java Virtual Machine Settings page, click Run Adaptive Instrumentation now. In the Adaptive Instrumentation Wizard page, select Enable Adaptive Instrumentation. In the Adaptive Instrumentation Wizard page, use the Overhead Budget text box to specify the desired level of relative overhead available for instrumentation. Enter the overhead as a floating point number greater than or equal to zero. Verify that Collect New Survey Data is checked. If no survey data has been collected previously, Adaptive Instrumentation requires the collection of survey data. Select the Adaptive Instrumentation Data Collection Duration from the drop-down list. The monitored JVM activity that occurs within the Data Collection Duration will be analyzed by Adaptive Instrumentation. Be sure to select a sufficiently long duration.
4 5
41
Run at least one iteration of an application functionality test as a ClassLoader primer, such as a load test, or wait until the workload has exercised all paths in the application. This step is a pre-test to exclude the application startup effects from skewing the survey data. Start the main application load test or wait until the workload is exercising the application and the activity you want to analyze begins. Select the Apply Changes from Expert Configuration if you want to apply instrumentation changes previously selected with Expert Configuration. Note that applied changes will override the overhead budget setting. In the Adaptive Instrumentation Wizard page, click Next. In the Adaptive Instrumentation Progress page, monitor the progress of Adaptive Instrumentation. Information in the Adaptive Instrumentation Progress page tells you which policies were applied so that you can evaluate the trade-off between increased overhead and fuller instrumentation. If the application activity does not finish within the Data Collection Duration, then allow Adaptive Instrumentation to finish, restart the monitored JVM, and re-run this procedure until the application activity can all be measured during one data collection duration. When you see the message Done, restart the monitored JVM. Repeat Step 2 to Step 11 to find additional hot spots. Running Adaptive Instrumentation twice is especially important if the Survey Calibration policy status indicates that changes were identified. After running Adaptive Instrumentation data collection two or more times, restart the application load test or wait until the workload is exercising the application. Allow two aggregation intervals and then view data in the user interface pages to evaluate whether the instrumentation has improved your understanding of the applications performance. Beware that time series summary metrics are misleading when instrumentation is applied by Adaptive Instrumentation or Expert Configuration during the displayed period.
7 8 9 10
11 12 13
Adjusting Adaptive Instrumentation overhead

Use this procedure if you have previously run Adaptive Instrumentation and you have not modified the application code or workload. This procedure adjusts the Overhead Budget setting in the Adaptive Administration page without re-collecting data. When you run this procedure, Adaptive Instrumentation applies the policies to the previously collected survey data to generate an instrumentation configuration that is in keeping with your new overhead budget. Adaptive Instrumentation saves the new configuration and applies it to the JVM. To adjust Adaptive Instrumentation overhead 1 2 3 4 5 In the Adaptive Instrumentation Wizard page, select Enable Adaptive Instrumentation. In the Adaptive Instrumentation Wizard page, clear the Collect New Survey Data check box. Use the Overhead Budget text box to specify the desired level of relative overhead available for instrumentation. Enter the overhead as a floating point number greater than or equal to zero. Click Next. In the Adaptive Instrumentation Progress page, monitor the progress of Adaptive Instrumentation. Information in the Adaptive Instrumentation Progress page tells you which policies were applied so that you can evaluate the trade-off between increased overhead and fuller instrumentation. When you see the message Done, restart the application load test or wait until the workload is exercising the application. If the Survey Calibration policy status indicates that changes were identified, especially if methods were ignored to lower overhead, then plan to restart the monitored JVM as soon as possible. The lower overhead will be engaged only after the monitored JVM is restarted. Allow two aggregation intervals to pass and then view data in the user interface Activity pages to evaluate whether the instrumentation has improved your understanding of the applications performance. Beware that time series summary metrics are misleading when the displayed time frame includes the period in which conditional instrumentation was applied by Adaptive Instrumentation or Expert Configuration. Repeat this procedure to further adjust the overhead.
42
Using Adaptive Instrumentation with a stable application or workload

Use this procedure when you have previously used Adaptive Instrumentation to generate and save a satisfactory instrumentation configuration using Standard or Expert Instrumentation modes and the application and workload are not expected to change. This procedure changes the instrumentation mode to Basic. In Basic mode, the instrumentation configuration file that Adaptive Instrumentation created will continue to provide performance information about your application, but the JVM will use fewer memory and CPU resources. See Adjusting Adaptive Instrumentation overhead on page 41. To use Adaptive Instrumentation with a stable application or workload 1 2 3 In the Adaptive Instrumentation Wizard, check Enable Adaptive Instrumentation. In the Java Virtual Machine Settings page, select Instrumentation Mode: Basic and click OK. Restart the monitored application.
Re-enabling Adaptive Instrumentation

Adaptive Instrumentation is enabled by default when Precise for J2EE is installed. If it is later disabled, follow this procedure to re-enable it. To re-enable Adaptive Instrumentation 1 In the Adaptive Instrumentation Wizard, check Enable Adaptive Instrumentation. Verify that prior survey data was collected, and that the desired overhead budget has been entered. If survey data was previously collected, the date of the collection is displayed next to Collect New Survey Data. Run Adaptive Instrumentation if survey data has not been collected or is out of date. See Using Adaptive Instrumentation for a new or changed application or workload on page 40. Change the overhead budget if necessary to adjust the Adaptive Instrumentation overhead budget that will be used during analysis. See Adjusting Adaptive Instrumentation overhead on page 41. Restart the monitored application if you made changes.
2 3
About the Expert Configuration page

Expert Configuration allows you to view the methods running in the JVM that Precise for J2EE monitors and whether they are currently instrumented. Using Expert Configuration, you can examine the context surrounding methods with high response or work times and select methods for additional instrumentation in order to fine-tune Precise for J2EE instrumentation. The methods that appear in Expert Configuration depend on the instrumentation mode set for the JVM in the Java Virtual Machine Settings page. To open the Expert Configuration page 1 In the Java Virtual Machine Settings Administration page, click Expert Configuration. By default, the Precise for J2EE Collector obtains information for Expert Configuration from information stored in the Collector about the monitored JVMs. To improve the performance of Expert Configuration, you can enable Direct Connect in the Java Virtual Machine Settings page, so that Expert Configuration connects directly to the monitored JVM. See About the Java Virtual Machine Settings page on page 16.
43
About Expert Configuration options

The table below shows Expert Configuration options. Table 2-36 Option
View Drop-down List
Expert Configuration options Description

Expert Configuration has the following four views of the methods running in the JVM:
View methods in a specific context, following execution path. This view shows methods by type and by invocation hierarchy from the caller method down to the callee methods. Tree controls in the Method Table and Expand All and Collapse All buttons allow you to see more or fewer methods. Selecting a method to instrument, from this view, instruments the method only when called in the specific method context. View methods in a specific context, inverse execution path. This view shows methods in the context of all the calls to the methods. This view can help you see where all invocations to a particular method are being made and can help you sort methods by Cumulative Invocation Count or Cumulative Service Time to see which methods are being called the most or are taking up the most time. Tree controls in the Method Table and Expand All and Collapse All buttons allow you to see more or fewer methods. Selecting a method to instrument, from this view, instruments the method only when called in the specific method context. View methods regardless of context, grouped by type. This view shows all methods that are called, organized by type. This view, when filtered appropriately, can help you see under each invocation type the worst performing or most frequently called methods. Selecting a method to instrument, from this view, instruments the method every time it is called, regardless of context. View methods regardless of context, no grouping. This view shows all methods running in the JVM. This view, when filtered appropriately, can help you see the worst performing or most frequently called methods. Selecting a method to instrument, from this view, instruments the method every time it is called, regardless of context.
Filter
The filter can be accessed by clicking the circle icon at the top right of the screen. You can filter the methods shown in the Method Table. Methods can be filtered by name (wildcard characters are allowed), invocation type, invocation count, service time, or instrumentation status. Methods that match the filter name are highlighted. After applying a filter, you can close the filter controls to increase the screen area for the Method Table. When you close the filter controls, the applied filter remains in force until you reopen the filter controls and click Clear Filters. The open and close filters control changes appearance to alert you that filtering has been applied to the Method Table.
44
Table 2-36 Option

Method Table
Expert Configuration options Description

The method table shows the methods in the JVM using the view and filtering you selected. By default, methods in the table are sorted by name, but clicking an underlined column heading causes them to be sorted by corresponding values.
Namename of the method. Method names are truncated from the left. Selecting a method causes it to be highlighted in every context in which it appears. Placing the mouse over a method name will show you the complete name in a tool tip. Enable/Disable instrumentationchecking the box beside a method name causes Precise for J2EE to monitor the method each time it calls other methods. Only methods that Precise for J2EE is monitoring can be enabled. After selecting methods to instrument, you must click Apply Changes in order for the changes to take effect.
Note: It is not possible in all situations to change the instrumentation state due to technical limitations within the JVM. Precise for J2EE will warn you when the methods you selected cannot be instrumented.

Invocation Typesuch as HTTP, custom, and more. Cumulative Invocation Counttotal number of times the method was called. Cumulative Service Timetotal time, in milliseconds, across all invocations for this context that the method has spent executing. N/A indicates that Precise for J2EE is not monitoring the method. Cumulative Work Timetotal execution time across all invocations for this context for the method, that cannot be attributed to other instrumented methods called from this context. Set Byicon representing the area of Precise for J2EE responsible for instrumenting the method. Can be one of the following: Expert Configuration, Adaptive Instrumentation, Instrumentation Configuration files, Over-instrumentation Protection.
Action Buttons
Five buttons at the bottom of Expert Configuration allow you to take the following actions:
Refresh Cumulative Dataupdate the method data and counters to reflect the most recent data. By default, the method information and counters you view in Expert Configuration are cached to improve performance and reduce overhead on the instrumented JVM, so clicking this button renews the cache. Clear Cumulative Datadeletes the invocation counts currently displayed for methods in the Method Table. You can clear these counts when you want to be sure updates to the counts reflect current system loads. For example, after initial start-up, but prior to running under load, the Method Table will show invocations, but you may not want these counts included in the counts recorded when the system is under load. Apply Changesenable instrumentation for methods not previously instrumented or disable instrumentation for previously instrumented methods. If another user is currently using Adaptive Instrumentation, you will be notified that changes cannot be applied. Adaptive Instrumentationrun the Adaptive Instrumentation Wizard to survey application activity during a load and instruct Precise for J2EE to select an optimized set of methods to instrument without exceeding your specified overhead budget. See About the Adaptive Instrumentation Wizard page on page 38. Copy Instrumentationruns the Copy Instrumentation Wizard to apply the instrumentation configuration from the currently selected JVM to another JVM. This is convenient when fine-tuning instrumentation across servers in a cluster.
Page Controls
The number of methods in the Method Table that are accessible using the scroll bar out of the total number of methods in the Method Table. You can page forward and backward and jump to the first and last pages.
About the Statistics Administration page

The Statistics Administration page enables you to modify Application Server Metrics data collection options for the JVM selected in the Java Virtual Machine Settings Administration page.
45
Warning: Application server overhead will increase when the application server collects metrics and when the Precise for J2EE Collector gathers them. Refer to the application server documentation for further details. To open the Statistics Administration page 1 2 In the Java Virtual Machine Settings Administration page, click Statistics. The Statistics Administration page opens. Values displayed in this page are the current values in the system. To save any changes that you make on this page, click OK.
About the Statistics Administration options

The table below describes the Statistics Administration options. Table 2-37 Option
Collector
Statistics Administration options Description

Identifies the currently selected Collector.
Java Virtual Machine Identifies the name of the JVM monitored by the Precise for J2EE Collector. The configuration values on this page apply to the specified JVM. Enable Statistics Collection Controls whether or not Precise for J2EE collects Application Server Metrics from the Java Virtual Machine. The application server metrics collection occurs at the interval value defined in the Precise for J2EE Collector Aggregation Interval. If this check box is selected, the Application Server Metrics collection is enabled. If this check box is cleared, the Application Server Metrics collection is disabled. Contains fields for Username and Password. These are required to set up a connection with the Application Server in order to collect Application Server metrics. The properties that are required depend upon the vendor and version of the application server. Lists the groups of Application Server Metrics collected by the Precise for J2EE Collector and names and describes each metric. The check box for each metric permits collection of individual metrics. Opens the Add Statistics to Configuration page from which users explore the J2EE application servers MBeans to select additional statistics for monitoring in Precise for J2EE.
Properties
Application Server Metrics Table Add Statistics
About the Add Statistics to Configuration page

The Add Statistics to Configuration page allows you to explore additional MBeans provided by the J2EE application server which can be added to the list of application server metrics which Precise for J2EE can collect. MBeans are managed beans that expose application server metrics. The MBeans in the Add Statistics to Configuration page are the subset of the application servers MBeans which Precise for J2EE can display. Precise for J2EE displays only MBeans whose information is numeric metrics. Select MBeans in the Add Statistics to Configuration page to add them to the list of application server metrics that Precise for J2EE can collect, then click Apply Changes. To actually start collection of the metric, you must enable its collection in the Statistics Administration page. Warning: Application server overhead will increase when the application server collects these metrics and when the Precise for J2EE Collector gathers them. Refer to the application server documentation for further details. To Open the Add Statistics to Configuration page 1 2 Open the Statistics Administration page. In the Statistics Administration page, click Add Statistics to open the Add Statistics to Configuration Web page dialog.
46
About the Add Statistics to Configuration Page options

The table below describes the Add Statistics to Configuration page options. Table 2-38 Option
Name
Add statistics to configuration options Description

Each root node in the tree is an MBean. Expanding it shows the metrics that it exposes. Select the node and metrics to make available as statistics in Precise for J2EE. Category of statistics in which the metric will be displayed in the Statistics workspace. Selection for how Precise for J2EE will handle the metric. The following types may occur:

Group Type
PASS_THRU: Precise for J2EE sends the metric value directly to the FocalPoint. ABSOLUTE_COUNT: Reserved for future use. BSH: Reserved for future use. DELTA: Precise for J2EE subtracts the previous metric value from the current value and sends the difference to the FocalPoint. J2EE_STAT: Directs Precise for J2EE to report metrics using the javax.management.j2ee.statistics interface which implements JSR 77 for J2EE management. Use type J2EE_STAT only with Oracle 10g and JBoss application servers which implement this standard. MEAN: For WebSphere application servers only, Precise for J2EE reports the average value for the metric over the time period.
Description
Information about the MBean provided by the application server vendor.
About the Copy Instrumentation page

In order to address scalability and availability requirements in your environment, Java Virtual Machines may be deployed in clusters. In order to maximize the use of Precise for J2EE in clustered configurations, you can use the Copy Instrumentation Wizard, accessed from Expert Configuration or Java Virtual Machine Settings Administration pages, to automatically copy instrumentation configuration files from one JVM in the cluster to others. If the target JVMs are running, the copied instrumentation will take effect immediately. Note: Only a subset of the copied instrumentation is enabled immediately when copying instrumentation between JVMs that are set to different instrumentation modes. Some instrumentation, like Adaptive Instrumentation Survey Calibration results, only takes effect at startup. After copy instrumentation completes, you should plan to restart the target JVMs as soon as possible.
Warning: After copying instrumentation, closely monitor the instrumentation overhead on the target JVM. Depending on the configuration of the target JVM prior to copying, the instrumentation overhead on the target JVM following the copy may exceed the overhead that the source JVM incurs as a result of the same instrumentation. To open the Copy Instrumentation page 1 2 From the Java Virtual Machine Settings Administration page, click Run Copy Instrumentation now. The Copy Instrumentation page opens. Click OK in the Copy Instrumentation page to open the Copy Instrumentation Progress page.
Troubleshooting memory errors and adjusting heap sizes

If the available memory is running low inside the monitored JVM, or on its host, the JVM may throw OutOfMemory errors, or may crash with a HotSpot JVM error. This may happen when Adaptive Data Collection is occurring while the monitored JVM is in Expert or Standard instrumentation modes because classes are being heavily instrumented, and the space the classes consume increases. In some cases, the JVM starts and operates fine but later runs out of
47
memory when Adaptive Instrumentation data is being collected and saved to a file. The actual memory error produced depends on the state of the JVM at the time the memory is exhausted. In the best case scenario, you will see OutOfMemory errors in the command window or stdout/stderr log for the monitored JVM; look carefully since it is easy to miss the error if alot of output is sent to the console. In the worst case, no error message is visible, and the JVM crashes with or without a Hotspot JVM error. Typically memory related problems may be solved by allocating more memory to the monitored JVM. One way to gauge the size of the memory increase that is needed is to turn on the JVM argument -verbose:gc to view the free memory and garbage collection activity during startup and runtime. For example, if the JVM runs out of memory half way through startup, then you can surmise that the memory should be doubled. At the time of this writing, there is no way to predict the memory requirement except empirically. In many environments, if you use Adaptive Instrumentation, you will need to increase the JVM heap memory settings (using the -Xmx parameter) and the Permanent Generation settings on Sun's JDKs (using the -XX:MaxPermSize parameter) or the initial system heap size on IBM's JDKs (using the -Xinitsh parameter) or all of them. The amount of JVM memory increase that is required can vary dramatically from application to application, depending on a number of factors, including the number of classes loaded by the application in the JVM. In some cases, you might even need to double (or more) the JVM memory. After you adjust these memory settings you will need to restart the monitored JVM for the new settings to take effect. If your monitored JVM experiences stability or memory issues, set the monitored JVM to use the Basic Instrumentation Mode because that mode uses the least amount of JVM memory and system resources.
About JVM heap size for all JDKs

Use the -Xmx*M parameter to set the JVM heap size, where * is the maximum heap size in megabytes, such as -Xmx1024M or -Xmx512M. It is not uncommon to double the previous heap size when using Adaptive Instrumentation.
About increasing collector memory

In addition to increasing the JVM memory, you might need to increase the collector memory as well. To increase the collector memory, do the following: 1 2 3 Edit the <I4J2EE_HOME>\bin\psje_j2c_init.xml file. Change the following option to a larger size: <option>-Xmx512m</option> Restart the collector, and run Adaptive Analysis again.
About permanent generation size for Sun JDKs

Use the -XX:MaxPermSize=*M parameter to set the permanent generation size, where * is the generation size in megabytes, such as -XX:MaxPermSize=128M or -XX:MaxPermSize=256M. For additional information on Sun's Java Virtual Machine settings, see Java HotSpot VM Options at http://java.sun.com.
Setting initial system heap size for IBM JDKs

Use the -Xinitsh* parameter to set the initial system heap size for IBM JRE where * is the size followed by K or M, such as -Xinitsh256K. The defaults are 128K on 32-bit architectures and 8M on 64-bit architectures. For additional information on IBM's settings, see Sensible sanitation -- Understanding the IBM Java Garbage Collector, Part 3 at http://www.ibm.com. To insert the Xinitsh parameter using the WebSphere Administrative Console 1 2 Stop the application to be monitored. Navigate to the console location appropriate for your server.
Server Location
Precise for J2EE Basics How to launch the Precise for J2EE user interface
48
WebSphere 5.x
Servers > Application Servers > Application > Process Definition > Java Virtual Machine > Generic JVM Arguments Servers > Application servers > Server Name > Java and Process Management > Process Definition > Java Virtual Machine > Generic JVM arguments
WebSphere 6.x
3 4
Add the parameter into the text edit field. Click Apply.
How to launch the Precise for J2EE user interface

You can launch the Precise for J2EE user interface from Precise StartPoint or directly from a browser. See How to launch the Precise for J2EE user interface on page 48. See Launching the user interface directly on page 48.
Launching Precise for J2EE from Precise StartPoint

The Precise user interface is a server-side Java application that listens on a network port for HTML page requests. The syntax of the Precise URL address is: http://<server machine>:<port>/ where <server machine> refers to the Precise FocalPoint server and <port> refers to the port number that the FocalPoint communicates on. By default, the port number is 20790. Note: The Precise FocalPoint and Precise for J2EE FocalPoint must be started before they can be accessed. See the Precise Administration Guide to learn how to start Precise and Precise for components. To access the Precise for J2EE user interface using Precise StartPoint 1 2 3 4 Type the URL address of the StartPoint user interface into the Address bar of your browser and press Enter. The Precise login page opens. The login page provides secure access to Precise and to your specific product. Specify your authorized role name and password. By default, both the role name and password are admin. For more information on role names, see the Precise Administration Guide. Click Login. The StartPoint page opens. This is the Precise home page. On the StartPoint page, click the Precise for J2EE button located on the right side and open the Activity workspace.
Note: Make sure that the Precise user interface and J2EE are using the same hypertext transfer protocol, whether secure (HTTPS) or non-secure (HTTP).
Launching the user interface directly

The Precise for J2EE user interface is a server-side Java application that listens on a network port for HTML page requests. You can access the Precise for J2EE user interface using Internet Explorer browser, version 7 or 8. Note: Since the Precise for J2EE user interface uses standard HTML pages, you may return to a screen you were previously viewing by book marking the page or sending the link via email. The syntax of the Precise for J2EE URL address is: http://<server machine>:<port>/ where <server machine> refers to the Precise FocalPoint server and <port> refers to the port number that the User Interface communicates on. By default, the port number is 20761.
Precise for J2EE Basics How to launch the Precise for J2EE user interface
49
Note: Precise for J2EE FocalPoint must be started before it can be accessed. See the Precise Administration Guide to learn how to start Precise for components. To access the Precise for J2EE user interface from a browser 1 Type the URL of the Precise for J2EE user interface into the Address bar of your browser and press Enter. If HTTPS is enabled for communication between the Precise for J2EE user interface and Precise for J2EE FocalPoint, you may see a security alert dialog box asking you to accept the certificate. Once you accept, the certificate will remain valid for the entire browser session. You can also choose to install the certificate for use in future browser sessions. See About the FocalPoint Administration page on page 18. If your Precise environment uses SiteMinder or other single sign-on authentication and your current session has not been authenticated, you will be redirected to the Precise Login page. In the Precise for J2EE Login page, specify your authorized role name and password. Click OK to open the Dashboard workspace. This is the Precise for J2EE home page.
2 3
Chapter
Getting an overview of your environment in the Dashboard workspace


About the Dashboard workspace About the Dashboard portlets How to identify performance problems in the Dashboard workspace
About the Dashboard workspace

The Precise for J2EE Dashboard workspace is a web page portal for visualizing the overall health and status of all instrumented application server instances using data collected through application instrumentation. Composed of user-configurable tabs and data modules, called portlets, the Precise for J2EE Dashboard workspace provides support for detailed views of individual application servers as well as top-level summary views of multiple application servers. By personalizing the Dashboard workspace, users can display the view of the application server most relevant to their roles and organization. See How most workspaces are structured on page 9. The figure below shows a typical Dashboard workspace.
Getting an overview of your environment in the Dashboard workspace About the Dashboard workspace
51
Figure 3-1 Time frame
Typical Dashboard workspace Environment AppTier
Portlet
Portlet preferences
About Portlets
Portlets are the data modules containing Precise for J2EE metrics that make up the Dashboard workspace. The JVMs in the JVM List portlet and the Select JVM drop-down list (where it exists) contain only the list of JVMs that the logged on user is authorized to view (based on previously defined roles definitions). The data in the All JVMs Health and All JVMs Threads portlets summarize data for all monitored JVMs in the JVM List. The data in all other portlets are for the JVM currently selected in the JVM List, or you can select the JVM in the portlet itself. See About the Dashboard portlets on page 53.
About the time frame

The time frame for data displayed in the Dashboard workspace is selected using the Time Frame selector in the Dashboard. By default, the time frame is set to the last hour. If the time frame is set in another workspace, data for that time frame will be displayed in the Dashboard. The time frame set in the Dashboard is also the time frame for the Activity and Statistics workspaces. See About display intervals on page 12.
About the environment

The environment for data displayed in the Dashboard workspace is selected using the Environment selector in the Dashboard.
Getting an overview of your environment in the Dashboard workspace About the Dashboard workspace
52
About the AppTier

In the Dashboard workspace, the AppTier for data displayed in this workspace, is selected using the AppTier selector.
Configuring portlets
For many portlets, you can select the JVM for which data is displayed. You can also configure the metrics that are displayed in the portlet as well as how the data is displayed. The figure below shows a typical Portlet Preferences page. Figure 3-2 Portlet Preferences
To configure a portlet 1 2 3 Click on the portlets Edit Preferences icon. Change the portlets title by entering a new title in the Displayed title field. The JVM List portlet only allows you to change the portlets displayed title and the JVM List Portlet height. Choose Table, Chart, or Traffic Light to select how the portlet will display the data. Only numeric metrics can be displayed in a chart or by using traffic light icons.
Table If you choose Table, additional metrics are available to be configured. These metrics serve as column headings for the table. You can choose Summary or Detail to select how the portlet will display data. Summary results in one row per metric, while Detail results in one row per data point.
Getting an overview of your environment in the Dashboard workspace About the Dashboard portlets
53
Chart
If you choose Chart, the following options can be configured:

Chart typeType of chart and number of axes per chart. Multiple axes allows more than one metric to be plotted on a single graph. Chart widthWidth of chart in pixels when portlet is viewed normally (not maximized). Chart heightHeight of chart in pixels when portlet is viewed normally (not maximized). Maximized chart widthWidth of chart in pixels when portlet is maximized. Maximized chart heightHeight of chart in pixels when portlet is maximized. Chart legend maximum lengthMaximum number of characters to appear in the chart legend for each metric. For a legend of unlimited length, enter -1. Chart legend positionLocation of chart legend above, below, or to the right or left of the chart. Select No Legend to hide the legend.
Traffic Light
Traffic Light uses a red, yellow, or green icon for each metric the portlet is displaying. The metric value is compared to a user-configurable threshold to determine which icon to display. By default, the threshold for yellow icons in all portlets is 0.5, and the default for red icons is 0.25. You can customize the threshold by selecting the comparison method and entering a new value in the threshold text fields. You can also choose to see the actual metric value as a ToolTip, or displayed next to the Traffic Light icon.
4 5 6 7
Select the metrics that you want to see in the portlet. If the portlet has configurable parameters, select the parameters. Click Save Changes. Click the portlets Leave Edit Preferences icon.
About the Dashboard portlets

The following is an alphabetical list of the portlets that are available in the Dashboard workspace:
All JVMs Health All JVMs Threads Concurrent Active Thread Metrics Exception Seeker Grouped JVMs Health Grouped JVMs Threads Invocation Type Scalability JDBC Metrics JVM Health JVM List Leak Seeker Metrics Lock Seeker Metrics Memory Metrics Method Scalability Portal Server Metrics SQL Statements Findings Methods Invocations Findings Application Summary Statistics Top Business Transactions Top Instrumented Methods Top Methods by Invocation Type Work Times of Invocation Types
About the JVM List portlet

The JVM List portlet provides a list of the JVMs that the logged on user is authorized to view, according to the roles definitions. Clicking a column header causes the data displayed in the table to be sorted by the selected column. The JVM List portlet displays the following information:
Find: JVM Name Status CPU (%) Find Next Heap (%) Filter Avail (%)
54
The following is a short description of the information displayed for each JVM. The averages displayed are averages over the last time slice analyzed.
JVM Name Server hostname and JVM ID of the monitored JVM. Clicking the JVM Name field selects this JVM and transfers data to the Activity workspace. The Status column contains the following icons to indicate the JVM's status: Indicates the JVM is running and being monitored by Precise for J2EE Indicates the JVM is not running Indicates that Precise for J2EE could not obtain information from the JVM Note: Clicking on the Status field for a JVM selects this JVM and it remains on the Dashboard workspace. CPU (%) Heap (%) Avail (%) Average percent of CPU time this JVM consumed. See note above. Average percent of the JVM heap in use. See note above. Average percent of the time frame that the selected JVM was available. See note above.
Status
About the All JVMs Health portlet

The All JVMs Health portlet provides summary metrics across all JVMs that the logged on user is authorized to view, according to the roles definitions. The All JVMs Health Metrics portlet displays the following information:
Data values are displayed in table, chart, or traffic light formats using the metrics selected from the table below.
The table below shows the metrics that are available when displaying the All JVMs Health data. Table 3-1 Metric
Service Time
All JVMs Health metrics Description

Average time in milliseconds for the displayed time frame that elapsed from when a request is sent to a server to the time a response for that request is generated. The service time measures server-side Java method completion. The number of method completions per second. Average CPU percentage used during a time period. Average amount of JVM heap space used during a time period. Average amount of available Java heap space over a time period. Scheduled system downtime entered into the Precise FocalPoint. Planned downtime does not negatively impact availability calculations. The average size of the Java heap space over a time period. The number of major garbage collections that occurred during the specified time. A major garbage collection in Precise for J2EE reclaims more than a configurable percentage of the Java heap, by default, 40%. The total number of garbage collections (major and minor) that occurred during the specified time.
Throughput %CPU %Heap %Available %Planned Downtime
Avg Heap Size Major GC Count
Total GC Count
About the All JVMs Threads portlet

The All JVMs Threads portlet provides thread metrics for all JVMs that the logged on user is authorized to view, according to the roles definitions. This portlet helps you compare the load on the JVMs.
55
The All JVMs Threads portlet displays the following information:

Select JVM Current selected JVM from JVM List (drop-down list)
Data values are displayed in table, chart, or traffic light formats using the metrics selected from the table below
The table below shows the metrics that are available when displaying the All JVMs Thread data. Table 3-2 Metric
Concurrent Active Threads Long Running Threads
All JVMs Threads metrics Description

Number of top-level threads running simultaneously. The number of threads that are active longer than a configurable amount of time.
About the Concurrent Active Thread Metrics portlet

The Concurrent Active Thread Metrics portlet provides metrics on long-running and concurrent active threads for an instrumented JVM. This data gives an indication of how busy the system is and helps you to determine whether an application is misusing Java threads or if there are threads that are running over a long period of time. Thread metrics can help pinpoint performance problems since a large number of concurrent threads relative to the number of CPUs could slow performance. The Concurrent Active Thread Metrics portlet displays the following information:
The table below shows the metrics that are available when displaying the Concurrent Active Thread Metrics data. Table 3-3 Metric
Concurrent Active Threads Metrics Description

About the Exception Seeker portlet

The Exception Seeker portlet displays the following information:
Data values are displayed using the metrics selected from the table below.
The table below shows the metrics that are available when displaying the Exception Seeker data. Table 3-4 Metric
Exception Stack Trace Message Thrown Class
Exception Seeker Description

The full stack trace of the thrown class. The message that was set in the thrown class. The class name that was thrown.
56
Table 3-4 Metric
Exception Seeker Description

Number of times the exception occurred during the selected time frame. The class and method from which the class was thrown. Number of times the exception occurred during the selected time frame. The exception cause (if available). This parameter is not shown by default; it can be enabled in the portlet settings. The root of the stack trace. The last time this class was thrown within the time frame (the last time the exception occurred).
Exception Count Location Count Cause
Stack Trace Root Last Exception Time
About the Grouped JVMs Health portlet

The Grouped JVMs Health portlet provides average metrics for a subset of JVMs in the current JVM list. You use the portlet's Portlet Preferences page to set up the group and select the metrics to display. You can include JVMs in the group using a semi-colon delimited list of regular expressions. For example, entering ClusterNode* in the JVMs in Group field in the portlet preferences screen will include all JVMs whose IDs begin with ClusterNode in the group. You also use options in the Portlet Preferences page to display only the group metrics or metrics for both the group and individual JVMs. The Grouped JVMs Health portlet displays the following information:
The table below shows the metrics that are available when displaying the Grouped JVMs Health portlet as a chart. Table 3-5 Metric
Service Time
Grouped JVMs Health metrics Description

Average time in milliseconds for the displayed time frame that elapsed from when a request is sent to a server to the time a response for that request is generated. The service time measures server-side Java method completion. The number of method completions per second. The amount of time in percent consumed by the operating system actively processing instructions on behalf of a running method. Average amount of JVM heap space used during a time period. Average amount of available heap space over a time period. Scheduled system downtime, according to the settings in the Planned Downtime dialog for the J2EE technology, in AdminPoint. Planned downtime does not negatively impact availability calculations. The average size of the Java heap space over a time period. The number of major garbage collections that occurred during the specified time. A major garbage collection in Precise for J2EE reclaims more than a configurable percentage of the Java heap, by default, 40%. The total number of garbage collections (major and minor) that occurred during the specified time.
Throughput CPU (%)
Heap (%) Available (%) Planned Downtime (%)
Total GC Count
57
About the Grouped JVMs Threads portlet

The Grouped JVMs Threads portlet provides average thread metrics for a subset of JVMs in the current JVM list. This portlet helps you assess the load on JVMs in a named group. You use the portlet's Portlet Preferences page to set up the group and select the metrics to display. You can include JVMs in the group using a semi-colon delimited list of regular expressions. For example, if you enter ClusterNode.* in the JVMs in Group field in the portlet's Portlet Preferences page, you will include all JVMs whose IDs begin with ClusterNode.* in the group. You also use options in the Portlet Preferences page to display only the group metrics or metrics for both the group and individual JVMs. The Grouped JVMs Threads portlet displays the following information:
The table below shows the metrics that are available when displaying the Grouped JVMs Threads portlet as a chart. Table 3-6 Metric
Grouped JVMs Threads Description

About the Invocation Type Scalability portlet

The Invocation Type Scalability portlet provides summary metrics about a specific invocation type. This data helps you determine which invocation type may be affecting application performance. You use the portlet's Portlet Preferences page to choose the invocation type to monitor. The Invocation Type Scalability portlet displays the following information:
The table below contains the metrics that are available when displaying the Invocation Type Scalability data. Table 3-7 Metric
Service Time
Invocation Type Scalability metrics Description

The elapsed total time in seconds for completed service requests of the selected invocation type. This metric measures when the request arrived at the server until the time a response to that request was sent from the server. The number of times a method was executed. The total service time per execution over a period of time. This is the Average Service Time. The number of method completions per second. Total CPU time per slice for the displayed item. Average CPU time per slice for the displayed item.
Executions Service Time/Execution Throughput CPU Time CPU Time/Execution
About the JDBC Metrics portlet

The JDBC Metrics portlet provides metrics for the JDBC invocation type. These metrics help you determine if database activity is affecting application performance.
58
The JDBC Metrics portlet displays the following information:

The table below shows the metrics that are available when displaying the JDBC data. Table 3-8 Metric
Service Time
JDBC metrics Description

The total time, in seconds that it took all instrumented JDBC methods of the specified type (updates, queries, etc.) to execute. Performance contributions not directly accounted for with instrumentation. The number of times a JDBC method was executed. The total service time per execution over a period of time. This is the Average Service Time. The average work time per execution over a period of time. Work time is unaccounted for time, in other words the time that is not spent calling other instrumented methods. The number of JDBC method completions per second.
Work Time Executions Service Time/Execution Work Time/Execution
Throughput
About the JVM Health portlet

The JVM Health portlet provides summary metrics for the selected JVM. The JVM Health portlet displays the following information:
The table below shows the metrics that are available when displaying the JVM Health data. Table 3-9 Metric
Service Time
JVM Health metrics Description

Average time in milliseconds that elapsed from when a request is sent to a server to the time a response for that request is received. The service time is measured on the client side. The number of method completions per second. Average CPU percentage used during a time period. Average amount of JVM heap space used during a time period. Average amount of available Java heap space over a time period. Scheduled system downtime entered into the Precise FocalPoint. Planned downtime does not negatively impact availability calculations. The average size of the Java heap space over a time period. The number of major garbage collections that occurred during the specified time. A major garbage collection in Precise for J2EE reclaims more than a configurable percentage of the Java heap, by default, 40%. The total number of garbage collections (major and minor) that occurred during the specified time.
Throughput %CPU %Heap %Available %Planned Downtime
Total GC Count
59
About the Leak Seeker Metrics portlet

The Leak Seeker Metrics portlet provides Leak Seeker metrics on Java objects, collections, arrays, or string buffers. You use the portlet's Portlet Preferences page to configure the number of objects, collections, arrays, or string buffers to display. You can also select how the list is sorted. The Leak Seeker Metrics portlet displays the objects, collections, arrays, or string buffers with the largest number of elements or largest trend line from this list. You must configure the monitored JVM to collect Leak Seeker metrics to display these metrics in the Leak Seeker Metrics portlet. See About the Java Virtual Machine Settings page on page 16. The Leak Seeker portlet displays the following information:
The table below shows the metrics that are available when displaying Leak Seeker Metrics. Table 3-10 Metric
Object Count
Leak Seeker metrics Description

Total number of objects, or elements, in all live collections, arrays, or string buffers allocated at a particular site. Best linear approximation of the growth of the collection size over time. Rate of growth of the collection over time.
Object Count Trend line Object Count Growth Rate (Objects per Minute)
About the Lock Seeker Metrics portlet

The Lock Seeker Metrics portlet provides metrics for lock acquisition time. You use the portlet's Portlet Preferences page to configure the metrics for display. The Lock Seeker Metrics portlet displays the following information:
The table below shows the metrics that are available when displaying Lock Seeker Metrics as a chart. Table 3-11 Metric
Lock Acquisitions Lock Acquisition Time Average Lock Acquisition Time
Lock Seeker Metrics Description

Number of lock acquisitions that were made in a given method during the specified time frame. Total time spent acquiring locks in a given method during the specified time frame. The average amount of time spent per lock acquisition within a given method during the specified time frame.
About the Memory Metrics portlet

The Memory Metrics portlet provides memory information for instrumented JVMs. This portlet helps you determine rapidly if the monitored application is experiencing memory issues.
60
The Memory Metrics portlet displays the following information:

The table below shows the metrics that are available when displaying the Memory Metrics as a chart. Table 3-12 Metric
Avg Heap Size Avg Free Heap Avg Heap Used Min Heap Size Max Heap Size Min Free Heap Max Free Heap Min Heap Used Max Heap Used Major GC Count
Memory Metrics Description

The average size of the Java heap space over a time period. The average free heap (heap available for use) over a period of time. The average heap used over a period of time. The minimum Java heap size over a period of time. The maximum Java heap size over a period of time. The minimum free Java heap space over a period of time. The maximum free Java heap space over a period of time The minimum Java heap used over a period of time. The maximum Java heap used over a period of time. The number of major garbage collections that occurred during the specified time. A major garbage collection in Precise for J2EE reclaims more than a configurable percentage of the Java heap, by default, 40%. The total amount of time spent executing major garbage collections. The amount (in MB) of Java heap memory that has been freed or released during a major garbage collection. The total number of garbage collections (major and minor) that occurred during the specified time. The total amount (in MB) of unreferenced Java objects that have been freed/released during major/minor garbage collections.
Major GC Time Major GC Freed
Total GC Count Total GC Freed
About the Method Scalability portlet

The Method Scalability portlet provides data on the behavior of a specific method. It is useful in cases where a known business process entry point method could be set up to track the scalability. You use the portlet's Portlet Preferences page to configure the class and method to display. The Method Scalability portlet displays the following information:
The table below shows the metrics that are available when displaying the Method Scalability data. Table 3-13 Metric
Service Time
Method Scalability metrics Description

The total time, in seconds, that it took the selected method to execute. Only completions within the displayed time frame are displayed.
61
Table 3-13 Metric

Executions
Method Scalability metrics Description

The number of times the selected method was executed. The total service time per execution over a period of time. This is the Average Service Time. The number of completions of the selected method per second. Total CPU time per slice for the displayed item. Average CPU time per slice for the displayed item.
Service Time/Execution Throughput CPU Time CPU Time/Execution
About the Portal Server Metrics portlet

The Portal Server Metrics portlet provides metrics for the portal server and its portlets that are monitored by Precise for J2EE, if the monitored JVM is a portal server. You can use this portlet to spot performance problems in the portal server and its portlets. The portal and portlet invocations that are available for monitoring with this portlet depend on the monitored portal server's vendor and version. You use the portlet's Portlet Preferences page to select the portlet invocation type to graph and how many invocations for that portlet the graph will show. The Portal Server Metrics portlet displays the following information:
The table below shows the metrics that are available when displaying the Portal Server Metrics data. Table 3-14 Metric
Service Time
Portal Server Metrics Description

The total time, in seconds, that it took the selected invocation type to execute, from when a request was sent to a server until the time a response to that request was sent. Performance contributions not directly accounted for with instrumentation. The number of times the invocation type was executed. The total service time per execution over a period of time. This is the Average Service Time. The work time per execution over a period of time. This is the Average Work Time. Work time is unaccounted for time, in other words the time that is not spent calling other instrumented methods. The number of invocations per second. Total CPU time per slice for the displayed item. Average CPU time per slice for the displayed item.
Throughput CPU Time CPU Time/Execution
About the SQL Statements portlet

The SQL Statements portlet displays service times for SQL statements. This portlet helps you identify rapidly which SQL statements are contributing to poor performance. You use the portlet's Portlet Preferences page to configure the number of SQL statements to display. The SQL Statements portlet displays the following information:
62
The table below shows the metrics that are available when displaying SQL Statements data. Table 3-15 Metric
Start Time End Time SQL Unique ID
SQL Statements metrics Description

The start time of the time frame in which the SQL statement was monitored. The end time of the time frame in which the SQL statement was monitored. An internal ID used to track an SQL statement in Precise for J2EE. The SQL Unique ID is mainly used for diagnostic or troubleshooting purposes. The SQL statement executed in the monitored JVM. The total time, in milliseconds, that it took for the displayed SQL statement to execute.
SQL Statement Service time
About the Findings Application Summary portlet

The Findings Application Summary portlet uses a stoplight display to quickly indicate the severity of method contributors to application performance. When you click the method name in the portlet, the Activity workspace Hotspots tab opens. By default, the Findings Application Summary portlet displays data for the Category with Highest Rank for All Service requests. For the Findings Application Summary portlet to display other method data, you must configure the contributor category in the Findings Administration page as well as in the portlet's Portlet Preferences page. You select the category, type, and measurement, and set severity thresholds and indicators for the portlet to display in the portlet's Portlet Preferences page. If there are no significant contributors for the category or type configured, the portlet indicates that no contributors were found. See About the Findings Administration page on page 20. The Findings Category With the Highest Contribution for All Service Requests portlet displays the following information:
Table headings with the metrics selected from the table below are displayed.
The table below shows the parameters that can be configured for the Findings Application Summary portlet. Table 3-16 Parameter
Measurement
Findings Application Summary portlet metrics Description

Selects one of the following metrics to display about the contributor:

Service Time Work Time CPU Time CPU Work Time
Type
Selects one of the following types of service requests to display:

All Service Requests All Threads EJB Service Requests HTTP Service Requests Portal Service Requests
Category
Selects the category of contributor to display. The list includes all Findings method categories listed below.
63
Findings Application Summary Categories

Category With the Highest Rank WEBLOGIC Stateless Session EJB WEBLOGIC Stateful Session EJB WEBLOGIC Entity EJB WEBSPHERE EJB Cache WEBSPHERE Stateful Session EJB WEBSPHERE Entity EJB ORACLE Stateless Session EJB ORACLE Stateful Session EJB ORACLE Entry EJB JDBC Connection Pool SQL Acess JDBC Access EJB Access JNDI Access HTTP Access XML Access JMS Access Java Transaction Access Java IO Access Web Services Access Synchonized Access Application Methods
About the Findings Application Summary portlet

The Findings Application Summary portlet uses a stoplight display to quickly indicate the severity of application contributor categories to application performance. All application contributor categories are displayed in the portlet. The portlet has no editable preferences. However, for the portlet to display the data, you must configure the contributor category in the Findings Administration page. See About the Findings Administration page on page 20. The Findings Application Summary portlet contains a drop-down list that enables you to select a JVM. Contributors are displayed in the Findings Application Summary next to the Severity of each contributor. This portlet has no configurable parameters. The contributors are shown below.
ExecuteQueue Idle Threads Shortage Concurrent Active Threads Garbage Collection Time Heap Used Memory JMS Server Messages Pending JMS Session Messages Pending Maximum Free Memory Database Connection Availability Leaked Database Connections Waiting For Database Connection
About the Statistics portlet

The Statistics portlet displays the value of statistics (application server metrics) collected from an instrumented JVM. By default, the Statistics portlet can display the Heat Seeker statistic, if this statistic is enabled in the Statistics Administration page. If Precise for J2EE is reporting other Application Server Metrics in the Statistics workspace, you can display these statistics in the Statistics portlet. For the statistic that you select, you can configure the Statistics
64
portlet to show specific metrics. You use the portlet's Portlet Preferences page to select the statistic to display and the number of top measurements that will be displayed for that statistic. The Statistics portlet displays the following information:
Data values are displayed in table, chart, or traffic light formats.
About the Top Business Transactions portlet

The Top Business Transactions portlet displays metrics for the business transactions that have the highest response or work times. This portlet helps you to quickly assess how users are experiencing key areas of your application. You use the portlet's Portlet Preferences page to choose the number of business transactions to display and how the portlet will sort the business transactions. In order to display data for business transactions, you must configure at least one business transaction to display data in the Top Business Transactions portlet. See About the Business Transactions Administration page on page 27. The Top Business Transactions portlet displays the following information:
The table below contains the metrics that are available when displaying the Top Business Transactions data. Table 3-17 Metric
Service Time Executions
Top Business Transactions metrics Description

Average elapsed time in seconds for completed service requests that are part of the business transaction. The number of times the method with the longest service times was executed.
Service Time/Execution The total service time per execution over a period of time. This is the Average Service Time. Throughput CPU Time CPU TIme/Execution The total number of method completions for the methods that are part of the business transaction. Total CPU time for the methods that are part of the business transaction. Average CPU time per slice for the displayed item.
About the Top Instrumented Methods portlet

The Top Instrumented Methods portlet displays metrics for the methods with the top response or work times. This portlet helps you to rapidly identify methods for further investigation in the Activity workspace. You use the portlet's Portlet Preferences page to choose the number of methods to display and whether the portlet will sort the selected methods by service time or work time. The Top Instrumented Methods portlet displays the following information:
65
The table below contains the metrics that are available when displaying the Top Instrumented Methods data. Table 3-18 Metric
Service time
Top Instrumented Methods metrics Description

The total time, in seconds, that it took the methods with the longest service times to execute, from when a request was sent to a server until the time a response to that request was sent. Performance contributions not directly accounted for with instrumentation. The number of times the method with the longest service times was executed. The total service time per execution over a period of time. This is the Average Service Time. The work time per execution over a period of time. This is the Average Work Time. Work time is unaccounted for time, in other words the time that is not spent calling other instrumented methods. The number of method completions per second. Total CPU time per slice for the displayed item. Average CPU time per slice for the displayed item.
About the Top Methods by Invocation Type portlet

The Top Methods by Invocation Type portlet lists methods that have the largest response or work times for a given invocation type. This portlet helps you rapidly identify methods for further investigation in the Activity workspace. You use the portlet's Portlet Preferences page to select the invocation type and whether the portlet will sort the selected methods by service time or work time. The Top Methods by Invocation portlet displays the following information:
The table below shows the metrics that are available when displaying the Top Methods by Invocation Type data. Table 3-19 Metric
Service time
Top Methods by Invocation Type metrics Description

The total time, in seconds, that it took the methods with the longest service times of that execution type to execute, from when a request was sent to a server until the time a response to that request was sent. Performance contributions not directly accounted for with instrumentation. The number of times the method with the longest service times for that invocation type was executed. The total service time per execution over a period of time. This is the Average Service Time. The work time per execution over a period of time. This is the Average Work Time. Work time is unaccounted for time, in other words the time that is not spent calling other instrumented methods. The number of method completions per second. Total CPU time per slice for the displayed item. Average CPU time per slice for the displayed item.
Work Time Executions
Service Time/Execution Work Time/Execution
Getting an overview of your environment in the Dashboard workspace How to identify performance problems in the Dashboard workspace
66
About the Work Times of Invocation Types portlet

The Work Times of Invocation Types portlet lists the work times broken down by invocation type. This port helps you rapidly identify the invocation type (HTTP or custom) that has the highest work times. The Work Times of Invocation portlet displays the following information:
The table below shows the metrics that are available when displaying Work Times of Invocation Types data. Table 3-20 Metric
Work time
Work Times of Invocation Types metrics Description

The total time, in seconds, that the methods did not spend in instrumented contributors. This is the Performance contribution not directly accounted for with instrumentation. The total time, in seconds, that it took the methods with the longest service times for the displayed invocation type to execute, from when a request was sent to a server until the time a response to that request was sent. The number of times methods of the invocation type were executed. The work time per execution over a period of time. This is the Average Work Time. Work time is unaccounted for time, in other words the time that is not spent calling other instrumented methods. The total service time per execution over a period of time. This is the Average Service Time. Total CPU time per slice for the displayed item. Average CPU time per slice for the displayed item.
Service time
Executions Work time per execution
Service time per execution CPU Time CPU Time/Execution
How to identify performance problems in the Dashboard workspace

The Dashboard workspace enables you to quickly view the health and key performance data for the JVMs you are monitoring. The Dashboard portlets show many aspects of the health of monitored JVMs. You can use the Dashboard to identify likely causes of performance problems before switching to the Activity, Statistics, or Memory workspaces where you locate more specific data and fully analyze the problem.
Diagnosing scalability issues

You can use the Dashboard workspace to check the scalability of your system. To locate scalability bottlenecks 1 2 3 4 In the Precise for J2EE user interface, click Dashboard to open the Dashboard workspace. In the Dashboard JVMs List portlet, click a JVM you are monitoring. Information on this JVM displays in other Dashboard portlets. If the Method Scalability portlet is not already displayed, use Add Portlet to display it. In the Method Scalability portlet, click Edit Preferences. In the Portlet Preferences page Class Name to Report and Method Name to Report fields, enter a method related to the critical business process that you are monitoring. You enter the class and methods separately. The class name must include the full package name instrumented and displayed by Precise for J2EE. The combined class and method name text has to match class and method
67
names displayed in the Precise for J2EE Activity workspace tabs, but when entering the class and method names in the Portlet Preferences page omit the period. 5 6 Save and close the Portlet Preferences page. Then wait until the GUI is updated with data for the next time slice. In the Dashboard Method Scalability portlet, look at the service times for the method. If the method has high service times, you can use the Activity and Statistics workspaces to get a deeper understanding of the problem.
If the method is an EJB type, further investigate the methods behavior in the Statistics workspace (if Application Server Metrics are configured) by examining the EJB pool and cache sizes. For methods of type JDBC, use the Statistics workspace to look at database connection pools. For all types of methods, use the Hotspots tab in the Activity workspace to assist with the analysis.
Identifying a CPU bottleneck

You can use the Dashboard workspace to identify CPU bottlenecks and assess the end-user experience during high CPU usage. To identify a JVM whose CPU resources are a constraint 1 2 In the Precise for J2EE user interface, click Dashboard to open the Dashboard workspace. In the Dashboard JVM List portlet, click %CPU to sort the JVMs by their %CPU usage. Inspect the JVMs' %CPU and click a JVM that you consider to have high %CPU usage. Information on this JVM displays in other Dashboard portlets. If the JVM Health portlet is not already displayed, use Add Portlet to display it. In the JVM Health portlet, look at the CPU usage. Consistently high %CPU usage, for example, over 85%, indicates a possible CPU bottleneck. A good rule of thumb is to have about 20% of your CPU reserved to absorb a peak load. In other cases, the system may be operating at a peak load. During peak loads, high %CPU may contribute to a poor end-user experience. If the Invocation Type Scalability portlet is not already displayed, use Add Portlet to display it. This portlet helps you assess the end-user experience during high CPU usage. Then configure the portlet for the invocation type. Compare the portlet graphs to the JVM %CPU graph in the JVM Health portlet. Is the request Throughput low or decreasing and is the request Service Time high or increasing during the same period that the %CPU is high? If the answer is 'no' then the high %CPU is not correlated to an end-user problem. If the answer is 'yes' then you may have a CPU bottleneck that is contributing to a poor end-user experience and you should ask a developer or architect whether the CPU usage and end-user experience are normal for the load.
3 4
Identifying a memory bottleneck

You can use the Dashboard workspace to identify and locate memory bottlenecks. To identify a JVM whose memory resources are a constraint 1 2 In the Precise for J2EE user interface, click Dashboard to open the Dashboard workspace. In the Dashboard JVMs List portlet, click %Heap to sort the JVMs by their %Heap usage. Inspect the JVMs' %Heap and click a JVM that you consider to have high %Heap usage. Information on this JVM displays in other Dashboard portlets. If the JVM Health portlet is not already displayed, use Add Portlet to display it. In the JVM Health portlet, look at the CPU and Heap Usage graph. A JVM with high %Heap usage may be doing excessive garbage collections. In other cases, the JVM may be operating normally for the environment and load. If the Invocation Type Scalability portlet is not already displayed, use Add Portlet to display it. This portlet helps you assess the end-user experience during high CPU usage. In the Invocation Type Scalability portlet, click Portlet Preferences to configure the portlet for the invocation type.
3 4 5 6
68
Compare the portlet graphs to the JVM %Heap in the JVM Health portlet. Is the request Throughput low or decreasing and is the request response time high or increasing during the same period that the %Heap usage is high? If the answer is 'no', then the high %Heap is not correlated to an end-user problem. If the answer is 'yes' then a memory bottleneck may be contributing to a poor end-user experience. If the Memory Metrics portlet is not already displayed, use Add Portlet to display it. This portlet helps you assess the end-user impact of garbage collections. In the Memory Metrics portlet, click Portlet Preferences to configure the portlet to show Average Heap Size, Average Heap Used, Major CG Count, Total GC Count, GC Freed, and Total GC Freed metrics. Analyze these metrics to understand how busy the system is reclaiming memory and whether the end-user experience is suffering as a result. If so, investigate tuning the JVM memory settings. In other cases, the system may be operating normally and you should ask a developer or architect whether the Heap usage, garbage collection time, and end-user experience are normal for the load.
8 9 10
Identifying which tier has a bottleneck

You can use the Dashboard workspace to locate the tier in which a bottleneck occurs. To identify which tier is contributing to poor JVM health 1 2 3 4 5 6 In the Precise for J2EE user interface, click Dashboard to open the Dashboard workspace. If the All JVMs Health and All JVMs Threads portlets are not already displayed, use Add Portlet to display them. Use these portlets to identify the JVMs that appear to be heavily loaded. High response times, high CPU, or high thread counts are all potential indicators of a heavily loaded JVM. In the Monitored JVMs List portlet, click a JVM to investigate. If the Work Time of Invocation Types portlet is not already displayed, use Add Portlet to display it. In the Work Time of Invocation Types portlet, examine the kinds of activities, for example, HTTP or JDBC, that are consuming the largest amounts of time in that JVM.
Detecting a service backlog

A large number of active or long-running threads suggests a possible service backlog and scalability issue. Long-running threads are determined by a default setting in the Precise for J2EE Collector to be those threads active for more than 60 seconds (this default can be overridden with a command-line argument to the collector). To view the number of active threads 1 2 3 4 In the Precise for J2EE user interface, click Dashboard to open the Dashboard workspace. If the All JVMs Threads portlet is not displayed, use Add Portlet to display it. The All JVMs Threads portlet shows threads for all monitored JVMs simultaneously. In the All JVMs Threads portlet, click Edit Preferences. In the Portlet Preferences page, configure the All JVMs Threads portlet to show Concurrent Active and Long Running Threads. Numerous and increasing concurrent active threads indicate that there may be service delays as each thread waits to be serviced. Numerous or fluctuating numbers of long-running threads indicate that threads are waiting or are busy for a long period of time and may indicate a service bottleneck. A consistent number of long-running threads may indicate the normal presence of the running of background services. If the Work Time for Invocation Type portlet is not displayed, use Add Portlet to display it. Note the invocation type having the highest work time. These invocations may be responsible for the backlog and should be further analyzed in the Activity workspace.
Chapter
Examining performance over time in the Activity workspace


About the Activity workspace About Activity workspace tabs How the Activity workspace can help you identify performance problems
About the Activity workspace

The Precise for J2EE Collector agent collects, correlates, and summarizes data on specific data entities and, at the expiration of the aggregation interval, forwards this data to the Archive Agent. The Archive Agent stores this data to enable the user interface to publish Web pages containing performance reports. These pages form the Activity workspace.
About Java virtual machines

The Precise for J2EE Collector collects the following performance data from one or more Java Virtual Machines running on an application server:
Concurrent active thread processing levels
About HTTP, EJB, and portlet service requests

The following are among the wide variety of performance data on HTTP, EJB, and Portlet service requests that the Precise for J2EE Collector collects:

Service time CPU time Throughput URIs Other Invocations, either displayed as direct contributors or as Work Time
Dispatched by the application server to Java Servlets and JSPs. Java Servlets and JSPs usually contain presentation logic and invoke business logic in EJBs. HTTP requests invoked from outside the JVM are called external HTTP service requests and requests invoked from inside the JVM (e.g., from another Servlet or JSP) are called HTTP invocations. HTTP service requests are top-level HTTP invocations, that is, the first HTTP invocation to occur in a given invocation context. The top-level HTTP request serves as the entry point into the application server.
HTTP service requests
Examining performance over time in the Activity workspace About the Activity workspace
70
EJB service requests Dispatched by the application server to Enterprise Java Beans. EJBs typically contain business logic and invoke other EJBs and JDBC calls to a database. EJB requests invoked from outside the JVM are called external EJB service requests, and EJB requests invoked from inside the JVM (e.g., from another EJB) are called EJB invocations. EJB service requests are top-level EJB invocations, that is, the first EJB invocation to occur in a given invocation context. The top-level EJB request serves as the entry point into the application server. Portal service requests In a portal server, the portlet interface typically contains methods such as doView, doEdit, doConfigure, processAction, or doLogin, that have clearly defined tasks and which invoke other Portlets, Beans, or JDBC calls. Portlet requests invoked from outside the JVM are called Portlet service requests, and Portlet requests invoked from inside the JVM (e.g., from another Portlet) are called Portlet invocations. Portlet service requests are top-level Portlet invocations, that is, the first Portlet invocation to occur in a given invocation context which serves as the entry point into the application server. For supported portal servers, Precise for J2EE groups custom type invocations based on the services they provide. Although these groups vary by application server vendor, examples of some of the common invocation types are: PORTAL_GATEWAY: The servlet and set of classes that act as controller servlet. These forward the requests to the appropriate Portlets. PORTAL_AUTHENTICATION: The sets of classes and invocations that provide authentication services for a portal server. PORTAL_CACHE: Invocations that provide caching services. PORTAL: Invocations that provide general portal services.
The Root Activity Type drop-down list lets you control the displayed call trees. The All Threads option is selected by default, and displays all invocations regardless of where they are invoked from. Selecting the HTTP, EJB or Portlet option causes all invocations to be filtered by their root caller's type, respectively. For example, when the HTTP option is selected, all tabs will display data for the trees initiated by an HTTP service request.
About URI, Java class, and method names

Java Servlets, JSPs, and EJB requests are resolved by the application server into executable Java byte-code. The Java byte-code is organized into Java classes and methods. Precise for J2EE identifies invocations by displaying their class and method names. Precise for J2EE also identifies service requests (i.e., top level invocations) by displaying their URIs. Since many URIs may be bound to a Java class by the application server, Precise for J2EE displays the first URI it detects.
About invocations
The Precise for J2EE Collector collects performance data on all instrumented and sampled Java method invocations. Contributor invocations are invocations that contribute to the performance of other higher level invocations. In some reports, contributor invocations are grouped by one of the following types.
HTTP service requests (top level Servlet and JSP invocations) Typically invoke numerous EJBs, JDBC, custom methods, and other HTTP invocations (internally called Servlets and JSPs). HTTP invocations displayed in a Precise for J2EE page must run inside the monitored JVM. HTTP invocations that run remotely are not shown explicitly but are referred to as Work Time. If, for example, the application uses the Java method URL Connection and it is custom instrumented, the remote HTTP invocation will be shown explicitly as a custom invocation. Typically invoke numerous JDBC methods and other EJB methods. EJBs that are invoked from within another EJB service request (internally) are displayed as type EJB, and those EJB calls that run remotely are displayed as type EJBRem. A way to execute SQL queries in a database and to receive the results. A way to invoke SAP transactions from Java.
EJB service requests
JBDC invocations JCo invocations
Examining performance over time in the Activity workspace About Activity workspace tabs
71
Custom
Custom invocations that are not invoked from any other instrumented invocation (they have no parent invocation). Custom threads are not categorized as service requests.
Note: Refer to the Precise Administration Guide to learn how to enable custom instrumentation.
About Work Time

Precise for J2EE displays some performance metrics as Work Time for performance contributions that are not explicitly accounted for with application instrumentation, including raw method instructions. A subset of Work Time is Lock Time, which is collected by the Lock Seeker feature. Lock Seeker tracks the time that a thread takes to acquire a lock, giving an idea of how much time lock acquisition contributes to a method's performance. Reporting Lock Time as a component of Work Time enables Work Time to be a more accurate view of what is contributing to an application's performance.
About invocation context

Precise for J2EE displays performance metrics for every unique invocation context. An invocation context is a sequence of Java invocations, a call path of instrumented methods that identifies a unique location within the instrumented application. The context is used by Precise for J2EE to differentiate the same Java invocations called from multiple locations. For example, if there is more than one context used to invoke an EJB, performance metrics unique to each EJB invocation will be displayed in each of the contexts. Furthermore, if there are two contexts used to invoke an EJB service request, the EJB name will be displayed twice (once for each context) in the EJB service request page. You can display the invocation's context by clicking on the "Call Path" drop-down list on the top left corner of the workspace. You can also click on any entry in the Call Path to navigate to its context (will become selected entity), or clear the path to return to the JVM level.
About Activity workspace tabs

An important concept while viewing Activity tab data is that all tabs display data in context of a selected entity (either JVM or specific method). The selected entity name is shown in the title (to the left of the tabs display). In addition, it is reflected in the Call Path near the Time Frame display. The tabs data is always adjusted to the context, but provides both a deep and a shallow view into the underlying call tree. For example, when a specific method is selected, the Highlights tab shows its service time deep breakdown into predefined components and displays Findings of the problems detected in the method's underlying call tree. The SQL tab provides a Deep Summary view of all statements invoked somewhere under the selected method, along with a detailed view showing all statements with their caller contexts. The navigation between Deep Summary and Per Caller (detailed) views is based on a filtering mechanism. Whenever you wish to focus on an entity in the Deep Summary view (which is by definition an aggregated entity), you can click on its hyperlinked text which will bring you to the Per Caller view with an activated filter. The filter will show the different contexts of that specific aggregated entity only. You can then select a specific context and drill into it; this changes the selected entity of the Activity workspace and all tabs data now refers to the newly selected entity. For example, when viewing Hotspots Deep Summary view on the JVM level, you can spot a specific slow hot spot. You can click it to navigate to the Per Caller view and see all of its underlying contexts. When in the Per Caller view, you can drill into a specific context of the hot spot by clicking on it; now the selected entity is the method (context) and not the entire JVM (all tabs show data in context of the selected method). The following analysis tabs are displayed in the Activity workspace:

Highlights Hotspots

72
Deep Summary Per Caller Call Graph
Invocations Business SQL

Deep Summary Per Caller Deep Summary Per Caller Deep Summary Per Caller
Locks

Exceptions

About the Highlights tab

The Highlights tab in the Activity workspace displays service time deep breakdown into invocation types (such as: HTTP, EJB, JDBC, Locks, etc.) of the selected entity (JVM or method) along with in context Findings. This view reveals performance problems of the entire call tree underlying beneath the specific context. Findings are integrated into the performance data views to provide a better guidance and quicker problem resolution. All findings are shown in context, meaning that for each selected method the findings table will show problems detected in that method or in its descendants. To open the Highlights tab 1 2 Select the required parameters in the Status bar (Time Frame, Instance, and Root Activity Type). In the Activity workspace, click the Highlights tab (default tab).
The table below describes the data displayed in the main graphs (overtime and summarized) in the Highlights tab. Note: A partial data list is shown in the table; additional types (such as: JNDI) are possible. See the Precise Administration Guide.
Table 4-1 Item
Data in the Service Times Breakdown graphs Description

The total service time of the selected JVM or invocation broken into its components by deeply summarizing work times of each invocation type (such as: HTTP, EJB, JDBC, locks, etc.). Deep aggregation of the work time of all HTTP service requests and invocations under a selected context. Deep aggregation of the work time of all EJB service requests and invocations under a selected context. Deep aggregation of the work time of all JDBC calls under a selected context. Deep aggregation of the work time of all Portlet service requests and invocations under a selected context. Deep aggregation of the locking time under a selected context.
Service Times (Summed) Breakdown HTTP
EJB
JDBC Portlet
Lock
73
Table 4-1 Item

Custom JCo
Data in the Service Times Breakdown graphs Description

Deep aggregation of work time for all custom invocations under a selected context. Deep aggregation of the work time of all JCo invocations under a selected context. Deep aggregation of work time of all invocations of the user defined type under a selected context.
User Defined type
The table below describes the Findings table columns displayed in the Highlights tab. Context names that are too long to display are automatically shortened using ellipses. Table 4-2 Item
Rank (Default)
Findings table columns in the Highlights tab Description

The severity of a finding in terms of acuteness to application performance (red - high, yellow medium, green - low). For a method-related findings rank is based on the work time contribution in terms of % out of total service time. For JVM related findings (statistics), rank is based on the deviation from predefined thresholds. Location where a performance problem occurred; it can be either a JVM-related finding or a specific invocation context. Processing time of the context (invocation) as a percentage out of the selected entity's (JVM or invocation) service time.
Context (Default)
Work Time (%) (Default)
About the Hotspots tab

The HotSpots tab displays instrumented methods ranked by the percent of their contribution to the performance of the current context. The percentage for a method includes the methods time everywhere it is executed within the current context (throughout the underlying methods call tree), excluding recursion, when Service Time and CPU Time are the selected measurements. (Work Time measurements include a call's work time.) The Hotspots tab provides a flat view of the contributing methods from the entire sub call tree. This view provides direct shortcuts into the trees deeper slow invocations by quickly displaying them (rather than drilling into each and every method in the call path via the Invocations tab). This view (together with Highlights) is very useful for pinpointing problems and reducing the time to resolution. For each method, the HotSpots tab displays the method's aggregate contribution percentage of the selected metric, total number of invocations, average service time, average CPU time, and CPU Bound percentage (ratio of the CPU time to the service time). By default, the HotSpots tab lists the methods in descending order from those with the greatest time percentage to those with the least percentage of the selected measure. You can re-sort the list of methods by clicking on the column headings. The following table shows the list of possible columns to display in the Hotspots table (different views display different columns): Table 4-3 Item Table columns in the Hotspots tab Description Deep Summary View
+ (default) -
Per Caller View

+ (default) -
Call Graph View

+ (default) + (default)
Method Name Findings Category Work Time (%)
The full name of the invocation. Classifies grouping performance problems. Processing time of the context (invocation) as a percentage out of the selected entitys JVM-related finding, or a specific invocation context. Number of contexts executions.
Invocations
+ (default)
+ (default)
+ (default)
74
Table 4-3 Item
Table columns in the Hotspots tab Description Deep Summary View Per Caller View
-
Call Graph View

+ (default)
Service Time (%)
The percentage of the contexts service time out of the selected entitys (JVM or invocation) service time. The contexts average service time. The contexts accumulated service times. + (default) + (default)
Avg Service Time (ms) Summed Service Time (ms) Avg CPU Time (ms)
+ (default) +
+ (default)
The average amount of time consumed by the operating system actively processing instructions on behalf of a running method. The CPU time includes time spent locally (work time) plus all CPU time in instrumented calls.
Summed CPU Times (ms)
The total amount of time consumed by the operating system actively processing instructions on behalf of a running method. The CPU time includes time spent locally (work time) plus all CPU time in instrumented calls. The context within which a method is invoked. For example, if Method A is invoked from Method B and Method C, the invocation context for the performance metrics collected for Method A is different when Method A is invoked from Method B than when it is invoked from Method C.
Invocation Context
Advice
In Precise for Oracle, an algorithm that is designed to recommend on gathering statistics, creating new indexes, changing existing indexes, and adding or deleting hints to make Oracle's Optimizer choose a better access path and make the statement perform better. Can be activated from any DML (Data Manipulation Language) statement. The type assigned to the monitored method. The contexts accumulated work times.
Type Summed Work Times (ms) Summed CPU Work Times (ms)
+ + (default)
+ + (default)
+ +
The total time spent on everything not directly + accounted for by instrumentation, including the invocation time or CPU time. If you are looking for high CPU consumers per method this is the metric to use. The direct method that called this method. The root method of the invocation tree from which the method was called. + (default) + (default)
Caller Root Caller
About the Hotspots - Deep Summary view

The Hotspots - Deep Summary view provides a comprehensive insight into the different existing hot spots without repeating them for each context. It is advised to first locate the heaviest hot spots of interest in this view, and then focus on their underlying contexts by using the Hotspots - Per Caller view.
75
To open the Hotspots Deep Summary view 1 In the Activity workspace, click the Hotspots tab, and then click Deep Summary (default screen).
About the Hotspots - Per Caller view

The Hotspots - Per Caller view displays all hot spots with their separate contexts. In other words, if a method was called from different call paths in the invocations tree, and it is a hot spot, there will be several rows displayed for it (one per call path). Even though the method name will be the same, its ToolTip will show the distinct call path that invoked it. Once a particular hot spot of interest is identified, you can continue its investigation by following provided launches. You can either launch into the hot spots context, or into its caller context. To view all separate contexts of a specific aggregated hot spot, click on the "method name hyperlink" - the Per Caller view opens showing only relevant contexts (by using a filter). Alternatively, you can access "Per Caller" view directly by not filtering out any hot spots To open the Hotspots - Per Caller view 1 2 In the Activity workspace, click the Hotspots tab, and then click Per Caller. Or in the Activity workspace, click the Hotspots tab, and click on the specific row in the Deep Summary View table.
The Hotspots - Per Caller view displays Hotspots Summarized by Name and Call Path. The top n hot spots are displayed in the overtime graph. This graph displays the metric by which the table is sorted; sort by a different column and the graph will change accordingly.
About the Hotspots - Call Graph view

The Hotspots - Call Graph view provides a visual representation of the applications instrumented method calls for the selected time frame and context. Nodes in the Call Graph represent methods in the current SmarTune context. Arrows connecting the nodes represent the call path relationship between methods. The colors of the nodes and the percentage labels on the arrows indicate the methods contribution to the SmarTune contexts time. Thresholds for identifying a methods contribution as: high, medium, low, or very low are set in the Findings Administration page. See About the Findings Administration page on page 20.. The Hotspots - Call Graph view is divided into two panels: Full View and Focus View. To open the Hotspots Call Graph view 1 In the Activity workspace, click the Hotspots tab, and then click Call Graph. The Hotspots Call Graph view displays hotspots Call Graph, together with a complete hotspots list (table).
About the Full View panel

The Full View panel, at the right of the Call Graph view, provides a small-scale view of the entire Call Graph that was analyzed. The box outline represents the portion of the Call Graph that is displayed in the Focus View. Clicking in the Full View panel positions the box outline and selects an area of the Call Graph for display in the Focus View panel. Panning in the Focus View, or clicking a method's color icon column in the hotspots table row, updates the position of the box outline in the Full View panel.
About the Focus View panel

The Focus View panel, at the center of the Call Graph tab, provides a large-scale view of the portion of the Call Graph within the box outline in the Full View panel. Clicking on a node in the Focus View filters the hotspots table to contain a selected method only (with all its contexts). You can adjust the Focus View by clicking in the Full View, or by using the eight pan controls.
About the Invocations tab

The Invocations tab displays the method invocations in context.
76
By default (on the JVM level) the Invocations tab displays the top-level invocations (threads) that instrumentation detected for the displayed time range. Threads are named using their top-level invocation class and method names. For portal servers, the invocations are listed by the portlet name. Clicking the portlet name displays the methods it invoked. Measurements are displayed for all top-level invocation types including: HTTP, EJB, portlet, JDBC, JCo, or Custom. Note: In some cases, when instrumentation of a caller method is omitted, the methods invoked by the caller (that is, the callee) are shown in this page as separate top-level invocations. Furthermore, when the caller is instrumented, the invoked methods will no longer be top-level invocations and will be contained within the caller top-level invocation. The Concurrent Active Threads (CATs) measurement indicates how busy the system was during a slice or series (not shown by default, it can be added using the column chooser icon displayed to the right of the table). For example, if two threads are active for the entire display interval, the active threads measurement is two. If one thread is active for half of the display interval, the active threads measurement is 0.5. If an invocation is active across an aggregation interval boundary, the Concurrent Active Threads (CATs) measurement will account for the long running invocation. In contrast, invocation service times are reported only when the invocation completes. When your displayed time range is a time series, the metric displayed in the table is an average across all slices. Each point in the graph is the average value for that slice. When the Root Activity Type drop-down list is used, it is easy to filter invocations for the specific type of the top-level service request. The HTTP, EJB, and Portlet Service Requests views display performance metrics that summarize EJB, HTTP, and portlet service request invocations. These pages provide a good view of dynamically-generated pages used to enter the monitored application. Each service request is identified by its Java class and method name, and is a unique invocation context. A bar or line graph is also displayed to enable you to easily compare performance metrics. For portal servers, the Portal Service Requests page lists the portlet name. Clicking on the portlet name displays the methods it invokes. Click on the hyperlinked invocation name to navigate (drill down) to the invocation details and analyze contributors to the invocation of interest. To open the Invocations tab 1 In the Activity workspace, click the Invocations tab. The Invocations tab displays Method Invocations in Context. The top n methods are displayed in the overtime graph. This graph shows the metric by which the table is sorted; sort by a different column and the graph will change accordingly. The table below describes the data displayed in the Invocations tab. Table 4-4 Item
Chart Legend Color Method Name URI Type Avg Service Time (ms) Invocations Summed Service Times (ms) % Service Time % CPU Time
Default table columns in the Invocations tab Description

Color icon showing the color representing the row in the graph. The full name of the invocation. Displayed when HTTP is selected in the Root Activity Type combo box only. Displayed when All Threads is selected in the Root Activity Type combo box only. The contexts average service time. Number of contexts executions. The contexts accumulated service times. The percentage of the methods service time from the method which called it. The percentage of the methods CPU time from the method which called it.
77
About the Business tab

The Business tab contains aggregated data for the methods included in business transactions that contributed to response time during the current time frame. Clicking a business transaction in the Business tab displays the methods that were included in the business transaction (by launching to the Invocations tab). In order to display data for business transactions, at least one business transaction must be created for the selected JVM. See About the Business Transactions Administration page on page 27. Note: At times, you may notice that data on a business transaction changes or disappears. This is a result of changes in instrumentation made by Adaptive Instrumentation or Over-Instrumentation Protection. For example, if Adaptive Instrumentation was run after the business transaction was created, Adaptive Instrumentation may have disabled instrumentation for methods that were included in the business transaction, in order to meet the overhead budget. As a result, the business transaction will not display data, or the data displayed may be incomplete. To open the Business tab 1 In the Activity workspace, click the Business tab. The table below describes the table columns displayed in the Business tab. Table 4-5 Item
Business Transaction Avg Service Time (ms) Max Service Time (ms) Avg CPU Time (ms)
Default table columns in the Business tab Description

The user defined name that identifies a business transaction. The contexts average service time. The contexts maximum service time. The average amount of time in milliseconds consumed by the operating system actively processing instructions on behalf of a running method. Number of contexts executions.
Invocations
About the SQL tab

The SQL tab displays a list of the top SQL statements with their JDBC times and executions. An overtime graph shows the top statements for a selected measurement. The tab is divided into Deep Summary and Per Caller views. Once you identify a statement that you wish to analyze, you can click on the texts hyperlink to access the Per Caller view. The Per Caller view will be filtered to show all that statements appearances (contexts). A ToolTip on the SQL text column provides a complete call path to the method that invoked this statement. If you find a problematic SQL statement, you can also print the text of the page, take it to your DBA, and ask him to optimize its performance. The following table shows the list of possible columns to display in the SQL tab table (different views display different columns). Table 4-6 Item Possible table columns in the SQL tab Description Deep Summary View
Per Caller View

Chart Legend Color SQL Text
Color icon showing the color representing the row in the graph. The text of the SQL statement. The ToolTip provides the complete text, especially useful when the text is long and concatenated.
78
Table 4-6 Item
Possible table columns in the SQL tab Description Deep Summary View
+ (default)
Per Caller View

+ (default)
Summed JDBC Times (ms)
The summed service times that are attributed to invoking JDBC calls. The average service time that is attributed to invoking JDBC calls. Number of times the statement was invoked during the time frame. The method that is directly invoking the statement. The URI of the Root Caller, relevant for HTTP requests as the root activities.
Avg JDBC Time (ms)
+ (default)
+ (default)
SQL Executions
+ (default)
+ (default)
Root Caller URI
+ +
About the SQL - Deep Summary view

The SQL - Deep Summary view shows statements aggregated by their SQL text (not depending on any specific invocation context). This view provides a top-down overview of the statements executed somewhere along the call tree, below the selected JVM or method. To open the SQL - Deep Summary view 1 In the Activity workspace, click the SQL tab, and then click Deep Summary. The SQL Deep Summary view displays SQLs Summarized by Statement. The top n SQL statements are displayed in the overtime graph. This graph shows the metric by which the table is sorted; sort by a different column and the graph will change accordingly.
About the SQL - Per Caller view

The SQL - Per Caller view provides a more detailed statements list showing statements aggregated both by text and caller method. Since many of the statements are invoked from the same JDBC methods, a root caller is also displayed to provide a more complete context. You can either drill to focus on the single SQL statement, or launch its caller or root caller context for reviewing all statements and additional information in that context. To open the SQL - Per Caller view 1 In the Activity workspace, click the SQL tab, and then click Per Caller. The SQL Per Caller view displays SQL Statements Grouped by Statement and Caller. The top n SQL statements are displayed in the overtime graph. This graph shows the metric by which the table is sorted; sort by a different column and the graph will change accordingly.
About the Single SQL Statement screen

If Precise for any DB product (Oracle, SQL Server, Sybase, DB2) is installed, once you drill into a single SQL statement, you will see an Precise launch button on the upper right part of the screen. Click the button to open that Precise for product in the context of the displayed SQL statement. This launching capability allows the DBA to quickly find the SQL statement, analyze it, and tune its performance. Whenever the SQL text hyperlink is clicked in the Per Caller view, the Single SQL Statement view is displayed. This view displays statement details, such as: JDBC time, number of executions, full text and more, along with the JDBC time overtime graph.
79
About the Locks tab

The Locks tab shows the methods that have the longest average lock acquisition time across the application for the given time frame and context. For each context, the Locks tab shows the average lock acquisition time, the number of locks acquired, and the total lock time. The lock identifier is calculated at runtime. It is based on the object name that is being locked (synchronized). It is possible to use the same object more than once during the same method. In that case, Precise for J2EE adds an index for each of the lock events, in order to enable the developer to distinguish between the two lock events. For example: Public void foo(){ //run some code... Synchronized (myLockObject){// will be labeled as myLockObject+0 //run some synchronized code... ) //run some more code... // and then we need to have another synchronized block, locking the same object as before Synchronized (myLockObject){// will be labeled as myLockObject+1 // run some more synchronized code... ) } The tab is divided into Deep Summary and Per Caller views. Once you identify a lock you wish to analyze, you can click on its name hyperlink to access the Per Caller view. The Per Caller view will be filtered to show all of that locks appearances (contexts). The following table shows the list of possible columns to display in the Locks tab table (different views display different columns). Table 4-7 Item Table columns in the Locks tab Description Deep Summary View
Per Caller View

Chart Legend Color Data Source
Color icon showing the color representing the row in the graph. The lock identifier. For calculation, see About the Locks tab on page 79. The average time it takes a method to acquire a lock. The number of successful lock acquisitions. The total time it takes a method to acquire a lock. The type of root caller invocation. The displayed invocation types may include: HTTP, EJB, EJB Remote, JDBC, Custom and more. The top level method that started the chain that ultimately invoked the locking method. The method that is directly invoking the locking method.
Avg Lock Time (ms) Lock Acquisitions Summed Lock Time (ms) Root Caller Type
+ (default) + (default) + (default) -
+ (default) + (default) + (default) +
Root Caller
Caller
- (default)
80
About the Locks - Deep Summary view

The Locks - Deep Summary view shows locks aggregated by their name (not depending on any specific invocation context). This view provides a top-down overview of the locks acquired somewhere along the call tree below the selected JVM or method. A ToolTip on the data source column provides a complete call path to the method that invoked this lock. To open the Locks - Deep Summary view 1 In the Activity workspace, click the Locks tab, and then click Deep Summary. The Locks Deep Summary view displays Locking Methods Summarized by Name. The top n locks are displayed in the overtime graph. This graph shows the metric by which the table is sorted; sort by a different column and the graph will change accordingly.
About the Locks - Per Caller view

The Locks - Per Caller view provides a more detailed list, showing locks aggregated both by text and caller method. You can launch the lock's caller method for reviewing all locks and additional information in that context. In addition, the caller column provides a ToolTip showing the complete call path into that method. You can launch to any method in the call path. To open the Locks - Per Caller view 1 In the Activity workspace, click the Locks tab, and then click Per Caller. The Locks Per Caller view displays Locks Summarized By Caller and Context. The top n locks are displayed in the overtime graph. This graph displays the metric by which the table is sorted; sort by a different column and the graph will change accordingly.
About the Exceptions tab

Precise for J2EE catches exceptions during a time slice, based on the instrumentation configuration (switched off by default) and filtering criteria. See Precise Administration Guide, Appendix A, regarding configuring exception seeker options. The exceptions can be seen in the Activity workspace under the Exceptions tab. Precise for J2EE displays both deep and shallow views of exceptions thrown from the current context (usually JVM or method). The Exceptions tab displays an exceptions summary table along with an overtime graph. The tab is divided into Deep Summary and Per Caller views. Once you identify an exception you wish to analyze, you can click on its name hyperlink to access the Per Caller view. The Per Caller view will be filtered to show all exceptions. The following table shows the list of possible columns to display in the exceptions table (different views display different columns). Table 4-8 Item Possible table columns in the Exceptions tab Description Deep Summary View
+ (default) + (default) -
Per Caller View

+ (default) + (default) + (default)
Chart Legend Color Thrown Class Location
Color icon showing the color representing the row in the graph. The class name that was thrown. Class and method from which the class was thrown, including the line number in the source code. Number of times that an exception occurred during the selected time frame. The message that was set in the thrown class. The exception cause (if available).
Exception Count
+ (default)
+ (default)
Exception Message Exception Cause
+ (default) +
Examining performance over time in the Activity workspace How the Activity workspace can help you identify performance problems
81
Table 4-8 Item
Possible table columns in the Exceptions tab Description Deep Summary View
-
Per Caller View

+ (default) + + (default) + (default)
Stack Trace Root Stack Trace Last Detected On Caller
The root of the stack trace. The stack trace of the thrown class The last time that this class was thrown within the time frame. The direct calling method where the exception was thrown.
About the Exceptions - Deep Summary view

The Exceptions - Deep Summary view displays all aggregated exception classes thrown from somewhere in the current contexts sub call tree. To open the Exceptions Deep Summary view 1 In the Activity workspace, click the Exceptions tab, and then click Deep Summary. The Exceptions Deep Summary view displays Exceptions Summarized By Class.
About the Exceptions - Per Caller view

The Exceptions - Per Caller view displays all aggregated exception classes thrown from somewhere in the current contexts sub call tree, but detailed per their thrown class. You can launch the caller methods context to continue investigation. In addition, caller column provides a ToolTip showing the complete call path into that method. You can launch to any method in the call path. To open the Exceptions - Per Caller view 1 In the Activity workspace, click the Exceptions tab, and then click Per Caller. The Exceptions - Per Caller view displays Exceptions Summarized by Class and Stack Trace Root. The top n exceptions are displayed in the overtime graph. This graph shows the metric by which the table is sorted; sort by a different column and the graph will change accordingly.
How the Activity workspace can help you identify performance problems
The Activity workspace enables you to drill down into detailed performance data for the JVMs you are monitoring in order to analyze and isolate performance bottlenecks.
Analyzing performance bottlenecks using SmarTune findings

Use SmarTune to perform a more comprehensive identification of significant contributors and hot spots. SmarTunes analysis is context sensitive, so that only the path beneath and your current location, known as the context, is analyzed.
Analyzing Java method contributions to application performance

SmarTune findings display the results of the analysis of Java method contributions to application performance. To analyze Java method contributions 1 2
Select a time frame to analyze. In the Activity workspace, select the application context to analyze:
To analyze all methods in the application, select the All Threads option (default) in the Root Activity Type drop-down list.

82
To analyze only HTTP Service Requests, or EJB Service Requests, or Portlet Service Requests, select HTTP, or EJB, or the Portlet option in the Root Activity Type drop-down list. To analyze the invocations under a specific method context, display that method context (in the Activity workspace) by drilling into it in the Invocations or Hotspots tab.
In the Activity workspace, click the Highlights tab (default tab). When you display the Highlights tab, SmarTune analyzes the instrumented Java method invocations under the selected context. SmarTune displays the results of analysis for each contributor category (finding type). These are the Java technologies and their methods that comprise the application time. The method where a finding was detected is displayed as the findings context. The finding type is a hyperlink to more detailed information. Hover over the finding for each of the highest-ranked significant time contributors that show the specific context and are not a JVM related finding. SmarTune displays a description of the finding, advice for its resolution, and recommends the next steps. Click on the finding link to navigate to the Hotspots tab and view the supporting data. The relevant hot spot is displayed together with its measurements, overtime graph, and the underlying contexts in the Per Caller view. In the Activity workspace, click the Hotspots tab, and then click Call Graph to display a visualization of the Java method contributors. The Graph nodes represent instrumented methods; the arrows connecting the nodes indicate the invocation call path. The color of a node indicates the methods contribution toward the SmarTune contexts total time. Red methods have the highest severity; they contribute the most time toward the applications total time. Yellow has a medium severity, and green has the lowest severity; they each contribute progressively less time toward the applications total time.
5 6
Analyzing application server performance

Use SmarTune application summary categories to better understand application server performance issues, such as: excessive garbage collection time, exhausted database connections, or limited execute thread pools. Application summary categories are specific to each monitored JVM. To analyze application server performance 1 2 Select a time frame to analyze. In the Activity workspace, click the Highlights tab (default tab). When you display the Highlights tab, SmarTune analyzes the instrumented JVM, the application servers Java Management Extensions (JMX), and displays the results by topic (finding type). Problematic performance contributors are listed at the top with the highest (red) severity. The finding type is a hyperlink to more detailed information. Hover over the finding for each of the highest-ranked significant findings, labeled as JVM related finding. SmarTune displays a description of the finding, advice for its resolution, and recommends the next steps. Click on the finding link to navigate to the Statistics tab and view the supporting data. The relevant statistics counter is displayed together with its overtime graph.
3 4
Identifying slow HTTP service requests (Servlets or Java Server pages)

If the Dashboard workspaces Invocation Type Scalability portlet identifies high HTTP Service Time, then you should investigate the root cause of the long service time. The long service time may be caused by a number of contributing factors, such as: poorly performing SQL or third party libraries. To analyze the performance of your Servlets or Java Server Pages 1 2 3 Select a time frame to analyze. To identify contributors to slow service requests, choose a time period where the service time is poor. In the Activity workspace, click Highlights to view the Highlights for the selected JVM. You can either continue viewing all threads data, or select the HTTP entry in the Root Activity Type drop-down list. Using the service time breakdown graphs, verify whether the HTTP invocations appear to be a significant contributor to the JVM service time. In the Findings list, focus on severe problems and review their contexts.
83
4 5 6 7
Follow a specific finding's link to launch the Hotspots tab's Deep Summary view. The display is filtered to contain only relevant hot spots, sorted by their work time percentage out of the total service time. Review specific hot spots contexts in the Hotspots - Per Caller view and select the heaviest contributor or other hot spots of interest. Drill down into the hot spot's context. You can also drill down into any method in its call path (by using a call path display in the ToolTip of the direct caller method). For the selected context, explore its hot spots, findings, or other measurements (such as: top SQL statements, locks, or exceptions).
Isolating slow database queries

If the Dashboard workspace's JDBC Metrics portlet identifies JDBC Time, then you should investigate the root cause of the long JDBC Time. Sometimes the long service time is caused by one or more poorly performing SQL statements. To analyze the performance of your SQL statements for a time slice or series 1 2 Select a time frame to analyze. In the Activity workspace, click the SQL tab. The Deep Summary view opens, displaying all statements invoked from across the application. All different contexts of the same statement are aggregated to provide a high level breakdown of the top-heaviest statements. Investigate the top SQL statements list. To view the full text, use the ToolTip on the SQL Text column. To view all invocation contexts of a specific statement, launch the Per Caller view from the statement's row; the view opens filtering only relevant statements. Drill down into the specific statement to view more details. If an Precise product for the relevant database is installed, click on the launch button (on the upper right part of the screen) to proceed with a deeper investigation of the statement.
3 4 5 6
Identifying CPU consumers

If the Dashboard workspace's All JVMs Health portlet identifies high CPU Time for a JVM, then you should investigate the root consumer of the CPU time. Sometimes the CPU time is consumed by a few poorly performing methods. To analyze the CPU time of your methods for a time slice or series 1 2 3 4 5 Select a time frame to analyze. In the Activity workspace, click the Invocations tab. By default All Threads are shown. Sort the Invocations list by the CPU time percentage used by each thread. If additional CPU measurements are required, use the icon to the right of the table that enables adding columns to the list. Drill down into the invocation with the highest percentage (or other measurement), to see its contributors ranked by their percentage contribution to the caller's CPU time. In addition, you can view other data for the selected invocation using: Highlights, Hotspots, SQL, Locks, and Exceptions tabs.
Viewing business transaction performance for specific application functions

Business Transactions allows you to group methods that perform specific application functions and monitor them as a single entity. For example, in an application that accepts student admissions applications, you can create a business transaction to monitor application submission. In this business transaction, you would include all the methods that the application calls when a student submits an application. Use the Business Transactions administration page to create business transactions. See About the Business Transactions Administration page on page 27.
84
To monitor the business transaction in the Dashboard workspace, add the Top Business Transactions portlet to a Dashboard page. See About the Top Business Transactions portlet on page 64. If the Top Business Transactions portlet shows high response time for a business transaction, investigate the root cause by examining the business transaction in the Activity workspace Business tab. To view details of business transaction performance 1 2 3 4 5 Select a time frame to analyze. In the Activity workspace, click the Business tab. The list of all monitored business transactions is displayed. Sort the list according to service time, CPU time, or other metric to be analyzed. Select the business transaction with the highest metric value. In the Activity workspace, click the Invocations tab. The Invocations tab displays the methods included in the business transaction. Continue investigating the heaviest invocations using: Highlights, Hotspots, and other analysis tabs.
Chapter
Examining application server metrics in the Statistics workspace


About Statistics workspace tabs How the Statistics workspace can help you identify performance problems
About Statistics workspace tabs

The Precise for J2EE Collector collects performance metrics provided by WebSphere, WebLogic, and other application servers. These application server metrics are displayed in the Statistics workspace. The application servers collect the metrics and provide an interface for the Precise for J2EE Collector to obtain them. Depending on the application server, the Precise for J2EE Collector may log into the administrative server of the monitored JVM to gather the metrics or obtain the metrics in other ways. These metrics provide an important source of performance data for Database Connection Pools, EJB Pools and Caches, Sessions, and Threads. Precise for J2EE identifies a set of similar metrics using a Group Name. For example, the Database Connection Pool group includes many metrics describing a Database Connection Pool such as maximum capacity, active connections, and so on. Note: Application Server Metrics must be enabled using the post-installation tasks that appear in the Precise Agent Installer after installing the Precise for J2EE AppTier. See the Precise Installation Guide for information on post-installation tasks for each J2EE application server. The following analysis tabs are displayed in the Statistics workspace:

Findings Counters
The following table shows the list of possible columns to display in the Findings tab. The table below describes the Findings table columns displayed in the Findings tab. Context names that are too long to display are automatically shortened using ellipses. Table 5-1 Item
Rank
Default Findings table columns in the Findings tab Description

The severity of a finding in terms of acuteness to application performance (red - high, yellow medium, green - low). A method-related findings rank is based on the work time contribution in terms of % out of total service time. For JVM related findings (statistics), rank is based on the deviation from predefined thresholds.
Examining application server metrics in the Statistics workspace About Statistics workspace tabs
86
Table 5-1 Item

Type
Default Findings table columns in the Findings tab Description

Finding a category for classifying and grouping performance problems. Statistics findings categories are derived from the counters (metrics) that fall to meet best practices thresholds. A short explanation of the finding.
Description
When clicking on the hyperlinked findings type column, its relevant overtime graph is displayed at the bottom. The first findings graph is shown by default. Each findings type has a ToolTip with a findings description, link to the relevant metrics data (which opens the Counters tab filtered to display metrics details), and a link to more help. The more help link displays the contributors (metrics) impact on the applications health, and gives advice to reduce its negative contribution. A chart shows the values and trend of the contributor over the selected time frame.
About the Findings tab

The Statistics - Findings tab analyzes the entire application for the selected time frame, to show trends in the overall applications health. Green check marks and red icons give a quick visual indication of metrics to the applications health for all application servers, as well as for other application server-specific JMX-based metrics. In order for Application Summary pages to show server-specific JMX-based metrics, statistics data collection must be enabled in the Statistics Administration page. See About the Statistics Administration page on page 44.. To open the Findings tab 1 In the Workspace Selection bar, click Statistics, and then click the Findings tab. The following icons indicate the status of the metrics collected:
Metrics collection state is enabled. Metrics collection state is unknown. Metrics collection state is disabled.
About the Counters tab

The Application Server Counters tab displays a list of measurements that are applicable to the metric category selected in the Categories drop-down list (near the Instance drop-down list). Each item in the list is a specific application component or resource instance (data source), sorted in descending order by its value. Each column in the table displays a specific counter (metric) which was defined to be collected under the selected category. The table displaying the measurements list has the following structure:

The Data Source column appears for all categories All other columns are displayed according to monitored counters of that category.
To open the Counters tab 1 In the Workspace Selection bar, click Statistics, and then click the Counters tab. The top n counters are displayed in the overtime graph. This graph displays the metric by which the table is sorted; sort by a different column and the graph will change accordingly. Warning: Application server overhead will increase when the application server collects the metrics and when the Precise for J2EE Collector gathers them. Refer to the application server documentation for further details.
Examining application server metrics in the Statistics workspace How the Statistics workspace can help you identify performance problems
87
How the Statistics workspace can help you identify performance problems
Use the Statistics workspace to investigate metrics relating to application server performance.
Investigating database connection pool size

When the Dashboard JDBC Metrics portlet shows high database connection times (while the SQL Statements portlet shows consistently low query service times), you may have a problem with the JVMs database connections. Use the Statistics workspace to investigate this problem. To investigate database connection pool size 1 2 In the Dashboard workspace JVM List portlet, select a JVM that you are monitoring. Selecting the JVM displays information for the JVM in other Dashboard portlets. In the Dashboard workspace, view the JDBC Metrics and SQL Statements portlets. Service time spikes for the JDBC Metrics, but consistent performance for the SQL Statements, suggest that the JVMs connection pool size may be too small. In the Workspace Selection bar, click Statistics to open the Statistics workspace. If application server metrics have been enabled for the JVM, you will see SmarTune Findings and categories of metrics. The groups and names of the metrics displayed depend on the application server vendor and version. In the Findings tab, explore findings, or in the Counters tab, explore the metrics category that relates to JDBC connections (to display the individual metrics of that type). Note the total number of connections that you have. In the Findings tab, notice that SmarTune has found a JDBC Connection Pool Service Time contributor. Click on the more help hyperlink for the contributor. SmarTune displays advice to increase the DB Connection Pool Size. Adjust your application and wait until the JDBC methods are again called to verify that the problem is fixed.
4 5 6 7
Chapter
Examining usage and trends in the Memory workspace


About the Memory workspace About the Memory workspace tabs
About the Memory workspace

The Memory workspace displays two performance tabs by default: JVM Heap Memory and Garbage Collection. Additional graphs and charts show Leak Seeker data (number of live objects or size and trend of collections, arrays, or string buffers, as well as allocating methods). The Leak Seeker data will also be displayed (under the Leak Seeker tab) if the monitored JVM has been configured in the Java Virtual Machine Settings page to collect Leak Seeker data. See About the Java Virtual Machine Settings Administration page on page 15.
About the Memory workspace tabs

The following analysis tabs are displayed in the Memory workspace:

Heap Garbage Collection LeakSeeker
About the Heap tab

The Heap tab displays memory usage graphs along with relevant SmarTune findings. The overtime and the summary graphs display memory size data broken into used and free memory components (both in absolute measurements and percentage). In addition, the minimum size, maximum size of heap memory, total allocated and used for the measurement interval are shown below the graphs. The findings warn about memory related problems. Each finding type has a ToolTip with the findings description and a link to more help. Both finding types hyperlinked text and more help link show the findings impact on an applications health and gives advice to reduce its negative contribution (if applicable). A chart shows the values and trend of the contributor over the selected time frame. Note that green findings are also shown to indicate that memory usage is normal. To open the Heap tab 1 In the Workspace Selector bar, click Memory, and then click the Heap tab.
Examining usage and trends in the Memory workspace About the Memory workspace tabs
89
The table below describes the data displayed in the Heap tab. Table 6-1 Item
Rank
Default table columns in the Heap tab Description

The severity of a finding in terms of acuteness to application performance (red - high, yellow medium, green - low). A method-related findings rank is based on the work time contribution in terms of % out of total service time. For JVM related findings (statistics), rank is based on the deviation from predefined thresholds. Finding a category for classifying and grouping performance problems. A short explanation of the finding.
Type Description
About the Garbage Collection tab

The Garbage Collection tab displays garbage collection time graphs along with relevant SmarTune findings. The overtime and summary graphs display the percentage of the current measurement intervals time spent collecting garbage. The number of major collections observed and the total amount of memory collected by major collections are displayed below the graphs. The findings war about garbage collection related problems. Each finding type has a ToolTip with the findings description and a link to more help. Both finding types hyperlinked text and more help link show the findings impact on an applications health and gives advice to reduce its negative contribution (if applicable). A chart shows the values and trend of the contributor over the selected time frame. Note that green findings are also shown to indicate that memory usage is normal. To open the Garbage Collection tab 1 In the Workspace Selector bar, click Memory, and then click the Garbage Collection tab. The table below describes the data displayed in the Garbage Collection tab. Table 6-2 Item
Rank
Default columns in the Garbage Collection tab Description

The severity of a finding in terms of acuteness to application performance (red - high, yellow medium, green - low). A method-related findings rank is based on the work time contribution in terms of % out of total service time. For JVM related findings (statistics), rank is based on the deviation from predefined thresholds. Finding a category for classifying and grouping performance problems. A short explanation of the finding.
Type Description
About the Leak Seeker tab

The Leak Seeker tab displays details about the top 64 allocation sites with the largest total live allocated objects in the selected time frame. Each allocating method displays the collections stack trace in its ToolTip. The stack trace displays the invocations leading backwards from the allocation site to the applications initial invocation. For the top n allocating methods, the chart shows the approximate number of live objects in the collection, or its growth rate (according to the sorting column). Negative trends can be identified using these charts by detecting memory leaking locations. To open the LeakSeeker tab 1 In the Workspace Selector bar, click Memory, and then click the LeakSeeker tab.
Examining usage and trends in the Memory workspace About the Memory workspace tabs
90
The table below describes the data displayed in the JVM Leak Candidates by Allocation Trace. Table 6-3 Item
Chart Legend Color Allocating Method Object Type Live Object Count Growth Rate (inv/exec)
Default columns in the JVM Leak candidates table Description

Color icon showing the color representing the row in the graph. The method name where the object was allocated. The Object, Collection, Array, or String Buffer. Number of objects currently allocated by the allocating method. Rate of growth of the number of objects over time (objects/minutes).
Appendix
Configuring Precise for J2EE instrumentation


About using custom instrumentation About using the instrumentation configuration utility
About using custom instrumentation

Precise for J2EE provides default and recommended instrumentation configuration via Monitoring Configuration. See About Monitoring Configuration on page 29. To target your application with finer granularity, you can create custom instrumentation configurations. Custom instrumentation lets you manually instrument classes that are not included in the default Precise for J2EE monitored classes. It also lets you exclude classes that are monitored by default. To use custom instrumentation, you must edit the appropriate instrumentation configuration file and be sure that the edited file is uncommented in the InstrumenterConfigList.xml file, the configuration file that Precise for J2EE uses to keep track of your instrumentation configurations. Note: There are some minor variations to code format between using Monitoring Configuration or performing custom instrumentation manually. Nevertheless these minor variations are acceptable.
Note: Using custom instrumentation requires knowledge of Java language constructs. Refer to an introductory Java language or programming primer for an explanation of Java language concepts.
Note: Unless you have very specific instrumentation needs, consider using the adaptive instrumentation and instrumentation explorer features in the Precise for J2EE user interface, rather than custom instrumentation. Adaptive instrumentation automates custom instrumentation to provide application information most relevant to finding performance problems, but without exceeding overhead levels that you set. Although not intended for massive amounts of custom instrumentation, the instrumentation explorer provides a user-friendly interface for fine-tuning the selected instrumentation settings. For more on adaptive instrumentation and the instrumentation explorer, see the Precise Administration Guide.
About modifying instrumenter configuration files

Instrumentation instructions are contained in a series of XML files that can be found in the Precise for J2EE agent installation on the host where the monitored JVM runs. The InstrumenterConfigList.xml file, which also exists in each monitored JVMs configuration directory, references the instrumentation configuration files. See About instrumenter configuration file reference on page 108.
Configuring Precise for J2EE instrumentation About using custom instrumentation
92
How you modify your instrumentation configuration depends on what you try to do:
To enable a single existing instrumentation configuration that was not enabled by default, you can enable this configuration by uncommenting the reference to the file in the InstrumenterConfigList.xml file. To change the instrumentation instructions within a specific instrumentation configuration file, for example to instrument a specific method, you would modify the Custom.xml file (or any other instrumenter configuration XML file). In addition, you must verify that this instrumentation configuration file is enabled in the InstrumenterConfigList.xml file.
Note: By default, the custom instrumentation configuration files are located in the instrumenter directory: <i3_root>/products/j2ee/config/instrumenter. All relative paths of referenced configuration files are relative to this directory. You may also copy these files to JVM ID-specific directories to customize them on a per JVM basis. You can use the following special variables to specify the absolute path of these per-JVM configuration files:

${indepth.j2ee.home} expands to <i3_root>/products/j2ee ${indepth.j2ee.server_id} expands to the raw JVM ID ${indepth.j2ee.jvm_id} expands to the JVM ID (with cluster serial number)
For example, if you have copied the Custom.xml file into the <i3_root>/products/j2ee/config/petstore directory, you can reference it with: <config-file> ${indepth.j2ee.home}/config/${indepth.j2ee.server_id}/Custom.xml </config-file>
Enabling an additional configuration file

The following procedure describes how you can enable an additional configuration file. To enable an additional configuration file 1 2 Open the InstrumenterConfigList.xml file in the JVM ID-specific configuration directory for your application server (<i3_root>/products/j2ee/config/JVMID/). In the InstrumenterConfigList.xml file, locate the XML block that defines the file you want to enable. For example, to enable the JNDI custom instrumentation file, locate the following section:
<!-JNDI Uncomment to instrument. --> <!-<config-file> JNDI.xml </config-file> -->
Remove the XML comments surrounding the file name. For example:
<!-JNDI Uncomment to instrument. --> <config-file> JNDI.xml </config-file>
Adding your own custom instrumentation configuration file

The following procedure describes how you can add your own custom instrumentation configuration file.
93
To add your own custom instrumentation configuration file 1 Create a new user-defined XML configuration file, for example UserDefined.xml, in the following way:
<?xml version="1.0" encoding="UTF-8"?> <!-User Defined Instrumenter Configuration File --> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name></class-name> <methods> <method> <name> </name> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>
To add the file to the InstrumenterConfigList.xml file, use the following syntax:
<!-User defined instrumenter config file --> <config-file> UserDefined.xml </config-file>
Modify the new XML configuration file to include the interfaces, classes, and methods you want to instrument. See the next section for more information.
About custom instrumenter configuration

Precise for J2EE allows you great flexibility in instrumenting Java applications. You can instrument specifically named packages, interfaces, classes, and methods. In addition, you can instrument all classes in a package or all methods in a class using the wildcard character. Sub-elements of <instrumenter-config> also allow you to target the behavior of methods so that you can instrument all calls to a method as well as all calls the method makes, or calls from a specific method to another specific method. Precise for J2EE instrumentation also takes advantage of the inheritance properties of the Java language, for example, allowing you to instrument all classes that extend a common subclass or interface. Note: Using custom instrumentation requires knowledge of Java language structures. Refer to an introductory Java language or programming primer for an explanation of Java language concepts. The Workflow Framework example is used to illustrate how instrumentation is applied to Java language constructs. The Workflow Framework example is based on the following classes and interfaces:
package xmp.wfm.task; public interface Task { public void start(); public void stop(); public void stop(boolean force); } public interface RecoverableTask extends Task { public void start(RecoverableTaskContext context); } public abstract class AbstractTask implements Task { public void start() { } protected void start(TaskContext taskContext) { }
Configuring Precise for J2EE instrumentation About using custom instrumentation public void stop() { } public void stop(boolean force) { } } package xmp.wfm.server; public class NonRecoverableTaskAdapter extends AbstractTask { } public class RecoverableTaskAdapter extends AbstractTask implements RecoverableTask { public void start() { } public void start(RecoverableTaskContext context) { } protected void recover(RecoverableTaskContext context) { } public void stop() { } public void stop(boolean force) { } }
94
About instrumenting interfaces

Instrumentation can be applied to methods in abstract and concrete classes that implement specific interfaces.
About instrumenting methods in implementations of an interface

The <custom-config> element can be used to cause instrumentation to be applied to methods of abstract and concrete classes that implement an interface. This instrumenter configuration file causes instrumentation to be applied to the start and stop methods of abstract and concrete classes that implement the Task interface.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.Task </class-name> <methods> <method> <name> start </name> </method> <method> <name> stop </name> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>
Instrumentation is applied to methods of abstract and concrete classes that satisfy the following criteria:

The matched class implements, directly or indirectly, the interface that is specified in the <class-name> element. The name of the method matches the name that is specified in one of the <name> elements. The method, including signature, was declared in the matching interface.
Based on these rules, custom-type instrumentation are applied to the following methods:

AbstractTask.start() AbstractTask.stop() AbstractTask.stop(boolean) RecoverableTaskAdapter.start() RecoverableTaskAdapter.stop() RecoverableTaskAdapter.stop(boolean)
However, instrumentation is not applied to the following methods:

95
AbstractTask.start(TaskContext) because the method was not declared in the Task interface RecoverableTaskAdapter.start(TaskContext) because the method was not declared in the Taskinterface RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method was not declared in the Task interface
About restricting instrumentation to methods that match a signature

The <params> element can be included within a <method> element to restrict instrumentation to a method that is based on a signature. See About method signature matching on page 115. This instrumenter configuration file causes instrumentation to be applied to the start and stop(boolean) methods of abstract and concrete classes that implement the Task interface.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.Task </class-name> <methods> <method> <name> start </name> </method> <method> <name> stop </name> <params> <param> boolean </param> </params> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>

The matched class implements, directly or indirectly, the interface that is specified in the <class-name> element. The name of the method matches the name that is specified in the <name> element. The method was declared in the matching interface.
Based on these rules, custom-type instrumentation is applied to the following methods:

AbstractTask.start() AbstractTask.stop(boolean) RecoverableTaskAdapter.start() RecoverableTaskAdapter.stop(boolean) AbstractTask.start(TaskContext) because the method was not declared in the Task interface AbstractTask.stop() because the method does not match the specified signature of (boolean) RecoverableTaskAdapter.start(TaskContext) because the method was not declared in the Taskinterface RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method was not declared in the Task interface RecoverableTaskAdapter.stop() because the method does not match the specified signature of (boolean)

See About method signature matching on page 115.
96
About extending instrumentation to interfaces matching a wildcard

Inheritance is not considered when wildcards are used with <class-name> element. It is not possible to use wildcards to cause instrumentation to be applied to all abstract or concrete class's that implement interface's that match a wildcard pattern. However, wildcards can be used to apply instrumentation to all abstract or concrete classes whose names match the wildcard pattern that is specified in the <class-name> element. See About using the wildcard character * on page 115.
About extending instrumentation to methods that match a wildcard

Wildcards can be used in the <name> element. This instrumenter configuration file causes instrumentation to be applied to the start() and stop() methods of abstract and concrete classes that implement the Task interface.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.Task </class-name> <methods> <method> <name> s* </name> <params> <params/> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>
When wildcards are used in the <name> element and the matching construct is an interface, instrumentation is applied to methods of abstract and concrete classes that satisfy the following criteria:

The name of the method matches the wildcard pattern that is specified in the <name> element. The signature of the method matches the signature that is specified in the <params> element (if present). Specifying empty <params> </params> elements indicates that methods with zero arguments are matched, as in a signature of (). If <params> </params> is omitted, all signatures are matched. The method is declared in the matched interface.

AbstractTask.start() AbstractTask.stop() RecoverableTaskAdapter.start() RecoverableTaskAdapter.stop() AbstractTask.start(TaskContext) because the method was not declared in the Task interface AbstractTask.stop(boolean) because the method does not match the specified signature of () RecoverableTaskAdapter.start(TaskContext) because the method was not declared in the Task interface RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method name does not match the wildcard pattern RecoverableTaskAdapter.stop(boolean) because the method does not match the specified signature of ()

97
About extending instrumentation to methods that are declared in extending interfaces

By default, instrumentation is restricted to methods that are declared in the matching interface. The <apply-to-subtypes> element can be used to extend instrumentation to apply to methods that are declared in extending interfaces. This instrumenter configuration file causes instrumentation to be applied to the start methods of abstract and concrete classes that implement the Task interface or an interface that extends the Task interface.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.Task </class-name> <methods> <method> <name> sta* </name> <apply-to-subtypes>true</apply-to-subtypes> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>

The name of the method matches the wildcard pattern that is specified in the <name> element. The signature of the method matches the signature that is specified in the <params> element (if present). The method is declared in the matched interface. The matched class has one or more interfaces are the same as or extend the interface that is specified in the <class-name> element.

AbstractTask.start() RecoverableTaskAdapter.start() RecoverableTaskAdapter.start(RecoverableTaskContext) AbstractTask.start(TaskContext) because the method was not declared in the Task interface or in an interface that extends the Task interface +AbstractTask.stop() because the method does not match the specified wildcard pattern of sta* AbstractTask.stop(boolean) because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.stop() because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.stop(boolean) because the method does not match the specified wildcard pattern of sta*
About extending wildcards to apply to methods that are declared in implementations

By default, instrumentation is restricted to methods that are declared in the matching interface. The <apply-to-implementations> element can be used to extend instrumentation to apply to methods that are declared in abstract and concrete classes that implement the matching interface. This instrumenter configuration file causes instrumentation to be applied to the start methods of abstract and concrete classes that implement the Task interface.
<?xml version='1.0'?> <instrumenter-config> <custom-config>
Configuring Precise for J2EE instrumentation About using custom instrumentation <java-classes> <java-class> <class-name> xmp.wfm.task.Task </class-name> <methods> <method> <name> sta* </name> <apply-to-implementations>true </apply-to-implementations> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>
98

The name of the method matches the wildcard pattern that is specified in the <name> element. The signature of the method matches the signature that is specified in the <params> element (if present). The method is declared in a class that extends the abstract class or implements the interface that is identified in the <class-name> element.

AbstractTask.start() AbstractTask.start(TaskContext) RecoverableTaskAdapter.start() RecoverableTaskAdapter.start(RecoverableTaskContext) AbstractTask.stop() because the method does not match the specified wildcard pattern of sta* AbstractTask.stop(boolean) because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.stop() because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.stop(boolean) because the method does not match the specified wildcard pattern of sta*

About instrumenting classes

Instrumentation can be applied to methods in abstract and concrete classes.
About instrumenting methods in abstract and concrete classes

The <custom-config> element can be used to cause instrumentation to be applied to methods of abstract and concrete classes. This instrumenter configuration file causes instrumentation to be applied to the start and stop methods of abstract and concrete classes that extend the AbstractTask class.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.AbstractTask </class-name> <methods> <method> <name> start </name> </method> <method> <name> stop </name>
Configuring Precise for J2EE instrumentation About using custom instrumentation </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>
99

The matched class extends the class specified in the <class-name> element. The name of the method matches the name that is specified in one of the <name> elements. The method was declared in the matching class.

AbstractTask.start() AbstractTask.start(TaskContext) AbstractTask.stop() AbstractTask.stop(boolean) RecoverableTaskAdapter.start() RecoverableTaskAdapter.start(TaskContext) RecoverableTaskAdapter.stop() RecoverableTaskAdapter.stop(boolean) RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method was not declared in the AbstractTask class
About restricting instrumentation to methods that match a signature

The <params> element can be included within a <method> element to restrict instrumentation to a method that is based on signature. This instrumenter configuration file causes instrumentation to be applied to the start and stop(boolean) methods of abstract and concrete classes that extend the AbstractTask class.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.AbstractTask </class-name> <methods> <method> <name> start </name> </method> <method> <name> stop </name> <params> <param> boolean </param> </params> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>

The matched class extends the interface that is specified in the <class-name> element. The name of the method matches the name that is specified in the <name> element.

100
The method signature matches the types that are specified using the <param> elements. The method was declared in the matching class.

AbstractTask.start() AbstractTask.start(TaskContext) AbstractTask.stop(boolean) RecoverableTaskAdapter.start() RecoverableTaskAdapter.start(TaskContext) RecoverableTaskAdapter.stop(boolean) AbstractTask.stop() because the method does not match the specified signature of (boolean) RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method was not declared in the AbstractTask class RecoverableTaskAdapter.stop() because the method does not match the specified signature of (boolean)

About extending instrumentation to classes matching a wildcard

Inheritance is not considered when wildcards are used with a <class-name> element. It is not possible to use wildcards to cause instrumentation to be applied to all abstract or concrete classes that extend classes that match a wildcard pattern. However, wildcards can be used to apply instrumentation to all abstract or concrete classes whose names match the wildcard pattern that is specified in the <class-name> element.
About extending instrumentation to methods that match a wildcard

Wildcards can be used in the <name> element. This instrumenter configuration file causes instrumentation to be applied to the start() and stop() methods of abstract and concrete classes that extend the AbstractTask class. See About using the wildcard character * on page 115.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.AbstractTask </class-name> <methods> <method> <name> s* </name> <params> <params/> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>
When wildcards are used in the <name> element and the matching construct is a class, instrumentation is applied to methods of abstract and concrete classes that satisfy the following criteria:

The name of the method matches the wildcard pattern that is specified in the <name> element. If the <params> element is present, the signature of the method matches the signature that is specified in the <params> element. Specifying empty <params> </params> indicates that methods with zero arguments are matched, as in a signature of ( ). If <params> </params> is omitted, all signatures are matched. The method is declared in the matched class.
101

AbstractTask.start() AbstractTask.start(TaskContext) AbstractTask.stop() RecoverableTaskAdapter.start() RecoverableTaskAdapter.start(TaskContext) RecoverableTaskAdapter.stop() AbstractTask.stop(boolean) because the method does not match the specified signature of () RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method name does not match the wildcard pattern RecoverableTaskAdapter.stop(boolean) because the method does not match the specified signature of ()

About extending instrumentation to methods that are declared in extending classes

By default, instrumentation is restricted to methods that are declared in the matching class. The <apply-to-subtypes> element can be used to extend instrumentation to apply to methods that are declared in extending classes. This instrumenter configuration file causes instrumentation to be applied to the start methods of abstract and concrete classes that extend the AbstractTask class or a class that extends the AbstractTask class.
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.AbstractTask </class-name> <methods> <method> <name> sta* </name> <apply-to-subtypes>true</apply-to-subtypes> </method> </methods> </java-class> </java-classes> </custom-config> </instrumenter-config>

The name of the method matches the wildcard pattern that is specified in the <name> element. The signature of the method matches the signature that is specified in the <params> element (if present). The method is declared in the matched class. The matched class is the same as or extends the class specified in the <class-name> element.

AbstractTask.start() AbstractTask.start(TaskContext) RecoverableTaskAdapter.start() RecoverableTaskAdapter.start(RecoverableTaskContext) AbstractTask.stop() because the method does not match the specified wildcard pattern of sta* AbstractTask.stop(boolean) because the method does not match the specified wildcard pattern of sta*

102
RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.stop() because the method does not match the specified wildcard pattern of sta* RecoverableTaskAdapter.stop(boolean) because the method does not match the specified wildcard pattern of sta*
About instrumenting all calls from a method

Instrumentation can be applied to all calls from methods that match criteria specified in a <java-classes> element. This instrumenter configuration file causes instrumentation to be applied to all calls from the methods that match the <java-classes> element. <?xml version='1.0'?> <instrumenter-config> <all-calls-from-method> <java-classes> ] ... </java-classes> </all-calls-from-method> </instrumenter-config> The rules that apply to the <java-classes> element that is documented in preceding sections are applied when it is used inside the <all-calls-from-method> element.
About instrumenting calls to methods

The <all-calls-to-method> element can be used to apply instrumentation to all calls to specific methods. This instrumenter configuration file causes instrumentation to be applied to all calls made to println methods in the java.io. package or to run () methods.
<?xml version='1.0'?> <instrumenter-config> <all-calls-to-method> <methods> <method> <name> java.io.*.println </name> </method> <method> <name> *.run </name> <params> <params/> </method> </methods> </all-calls-to-method> </instrumenter-config>
The <name> element has a different interpretation from its use in all other cases. When the <name> element is used inside an <all-calls-to-method> element, it must represent a fully-qualified method name. The portion of the <name> after the last dot (.) is considered to be the method name, and the portion of the <name> before the last dot is considered to be the class name. When you use wildcards, it is important to use a wildcard pattern that fits the scheme described. For example, the wildcard pattern *.set* matches all methods whose name starts with set of all classes, and xmp.task.*.* matches all methods in all classes whose name starts with xmp.task. The <invocation-relationship> element can be used instead of the <all-calls-to-method> element to restrict instrumentation to calls to specific methods. This instrumenter configuration file causes instrumentation to be applied to all calls made to println methods in the java.io. package or to run() methods from methods in abstract or concrete classes that implement the AbstractTask interface.
<?xml version='1.0'?> <instrumenter-config> <invocation-relationship> <java-class>
Configuring Precise for J2EE instrumentation About using custom instrumentation <class-name> xmp.task.AbstractTask </class-name> </java-class> <invoked-method> java.io.*.println </invoked-method> <invoked-method> *.run() </invoked-method> </invocation-relationship> </instrumenter-config>
103
The rules that apply to the <java-class> element that is documented in preceding sections are applied when it is used inside the <invocation-relationship> element. The <invoked-method> represents a fully-qualified method name. The portion of the <invoked-method> after the last dot (.) is considered to be the method name, and the portion of the <invoked-method> before the last dot is considered to be the class name. When you use wildcards, it is important to use a wildcard pattern that fits the scheme described. For example, the wildcard pattern *.set* matches all methods whose name starts with set of all classes, and xmp.task.*.* matches all methods in all classes whose name starts with xmp.task. The <invoked-method> may also include a method signature. The method signature should follow these rules:

The method signature must be enclosed in parentheses (() and ()). The method signature must not contain spaces. A comma (,) must separate parameter types in the method signature. The method signature may include wildcards.
About preventing instrumentation for classes, methods, and calls to methods

Instrumentation can be prevented for specific packages and sub-packages, classes, methods, or calls to methods. The <ignore-config> element in instrumenter configuration files is used to illustrate how to prevent instrumentation from being applied to specific packages and sub-packages, classes, method, or calls to methods. See About instrumenter configuration file reference on page 108. As with the <custom-config>, <all-calls-from-method>, <all-calls-to-method>, and <calls-from-method-to-method> elements, the <ignore-config> element can be placed in its own instrumenter configuration file. The examples should be considered to imply that the <ignore-config> element must be included in an instrumenter configuration file that contains other instrumentation directives.
About preventing instrumentation for all methods of classes in a package and sub-packages
The <java-classes> element can be used within an <ignore-config> element to prevent instrumentation from being applied to all methods of classes in a package and sub-packages using wildcards in the <class-name>. This instrumenter configuration file prevents instrumentation from being applied to the AbstractTask class:
<?xml version='1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.* </class-name> <methods> <method> <name> * </name> </method> </methods> </java-class> </java-classes> </custom-config> ] <ignore-config> <java-classes> <java-class> <class-name> xmp.wfm.task.* </class-name> </java-class> </java-classes> </ignore-config> </instrumenter-config>
Based on these rules, instrumentation is not applied to the following methods:

104
AbstractTask.start() AbstractTask.start(TaskContext) AbstractTask.stop() AbstractTask.stop(boolean)
However, instrumentation is still applied to the following methods:

RecoverableTaskAdapter.start() RecoverableTaskAdapter.stop() RecoverableTaskAdapter.stop(boolean)
About preventing instrumentation for methods of a class

The <java-classes> element can be used within an <ignore-config> element to prevent instrumentation from being applied to some or all methods of abstract or concrete classes, or to all methods of a class in a specific package and its sub-packages. This instrumenter configuration file prevents instrumentation from being applied to the AbstractTask class:
<?xml version'1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class> <class-name> xmp.wfm.task.AbstractTask </class-name> <methods> <method> <name> * </name> </method> </methods> </java-class> </java-classes> </custom-config> <ignore-config> <java-classes> <java-class> <class-name> xmp.wfm.task.AbstractTask </class-name> </java-class> </java-classes> </ignore-config> </instrumenter-config>
Based on this configuration, instrumentation is not applied to the following methods:

AbstractTask.start() AbstractTask.start(TaskContext) AbstractTask.stop() AbstractTask.stop(boolean)
However, instrumentation is applied to the following methods:

RecoverableTaskAdapter.start() RecoverableTaskAdapter.stop() RecoverableTaskAdapter.stop(boolean)
The <methods> element can be supplied to prevent instrumentation from being applied to some methods of a class, but not others. This instrumenter configuration file prevents instrumentation from being applied to all stop() methods:
<?xml version'1.0'?> <instrumenter-config> <custom-config> <java-classes> <java-class>
Configuring Precise for J2EE instrumentation About using custom instrumentation <class-name> xmp.wfm.task.Task </class-name> <methods> <method> <name> * </name> </method> </methods> </java-class> </java-classes> </custom-config> <ignore-config> <java-classes> <java-class> <class-name> * </class-name> <methods> <method> <name> stop </name> <params> <params/> </method> </methods> </java-class> </java-classes> </ignore-config> </instrumenter-config>
105
Based on this configuration, instrumentation is not applied to the following methods:

AbstractTask.stop() RecoverableTaskAdapter.stop()
However, instrumentation is applied to the following methods:

AbstractTask.start() AbstractTask.stop(boolean) RecoverableTaskAdapter.start() RecoverableTaskAdapter.stop(boolean)
About preventing instrumentation for calls from a method

The <all-calls-to-method> element can be used within an <ignore-config> element to prevent instrumentation from being applied to all calls to specific methods. This instrumenter configuration file prevents instrumentation from being applied to all calls to Java runtime classes (java.*) methods.
<?xml version'1.0'?> <instrumenter-config> <ignore-config> <all-calls-to-method> <methods> <method> <name> java.*.* </name> </method> </methods> </all-calls-to-method> </ignore-config> </instrumenter-config>
The <all-calls-to-method> element is used within an <ignore-config> element, the <name> element of <method> elements is expected to be a qualified method name. The last dot in the <name> separates the class name from the method name. This is also true if wildcards are used. This instrumenter configuration file prevents instrumentation from being applied to all calls to methods in the java class. <?xml version'1.0'?> <instrumenter-config> <ignore-config> <all-calls-to-method>
106
<methods> <method> <name> java.* </name> </method> </methods> </all-calls-to-method> </ignore-config> </instrumenter-config>
About preventing instrumentation for calls to a method

The <invocation-relationship> element can be used within an <ignore-config> element to prevent instrumentation from being applied to calls to specific methods from specific calling methods. This instrumenter configuration file prevents instrumentation from being applied to all calls to Java runtime classes (java.*) methods that take an int[] parameter from the stop() methods in the xmp.wfm package and sub-packages.
<?xml version='1.0'?> <instrumenter-config> <ignore-config> <invocation-relationship> <java-class> <class-name> xmp.wfm.* </class-name> <methods> <method> <name> stop </name> <params> <params/> </method> </methods> </java-class> <invoked-method> java.*.*(int[]) </invoked-method> </invocation-relationship> </ignore-config> </instrumenter-config>
About instrumenting calls to EJB business method implementations

The J2EE specification does not require that an EJB implementation implement the remote interface directly. Application servers typically generate a skeleton that implements the remote interface directly and delegates calls to the EJB implementation. Because there is no direct relationship between an EJB implementation and the remote interface, it is difficult to instrument the business methods of an EJB implementation without first identifying the remote interfaces and then manually instrumenting the methods.
About the Calls to EJB instrumentation feature

The Calls to EJB implementations instrumentation feature adds a configurable extension to the instrumenter to allow calls to EJB implementations to be instrumented. When the feature is enabled, the Calls to EJB implementations instrumentation feature searches for classes that match certain marker classes or interfaces or name patterns. If a class matches, caller-side instrumentation is applied to any calls from a method that makes a call to another method of the same name and signature. The marker classes and interfaces are expected to identify the EJB skeletons. As an example, consider these application classes:
public interface Account extends EJBObject { public void deposit(float amount); } public class AccountEJB implements SessionBean { public void deposit(float amount) updateAccount(getCurrentBalance() + amount); } }
107
Under WebLogic 7.0, EJB skeletons extend the weblogic.rmi.internal.Skeleton class. The Calls to EJB implementations instrumentation feature can be configured to find the skeleton and instrument the call to deposit. As an example, the WebLogic skeleton might look as follows:
public class AccountEJB_bfqop_WKSkel extends Skeleton implements Account { public void init() { /* ... */ } public void invoke() { /* ... */ } public void deposit(float amount) { impl.deposit(amount); } }
In this case, the call from AccountEJB_bfqop_WKSkel.deposit to AccountEJB.deposit is instrumented because the call is to a method with the same name and signature as the caller. Note: init() and invoke() are probably not instrumented unless they call another method with the same name and signature. Instrumentation that is applied by the Calls to EJB implementations instrumentation feature show up in the instrumenter log as FIXED-CALLER-SIDE instrumentation. The EJBImpl.xml file looks like the following example:
<instrumenter-config> <planner-config> <class-name>com.precise.javaperf.instrument.planner. CallsToEJBImplementationPlanner </class-name> <property> <name> skeletonMarkerClass </name> <value> weblogic.ejb20.internal.BaseEJBObject </value> </property> <property> <name> logBeginMethodName </name> <value> logBeginEjbServer </value> </property> <property> <name> logEndMethodName </name> <value> logEndEjbServer </value> </property> <property> <name> invocationType </name> <value> EJBImpl </value> </property> </planner-config> </instrumenter-class>
The <class-name> element identifies the name of the new pluggable instrumentation planner. The following table lists the recognized properties. Table A-1 Recognized properties Multiplicity
Optional
Property Name
logBeginMethodName
Description
Identifies the logger method to call to report calls to EJB business methods. Identifies the logger method to call to report calls to EJB business methods. Identifies how the logger events show up in Precise for J2EE.
logEndMethodName
Optional
invocationType
Optional
108
Table A-1
Recognized properties Multiplicity

Any Number
Property Name
skeletonMarkerClass
Description
Identifies the classes that an EJB skeleton must extend. Only classes that extend a skeleton class or implement a skeleton interface are searched for calls to methods with matching name and signature. Identifies the classes that an EJB skeleton must implement. Only classes that extend a skeleton class or implement a skeleton interface are searched for calls to methods with matching name and signature. Identifies the classes that must be extended by calls with a matching name and signature. Identifies the classes that must be implemented by calls with a matching name and signature.
skeletonMarkerInterface
Any Number
implementationMarkerClass
Any Number
implementationMarkerInterface
Any Number
Applying instrumentation using the "Calls to EJB" instrumentation feature

The following procedure describes how to apply instrumentation using the "Calls to EJB" instrumentation feature. To apply instrumentation using the Calls to EJB instrumentation feature 1 Add the EJBImpl.xml file to the InstrumenterConfigList.xml file:
<instrumenter-config-list> <config-file> EJBImpl.xml </config-file> </instrumenter-config-list>
Restart the application server.
About instrumenter configuration file reference

The purpose and schema of the various files that configure instrumentation for a monitored JVM is described in About the master configuration file, About the instrumenter configuration files, About the structure of instrumenter configuration files, and About common instrumenter configuration matching techniques.
109
Figure A-1
Instrumenter Configuration
About the master configuration file

Instrumentation for each monitored JVM is configured from a master configuration file. The master configuration file, InstrumenterConfigList.xml, contains references to instrumenter configuration files that contain specific rules that are used to determine where and how to apply instrumentation to a monitored JVM. The master configuration file can be found under the JVM-specific config directory for a monitored JVM. The master configuration file has the following structure:
<?xml version='1.0'?> <instrumenter-config-list> ] <config-file>  instrumenter-config-file-path </config-file> </instrumenter-config-list>
The instrumenter config file path specifies the absolute or relative path to an instrumenter configuration file. Paths are relative to <i3_root>/products/j2ee/config/instrumenter. The following special variables can be used in the instrumenter config file path:

110
${indepth.j2ee.home} expands to <i3_root>/products/j2ee ${indepth.j2ee.server_id} expands to the JVM ID (with no cluster sequence number) ${indepth.j2ee.jvm_id} expands to the JVM ID (with a cluster sequence number)
About the instrumenter configuration files

Instrumenter configuration files contain specific rules that are used to determine where and how to apply instrumentation. There are several default instrumenter configuration files in the <i3_root>/products/j2ee/config/instrumenter directory. The instrumentation configuration files listed in the following tables are enabled by default in the InstrumenterConfigList.xml file. Comments that are placed above the references to these files in the InstrumenterConfigList.xml file indicate the files that are required for Precise for J2EE, as shown in the following table, and those that are recommended to gather the most information. Table A-2 File name
Logger.xml Planners.xml Heatseeker.xml
Required instrumentation configuration files Description

Product configuration Controls the order in which instrumentation is applied Adaptive instrumentation analysis results that are loaded at startup. This file is regenerated when adaptive instrumentation policies are run. Instrumentation Explorer applied changes that are loaded at startup. This file is regenerated when you click the Instrumentation Explorer Apply Changes button. Adaptive survey instrumentation configuration Adaptive conditional instrumentation configuration Adaptive synchronization instrumentation Default Java Servlet instrumentation configuration Default Generic Portal-specific instrumentation configuration. Detects the portal and portlet configurations that implement javax.portlet.GenericPortlet. Default Generic Portlet-specific instrumentation configuration. Instruments the portlet lifecycle and action methods. Default JSP instrumentation configuration Default (BEA WebLogic-specific) JSP instrumentation configuration Default (IBM WebSphere-specific) JSP instrumentation configuration Default BEA WebLogic Portal-specific instrumentation configuration. Detects the portal and portlet configuration. This file is populated when an application server portal version is selected in Precise Framework Installer. Default BEA WebLogic Portlet-specific instrumentation configuration. Instruments the detected portlets. This file is populated when an application server portal version is selected in Precise Framework Installer. Default EJB instrumentation configuration. Handles instrumentation of EJB stubs. Default ignored instrumentation configuration Default caller-side JDBC instrumentation configuration Over-instrumentation protection instrumentation configuration Default instrumentation configuration that Precise for Web uses. This file is populated when Precise for Web is installed.
Ixp.xml
Survey.xml SurveyConditional.xml SurveySynchronization.xml Servlet.xml GenericPortal.xml
GenericPortlet.xml
JSP.xml WebLogicJSP.xml WebSphereJSP.xml WebLogicPortal.xml
WebLogicPortlet.xml
EJB.xml Ignore.xml CallsToJDBC.xml OverInstrumentationProtection.xml IndepthWeb.xml
111
Table A-2 File name
Required instrumentation configuration files Description

Insight SmartLink for PeopleSoft instrumentation configuration Insight SmartLink for Web applications instrumentation configuration Contains an example instrumentation only. You should use this file as an example and edit this file. Contains an example instrumentation only. You must edit this file. Configuration for Leak Seeker instrumentation
TACPeopleSoft.xml TACWebApps.xml Custom.xml
CallsFromMethodToMethod.xml LeakSeeker.xml
The following table lists the instrumentation configuration files that are recommended to gather the most information. Table A-3 File name
WebLogicEJB.xml
Recommended instrumentation configuration files Description

Handles BEA WebLogic-specific EJB lifecycle operation instrumentation Handles IBM WebSphere-specific EJB lifecycle operation instrumentation Handles Oracle-specific EJB lifecycle operation instrumentation Default JNDI instrumentation configuration Default JDBC DataSource instrumentation configuration Default EJB implementation instrumentation Default Java Transaction instrumentation Default Message-Driven EJB instrumentation Default Java Messaging Service instrumentation Default XML and XSL instrumentation
WebSphereEJB.xml
OracleEJB.xml JNDI.xml DataSource.xml EJBBean.xml JTA.xml MessageDrivenEJB.xml JMS.xml XML.xml
Precise for J2EE also provides several instrumentation configuration templates, as shown in the following table. You edit and enable the templates and then add them to the InstrumenterConfigList.xml file. Table A-4 File name
Calls.xml EJBImpl.xml Jolt.xml MBeanImpl.xml PeopleSoft.xml SAP61.xml SmartuneInstrumentation.xml
Instrumentation configuration templates Description

Template for configuring all calls to and all calls from methods Sample EJB implementation instrumentation Sample Jolt instrumentation Sample MBean implementation instrumentation Old PeopleSoft instrumentation SAP 6.1 instrumentation Optional SmarTune instrumentation for servlet include and session analysis
About the structure of instrumenter configuration files

The instrumenter configuration files have the following general structure:
<?xml version='1.0'?>
Configuring Precise for J2EE instrumentation About using custom instrumentation <instrumenter-config> <custom-config> </custom-config> <all-calls-to-method> </all-calls-to-method> <all-calls-from-method> </all-calls-from-method> <calls-from-method-to-method> </calls-from-method-to-method> <ignore-config> </ignore-config> </instrumenter-config>
112
See About custom instrumentation configuration on page 112. See About all calls to method instrumentation configuration on page 112. See About all calls from method instrumentation configuration on page 112. See About calls from method to method instrumentation configuration on page 113. See About ignore instrumentation configuration on page 113.
About custom instrumentation configuration

The <custom-config> element has the following structure:
<custom-config> <java-classes> <java-class>  <class-name> class-or-interface-name </class-name> <methods> <method>  <name> method-name </name> <params>  <param>  parameter-type </param> </params> <capture-param-index>  capture-parameter </capture-param-index> </method> </methods> </java-class> </java-classes> </custom-config>
About all calls to method instrumentation configuration

The <all-calls-to-method> element has the following structure:
<all-calls-to-method> <methods> <method>  <name> method-name </name> <params>  <param>  parameter-type </param> </params> </method> </methods> </all-calls-to-method>
About all calls from method instrumentation configuration

The <all-calls-from-method> element has this structure:
<all-calls-from-method> <java-classes> <java-class>  <class-name> class-or-interface-name </class-name> <methods> <method>  <name> method-name </name> <params>  <param>  parameter-type </param> </params> </method>
Configuring Precise for J2EE instrumentation About using custom instrumentation </methods> </java-class> </java-classes> </all-calls-from-method>
113
About calls from method to method instrumentation configuration

The <calls-from-method-to-method> element has this structure:
<calls-from-method-to-method> <invocation-relationship>  <java-class> <class-name> class-or-interface-name </class-name> <methods> <method>  <name> method-name </name> <params>  <param>  parameter-type </param> </params> </method> </methods> </java-class> <invoked-method>  invoked-method-name </invoked-method> </invocation-relationship> </calls-from-method-to-method>
About ignore instrumentation configuration

Use the <ignore-config> element to configure rules that are used to determine when to prevent instrumentation from being applied to all methods in specifically matched classes or packages, to specifically matched methods, or to specifically matched calls to methods. The <ignore-config> element has this structure:
<ignore-config> <java-classes>   </java-classes> <invocation-relationship>   </invocation-relationship> <all-calls-to-method>   </all-calls-to-method> </instrumenter-config>
Use the <java-classes> element to prevent instrumentation from being applied to all methods in specifically matched classes or packages or to specifically matched methods. The <java-classes> element has this structure:
<java-classes> <java-class>  <class-name> class-or-interface-name </class-name> <methods>  <method>  <name> method-name </name> <params>  </params> </method> </methods> </java-class> </java-classes>
See About method signature matching on page 115. For each method to be instrumented, the following rules are used to determine if instrumentation should not be applied to the method:
114
If the method is declared in a class whose name matches the specified class or interface name of a <java-class> element, no instrumentation should be applied to the method. If the matched <java-class> includes a <methods> element, the method must also match the specified method name of a <method> element so that no instrumentation is applied to the method. If the matched <method> element includes a <params> element, the method must also match the specified signature so that no instrumentation is applied to the method.
Wildcards are permitted in the class or interface name and method name. See About using the wildcard character * on page 115. Use the <invocation-relationship> element to prevent instrumentation from being applied to specifically matched calls to methods from a specifically matched calling method. The <invocation-relationship> element has the following structure:
<invocation-relationship>  <java-class> <class-name> class-or-interface-name </class-name> <methods> <method>  <name> method-name </name> <params>  </params> </method> </methods> </java-class> <invoked-method>  qualified-method-name </invoked-method> </invocation-relationship>
See About method signature matching on page 115. For each call to a method to be instrumented, the following rules are used to determine if instrumentation should not be applied to the method:
If the called method is declared in a class whose name matches the specified class or interface name of a <java-class> element, no instrumentation should be applied to the method. If the matched, <java-class> includes a <methods> element, the method must also match the specified method name of a <method> element so that no instrumentation is applied to the method. If the matched <method> element includes a <params> element, the method must also match the specified signature so that no instrumentation is applied to the method.
Use the <all-calls-to-method> element to prevent instrumentation from being applied to specifically matched calls to methods from any calling method. The <all-calls-to-method> element has the following structure:
<all-calls-to-method> <methods> <method>  <name> method-name </name> <params>  </params> </method> </methods> </invocation-relationship>
See About method signature matching on page 115. The <name> element must represent a fully qualified method name. The portion of the <name> element after the last dot (.) is considered to be the method name, and the portion of the <name> element before the last dot is considered to be the class name. When you use wildcards, it is important to use a wildcard pattern that fits the scheme described. For example, the wildcards pattern *.* matches all methods of all classes.
About common instrumenter configuration matching techniques

Common instrumenter configuration matching techniques are method signature matching and using the wildcard character *.
115
About method signature matching

The <params> element configures rules that are used to match method signatures for processing by the instrumenter. The <params> element has the following structure:
<params>  <param>  parameter-type </param> </params>
The parameter type is the same as the abstract type declarator for the parameter type in Java. For example, the parameter-type for a parameter of type java.lang.String is java.lang.String, and the parameter type for a parameter of type int[][] is int[][]. The following primitive parameter types names are recognized:

boolean byte char double float int long short void
The <invoked-method> elements in the <calls-from-method-to-method> element are used to match specific method signatures for specific calls from one method to another. All methods that match the signature are instrumented. Wildcard expressions are not supported and return types are not matched. The <invoked-method> format must be expressed using the same primitive types that were discussed for the <param> element. For example:
<invoked-method> java.lang.Thread.sleep(long) </invoked-method> or <invoked-method> com.acme.shared.comm.Connector.<init> (java.lang.String,int[][]) </invoked-method>
About using the wildcard character *

In addition to using specific names to reference items such as classes, interfaces, and methods, for instrumentation, you can also use the wildcard character * to instruct Precise for J2EE to instrument all classes, methods, or packages within the scope of the instruction. The following table illustrates how the wildcard character can be used. Table A-5 Wildcard
*
Usage of wildcard character * Instrumented elements

xmp.server.Main xmp.task.AbstractTask xmp.task.AbstractTask$1 xmp.task.util.TaskUtilities xmp.task.AbstractTask xmp.task.AbstractTask$1 xmp.server.Main xmp.task.util.TaskUtilities xmp.task.AbstractTask$1 xmp.server.Main xmp.task.AbstractTask xmp.task.util.TaskUtilities
Non-instrumented elements
xmp.task.* *$*
Note: Use wildcard characters only when discovering the methods to instrument. Otherwise, it may result in instrumentation that does not yield meaningful performance metrics but introduces unwanted overhead. Do not implement wildcarded instrumentation in production environments.
Configuring Precise for J2EE instrumentation About using the instrumentation configuration utility
116
Including application server classes in Leak Seeker instrumentation

To obtain information on collections and arrays with the most elements, Leak Seeker instruments all user application classes but, by default, excludes application server classes. In special circumstances, you may want Leak Seeker to collect information on application server classes as well. Warning: Instrumenting application server classes may increase excessively the startup time as well as the running time of the application. To include Leak Seeker instrumentation for application server classes 1 In the JVMID/LeakSeeker.xml file, find the application server class prefix for the application server classes that you want to instrument. For example, to identify WebLogic application server classes to instrument, you would search for lines beginning with com.bea and weblogic. Comment out the lines for the application server whose classes you want to instrument. For example, the following lines cause Leak Seeker to collect information for WebLogic application server classes.
<!--leakseeker-if-package>com.bea</leakseeker-if-package> ... <!--leakseeker-if-package>weblogic</leakseeker-if-package>
About using the instrumentation configuration utility

Precise for J2EE ships with the Instrumentation Configuration Utility (ICU), a tool that is used to analyze the data files collected by adaptive instrumentation. The ICU also lets you enable or disable instrumentation on individual methods. How to use the ICU to obtain and analyze these data files and selectively enable or disable instrumentation on individual methods has been described. For information on adaptive instrumentation, see the relevant section in the Precise for J2EE Users Guide.
About system requirements

The ICU is a Java/Swing application that is delivered with Precise for J2EE FocalPoint. The ICU runs on any of the supported Precise for J2EE platforms, provided the computer is not running in headless mode. When you run the ICU from a remote UNIX environment, you must have an acceptable DISPLAY setting. Note: The data files that the ICU analyzes can be quite large after they are loaded into the ICU, so running them on a computer with at least 512MB RAM is recommended.
About how the ICU works

The ICU provides a user interface for analyzing the survey data files collected by adaptive instrumentation. The ICU user interface also lets you enable instrumentation for methods that are selected from these data files. To enable instrumentation, the JVM Runtime Agent on the Application Server that Precise for J2EE monitors is bound to a port on the application server to listen for instructions from the ICU. When you select a specific method in the ICU to instrument, the ICU contacts the Application Server Runtime Agent to request that the specific method be instrumented or to request performance data for an instrumented method. The instrumentation that the ICU injects allows two types of performance data to be reported from the instrumented methods. The first, known as Callee-side logging, is inside a particular method and measures the method from beginning to end. Callee-side logging is used whenever the method is invoked. The second type that is known as Caller-side logging, is used to measure one specific call to a method from inside another method. Performance information that is gathered from the instrumentation that the ICU injected appears in the charts and graphs of Precise for J2EE.
117
About prerequisites to using the ICU

Before you can use the ICU to inspect the survey data files and to select specific methods and enable instrumentation for them, you need to perform the following steps:

Run adaptive instrumentation to obtain a survey data file. If you plan to use the ICU to instrument selected methods, enable conditional instrumentation on the Adaptive Administration page so that the ICU can instrument methods on your JVM during runtime. For details, see the Precise for J2EE Users Guide. If you plan to use the ICU to instrument selected methods, enable the ICU to communicate with the Application Server JVM by enabling IXP Direct Connect mode and configuring the desired port for connections. The ICU always connects via Direct Connect mode. For information on configuring Direct Connect mode, see the Precise for J2EE User's Guide.
About obtaining data files for the ICU

When adaptive instrumentation data is collected, two .ser files are placed in the directory on the server with the Collector agent where your JVM is running. For example:
survey_01_19_2004_07_21_02_begin.ser survey_01_19_2004_10_21_02_end.ser
You need to make these files available to the ICU. To obtain data files for the ICU 1 Copy the .ser files that are located in the following directory to a directory that is accessible from the host where the ICU runs: <i3_root>/products/j2ee/config/JVMID
About running the ICU

Starting the ICU requires that you run a script. after the ICU has been loaded, the initial console screen appears, as shown in the following figure. Figure A-2 Initial ICU screen
118
To run the ICU 1 Start the ICU by running the following script:
Windows UNIX $<i3_root>/products/j2ee/bin/runHeatSeekerConsole.bat $<i3_root>/products/j2ee/bin/runHeatSeekerConsole.sh
Loading data files for analysis

To analyze data for analysis, you must load the slice files that contain the data. The order in which the slices are loaded does not matter, but you do not see any data until an end slice is loaded. To load data files for analysis 1 2 3 4 On the Slice menu, select Load Begin Slice. In the Load Begin HeatSeeker Sample dialog box, select the slice file that you want to load (the *_begin.ser file) and click Load. On the Slice menu, select Load End Slice. In the Load End HeatSeeker Sample dialog box, select the slice file that you want to load (the _end.ser file) and click Load. The method tree is populated with all methods that were invoked during the slice collection period.
About identifying methods of interest

The method hierarchy shows all the methods that were invoked during the data collection interval. With each method, three metrics are displayed:
Work Time (WT) Response Time (RT) represents the total work time, in milliseconds, for the method during the collection interval represents the average response time, in milliseconds, for the method across all invocations during the collection interval represents the total count of method invocations during the data collection interval.
Invocations (INV)
The ICU lets you sort the method list by the following metrics using the Sort By list above the method list:
When the method list is sorted by Work Time/Called By, as shown in the following figure, the methods are arranged in the tree according to their work time. Additionally, the child nodes in the tree represent the callers of a particular method, essentially allowing you to drill up in the method invocation hierarchy. Folder icons mean that a method has callers, while paper icons mean that the method has no callers. Method hierarchy, sorted by work time
Figure A-3
When the method list is sorted by Response Time/Calls To, as shown in the following figure, the methods are arranged in the tree according to their response time values. The child nodes in the tree represent the callees of that method, allowing you to drill down in the invocation hierarchy. Folder icons mean that a method has callees, while paper icons mean that the method has no callees.
119
Figure A-4
Method hierarchy, sorted by response time
When the method list sorted by Class & Method Name, as shown in the following figure, methods are sorted alphanumerically on the fully qualified class and method name. Drilling down in this view also displays the method callees. Method hierarchy, sorted by class & method name
Figure A-5
Enabling or disabling instrumentation for a method

You can enable or disable instrumentation per method.
120
To enable or disable instrumentation for a method 1 2 3 In the ICU, in the Host Name and Port text boxes, type the name of the Application Server Runtime Agents host and port. In the method hierarchy, select the method to instrument. On the Task menu, view the available tasks. The ICU determines which tasks in this menu are enabled or disabled based on the context of the selected method:
No tasks available means that the ICU determined that neither callee- nor caller-side logging can be enabled for the selected method. The Enable/Disable Logging for Calls from Selected Method to Callee tasks are available when the selected method can have caller-side logging enabled. The Enable/Disable Logging for Selected Method tasks is available when the selected method can have callee-side logging enabled. Both Enable/Disable Logging for Selected Method and Enable/Disable Logging for Calls from Selected Method to Callee are available when the selected method can have caller- and callee-side logging enabled.
Glossary
<i3_root> abandonment rate action This is the term used in a path for the Precise installation directory. The terms <i3_root> (or i3 root) and Precise root can appear in text too. In Precise for Web, a counter that keeps track of the percentage of users that abandon the loading of the Web page before it completes downloading. An operation that Alerts FocalPoint automatically performs when detecting a warning or critical status for a specific metric. According to the defined action, Alerts FocalPoint opens a message box, sends an email or SNMP trap, or executes a program. The data that is managed directly by Precise for J2EE. As new data is collected, Precise for J2EE saves it in the SQL archive with an active label. When the age of active archive data exceeds the Aging Timespan configuration setting, the data is re-labeled as overflow or deleted, depending on the selection status of the Overflow Enabled item. The central administration console of Precise that facilitates the maintenance, configuration, and management of all installed Precise components, such as monitoring the status of all Precise agents and Performance Warehouse processes, getting license information, starting and stopping the agents, getting log data on agents and events, changing Performance Warehouse settings, and installing patches. See also Performance Warehouse. See also agent. advice In Precise for Oracle, an algorithm that is designed to recommend on gathering statistics, creating new indexes, change existing indexes, and add or delete hints to make Oracle's Optimizer choose a better access path and make the statement perform better. Can be activated from any DML (Data Manipulation Language) statement. A program that runs on a server machine to collect, process, or communicate performance information. The Precise installation consists of multiple agents. Also called a measurement interval. In Precise for J2EE, the smallest unit of data presentation and storage. Represents the period of time over which Precise data is collected and aggregated (summarized). The state of an Alerts metric that has reached a near-critical or critical status. An alert is issued by Alerts, triggering an action and informing of a problem that has occurred or is likely to occur within the area sampled by the specific metric. See also action. Alerts These product provide alerts to problematic conditions before they turn into performance problems, based on predefined metrics and thresholds. Alerts can automatically perform an action, such as displaying a pop-up message, sending an e-mail message or SNMP trap, or running a program. An agent that receives data from the InformPoint agents, stores it, and performs any action that has been user-defined for that specific alert, such as displaying a pop-up message, sending an e-mail message or SNMP trap, or running a program. See also InformPoint. alert type In Alerts, the status of all metrics belonging to a metric group or a monitored instance, indicating the current performance level through colors. See also alert. See also metric. analysis tabs application server metric AppTier In Precise for J2EE, in the Activity workspace, these tabs show Highlights, Invocations, Hotspots, SQL, Locks, Business, and Exceptions. In Precise for J2EE, a metrics that is provided by the application server or by customer code. This can include metrics published by the Java Management Extension (JMX) APIs or vendor-specific APIs, such as IBM's Performance Management Interface (PMI). The abbreviation for an application tier in a Precise environment. An AppTier contains one or more instances of the same technology and purpose. Application tiers do not necessarily correspond to distinct physical server machines: in many cases, the tiers are logical, with one server machine running multiple
active archive data
AdminPoint
agent aggregation interval alert
Alerts FocalPoint
Glossary
122
AppTiers or one AppTier spans a cluster of servers. A Precise environment may contain multiple AppTiers on the same technology. For example, you may group J2EE instances (JVMs) into a J2EE Presentation AppTier and a J2EE Business Logic AppTier. Segmenting application service time into the contribution of individual application tiers is helpful in identifying the source of performance problems. Analyzing the performance and behavior of each tier separately is crucial for isolating the root causes of performance problems. archive data The data stored in a Precise for J2EE database, including data that is actively managed by Precise for J2EE (active archive data) and data that is managed by the user (inactive archive data). See also active archive data. See also inactive archive data. browser side collection cabinet call path CAT (concurrent active thread) In Precise for Web, the gathering of performance data from the desktop of the Web application's user through the Web browser agent. In Precise for Oracle, Precise for SQL Server, Precise for DB2, and Precise for Sybase, the highest logical level in the SQL workspace hierarchy. A cabinet contains folders and, within folders, statements. A subset of a stack trace including only those methods that have been instrumented. The average number of concurrently active top-level threads detected by instrumentation. The active threads can include HTTP, EJB, JDBC, or custom invocations. The measurement of CATs indicates how busy the system was during a period of time. The number of simultaneously active threads is rarely a stable integer number. In addition, the application server and multi-threading features impact the concurrence of the application server so that the CAT's value may be larger or smaller than the number of users reported by the load generator. In Precise for Web, a counter that keeps track of the percentage of requests taken from the client cache (http status 304). Within J2EE, a grouping of multiple JVMs, either within a single server or across multiple servers, in such a way that the operation of the group appears to be that of a single JVM with improved performance and reliability. In general, two (or more) servers that work together to balance load or to provide continued operation if one server fails. In Precise for SQL Server and Precise for Sybase, the access plan of a unique group of statements or batches that belong to the same collapsed statement or batch but have different access plans. Can differ due to the constants in the text of the original (not collapsed) statements. See also explained statement. See also collapsed statement. collapsed statement In Precise for Oracle, Precise for SQL Server, Precise for Sybase, and Precise for DB2, a statement whose constants are replaced with parameters. Each collapsed statement can have several access plans, according to the occurrences of its statements. See also collapsed access plan. Collector agent The program that runs on the monitored server to collect performance information. Some technologies allow a single Collector agent to serve multiple instances running on the same server. Other technologies require a dedicated Collector agent per monitored instance. In most cases, it must be installed on the monitored server. Collector agents for SAP, SQL Server, and Sybase may reside on a remote server. See also agent. completion rate Concurrent Active Thread contributor count CPU time critical status In Precise for Web, a counter that keeps track of the percentage of users that completed the loading of a Web page. See CAT (concurrent active thread). An invoked element that contributes to a method's performance. For example, an internally invoked servlet or JSP, EJB call, or JDBC call are contributors to service request response time and CPU time. The number of occurrences observed during a measurement interval. The average amount of time consumed by the operating system actively processing instructions on behalf of a running method. In Alerts, the status represented by a red bullet indicating that the value of the sampled metric has exceeded the near-critical and critical threshold values.
client cache cluster
collapsed access plan
Glossary
123
See also metric. Cross-AppTiers A perspective that provides high-level information about the performance of an environment, including operating system data. Information is always related to all AppTiers in an environment and can help understand how AppTiers interact. See also AppTier. current data customized metric data sample drilldown EJB (Enterprise Java Bean) EJB request EJB service time % EJB skeleton EJB Stub The data collected during the last aggregation interval of the J2EE AppTier Collector agent, displayed in bar graphs. In Alerts, a user-defined metric that measures site-specific parameters. See aggregation interval. Within Precise products and Insight SmartLink, the filtering of analyzed data by clicking a specific entity in the Association area table. A software component architecture for the development and deployment of object-oriented, distributed, enterprise-level applications. EJBs typically contain business logic. An EJB invoked either externally or directly from an externally invoked HTTP request. The percentage of service request response time attributed to executing local or remote EJBs. A server-side entity containing a method that dispatches calls to the actual remote object implementation. A proxy for a remote object that is responsible for forwarding method invocations on remote objects to the server where the actual remote object implementation resides. A client's reference to a remote object, therefore, is actually a reference to a local stub. See EJB (Enterprise Java Bean). The highest Precise logical group. It may contain multiple AppTiers of various technologies that serve an application together. For example, a Payroll Production environment may contain all Web servers, application servers, transaction managers, databases and server machines that serve this application. Alternatively, it may contain any set of instances that form together an administrative group. Since Precise version 8.5, an instance can belong to more than one environment. Let's say a single Oracle database serves two different applications plus the DBA wants to associate this database with a group of other databases under his responsibility regardless of served applications. in this case the Oracle database will be associated to three different Precise environments. See also AppTier. See also instance. ERP extension In Precise for Oracle, Precise for DB2, and Precise for SQL Server, a product extension that provides detailed information on the activities and resource consumption of packaged application components. It correlates the database information, and the packaged application information and lets you see users, transactions, reports and other elements of ERP applications such as Oracle Applications, SAP, PeopleSoft, and Siebel. In Alerts, the occurrence of a sampling or progress. A sampling occurrence occurs every time a metric samples. A progress occurrence occurs when a metric's progress status is changed or when the investigated status reaches the end of the given investigation time. In AdminPoint, all occurrences reported by Precise agents, including informational events, warnings, and errors related to one of the agents. All events are shown in the Events view. See also metric. See also progress. execute time executions explained statement The percentage of time spent executing the application. In Precise for Oracle, Precise for SQL Server and Precise for Sybase, the number of times a SQL statement was executed during the selected time frame. In Precise for Oracle, Precise for SQL Server, Precise for DB2, and Precise for Sybase, a statement whose access path (chosen by the RDBMS Optimizer) is clarified and translated into a visual display. Explained results include information on the objects referenced by the statement and the operations performed on these objects. In Precise for Oracle, a function that proactively specifies a future period during which Oracle activity data is collected and organized for subsequent analysis. Extended collections are an easy means to view collected
Enterprise Java Bean environment
event
extended collection
Glossary
124
information, assess application resource consumption, and identify bottlenecks that are inhibiting application performance and end-user productivity. external invocation Federated Precise The activation of a) an HTTP request (Servlet or JSP) from outside of the JVM or from a thread with a different thread identifier, or b) an EJB from an HTTP request, a thread with a different thread identifier as the caller, or from outside of the JVM. Federated Precise is a version of Precise (starting with version 8.5) that can manage multiple Precise installations within unified StartPoint and AdminPoint screens, displaying and managing all environments, instances, and installations. In Precise for Web, a counter that keeps track of the time that it takes from the moment a new Web page is called until the first byte arrives back from the Web server. In Precise for SQL Server, Precise for Oracle, Precise for DB2, and Precise for Sybase, the intermediate logical level in the SQL workspace hierarchy. Folders are grouped into cabinets and contain SQL statements. See also cabinet. Framework Installer The application that facilitates the installation of Precise framework components. It can be invoked from the installation DVD in order to install a new Precise deployment. It can also be invoked from an existing Precise deployment in order to install an additional framework node and attach it to the originating Precise deployment. See also Framework node. Framework node A set of FocalPoint agents that are installed together and manages a set of monitored instances. The performance data of these instances will be loaded into a dedicated Performance Warehouse. A single Precise deployment may contain multiple framework nodes (using a separate Performance Warehouse for each node). An environment cannot span over multiple framework nodes. An automatic process in the Java runtime environment that periodically reclaims memory used by objects that are no longer referenced. The process can impact an application's performance while memory is being reclaimed. Java programmers may initiate garbage collection explicitly. In Precise for Web, the identifier that is used to group other identifiers, such as sites or URLs. In Precise for Oracle, an instruction directed at the Oracle Optimizer that includes considerations for an execution plan. The Oracle Optimizer will build an execution plan based on the hint, ignoring its own set of considerations. A unit that reflects the type and level of activity within the system at different times. By defining the times of the day that are peak and off-peak, or day and night, the performance analysis can be focused on those particular times of the day. If, for example, most performance problems occur within nighttime and weekend batches, it can be useful to focus only on them. A Java Servlet or JSP that is invoked externally. See also external invocation. HTTP service time % The percentage of a service request's service time that is attributed to executing an internally invoked Java Servlet or JSP. See also internal invocation. inactive archive data InformPoint The archive data that does not reside under the active archive label, such as overflow data, and that is not managed by Precise for J2EE. Precise for J2EE will retrieve data from these files if they are classified with the inactive archive label. If this label is set to active, the management rules for active archive apply. In Alerts, an agent that retrieves performance data from all installed Precise products, analyzes it, and sends an alert to Alerts FocalPoint when the predefined thresholds are exceeded. See also agent. Insight The Precise product family that facilitates the process of monitoring and correlating system performance. It consists of Insight. See also Report Manager. See also An agent that communicates with the Listener agents installed on the monitored servers, receives data from the Collector agents, periodically processes and stores this data in Performance Warehouse, and serves UI requests..
first byte time folder
garbage collection
grouper hint
hour group
HTTP request
Glossary
125
Insight FocalPoint
An agent that receives performance information from Insight Savvies, which monitor the environment. Insight FocalPoint then correlates, processes, and stores this information in a centralized location. The Insight performance history is stored in the Performance Warehouse database. See also Savvy. See also Performance Warehouse.
instance
A monitored object of specific technology. The following list specifies what constitutes an instance for the various supported technologies: J2EE- a Java Virtual Machine (JVM- a logical name set by the user), Microsoft .NET- a Common Language Runtime (CLR - a logical name set by the user), Oracle Applicationsan Oracle Applications form server, Oracle- an Oracle instance, SAP- a SAP system, SQL Server- an SQL Sybase- a Sybase instance, Tuxedo- a Tuxedo domain, Web- a Web server, WebSphere MQ- an IBM WebSphere Queue Manager, DB2- a DB2 non-partitioned database or a DB2 database partition. During installation, the instance is associated with one AppTier and environment. An Instance can be moved to a different environment or associated with multiple environments without re-installation nor losing historical data. See also environment. See performance counter. In Precise for Oracle, the statistics information stored in Performance Warehouse. It provides insight into database behavior and database trends. The statistics include hit ratio information, redo logs statistics, tablespaces, and data file statistics. In Precise for SQL Server, the part of the Collect Schema Changes process that captures instance definition changes and database option changes and saves them in Performance Warehouse. In Precise for SQL Server and Precise for Sybase, the statistics information stored in Performance Warehouse. It provides insight and enables comparison of SQL Server internal performance counters and database files statistics. The process of inserting fault-tolerant recording hooks in Java byte code, .NET MSIL, HTML pages, or other monitored components, resulting in the capture of performance metrics. In Precise for J2EE, a mechanism that enables collecting performance information when an application is executed. The process involves inserting special fault-tolerant recording hooks into application class files, either in memory (Dynamic Instrumentation) or file-based (Static Instrumentation). See invocation context. The process of invoking a request from an HTTP request (Servlet or JSP) or an EJB. Precise for J2EE displays an internal invocation like any other invocation. A process that summarizes the performance of invoked elements that contribute to a service request's response time measurement. For example, an internally invoked Servlet or JSP, an EJB call or a JDBC call are contributors to a service request's response time and CPU time. The context within which a method is invoked. For example, if Method A is invoked from Method B and Method C, the invocation context for the performance metrics collected for Method A is different when Method A is invoked from Method B than when it is invoked from Method C. See also call path. An architecture that separates presentation details from business logic. This allows J2EE application developers to concentrate on writing the application components that represent the best business solution and leave the rest to the underlying platform. An application component is a self-contained module that is added to, and interfaces with, other application components. Application components include thin-client applications, applets, Servlets, Java ServerPages, and server-side Enterprise JavaBeans. For example, a J2EE application could have an HTML form to prompt the user for data, a Servlet to receive the data from the form and process it, and an Enterprise Bean to store data in a database. A Java object that groups multiple elements into a single unit. Collections are used to store, retrieve, and manipulate aggregate data. Object-oriented programming language and environment, invented and maintained by Sun Microsystems. The language is interpreted, which makes Java programs portable across many different operating systems and hardware platforms. The industry standard for database-independent connectivity between the Java platform and a wide range of databases. The JDBC provides a call-level Application Programming Interface for SQL-based database access.
instance statistics Statistics workspace instance/database changes instance/database statistics perspective instrumentation
instrumentation context internal invocation invocation
invocation context
J2EE 2 Platform, Enterprise Edition)
(Java
Java Collection Java
JDBC (Java Database Connectivity)
Glossary
126
JDBC time % JRE (Java Runtime Environment) JSP (Java Server Page) JVM (Java Virtual Machine)
The percentage of service request response time that is attributed to invoking JDBC calls. As the runtime part of the Java software, the combination of the components that enable the execution of a Java program: a Java virtual machine, the core class libraries, and the files that form the Java platform. An HTML page with special tags for Java scripting. An application server processes the tags and generates a Servlet. An instance of a JRE that executes Java programs. A server-side Java application server is itself a Java program that runs inside a JVM. Servlets, JSPs and EJBs are Java programs (applications) that run within the application server's JVM. Precise for J2EE monitors the JVM running the application server and the server-side Java applications within the application server. The amount of real computer memory that is allocated to the JVM for executing Java programs. In Alerts, a parameter that monitors a very important performance aspect. The status of the Oracle instance (up/down), for example, is crucial for system performance. If the instance is down, this is the first problem that needs to be solved. Marking a metric as key metric ensures that a critical alert raised for this metric receives top priority by the person that is responsible to handle alerts at any time. It can also help determine which alert to handle first in case of multiple alerts. In Alerts, key metrics are always displayed at the top of a metric table when it is sorted by alerts so that they get immediate attention. The agent that facilitates the communication between the various Precise agents across different servers must be installed on every server where collector agents or FocalPoint agents are installed. The Listener agent allows communication with all other agents installed on the monitored server, while only the Precise Listener port is known by other servers. In Precise for SQL Server and Precise for Sybase, the session identifier that represents the credential used to connect to the database. When an ERP extension is installed, the user name of the packaged application's client overrides the login name. For example, when SAP extension is installed, the SAP user name overrides the login name. A session identifier. A machine as sampled, for example, by the Precise for SQL Server Collector agent is the identification of the machine where the client process executes. Machine is also sampled by Precise for Oracle, Precise for DB2 and Precise for Sybase. In Insight terminology Machine is called Client machine. A main framework node is the single point for login and also serves as the Precise FocalPoint for the entire deployment. Number of estimated major garbage collection events that occurred during the last J2EE Collector aggregation interval. A major garbage collection can stop the application while JVM heap memory is being reclaimed. See also garbage collection. Percentage of time spent by the JVM executing major garbage collection events during the displayed interval. See also garbage collection. A Java object that represents a manageable resource. In Precise for J2EE, MBeans, or Managed Beans, are used for application server metrics. See aggregation interval. The interval at which the Precise for J2EE Collector agent gathers JVM heap memory data. All snapshots of the memory logger's data collected according to the memory logger interval are summarized with counters in the current aggregation interval. The memory logger interval's time span is typically a small fraction of the aggregation interval. In Alerts, a query that helps measure performance in the environment. Three types of metrics are available: System metrics relate to the internal resources, operations, and objects of the monitored infrastructure; application metrics reflect the way the applications perform; user-defined metrics can be customized to specifically relate to a site. When a metric's value exceeds one of the defined thresholds, its status changes to near-critical (yellow bullet) or critical (red bullet). See also key metric. In Alerts, a unit that groups metrics that measure related performance aspects. The following metric sets exist: Status: includes metrics that alert to functional problems related to the instance. Performance: includes metrics that alert to performance problems related to the instance.
JVM Heap Memory key metric
Listener
login name
machine
Main framework node major collection count
major garbage collection time
MBean measurement interval memory logger interval
metric
metric set
Glossary
127
Load: includes metrics that alert to instance-related load problems that may later cause errors or crashes. Service: includes metrics that alert to instance-related SLA breaches. The metrics in this set are sampled by Insight. Performance Trending: includes metrics that alert to potential future performance problems. The metrics in this set are sampled by Report Manager. Load Trending: includes metrics that alert to potential future load problems. The metrics in this set are sampled by Report Manager. Customized: includes user-defined metrics. Precise Status: includes metrics that alert to the near-critical or critical status of the installed Precise environment. module A session identifier. In Precise for Oracle it contains the value of MODULE column in V$SESSION table. In Precise for DB2 it contains the command name of non-SQL statements or the package name for SQL statements. In Alerts, a status indicating that the value of the sampled metric has exceeded the defined near-critical threshold. A near-critical status is indicated by a yellow bullet. In Precise for Web, a counter that keeps track of the time spent on network activity from the server side perspective. This includes the time to read the request from the network and the network time to send the response back to the client. See Framework node. Note: when creating a new installation from DVD, it would be called "Framework." In the UI screens (columns in tables, choosing a system for a new environment etc), we would call them "Nodes." For example: choose a node for the new environment. When adding a new system within AdminPoint, it would be called a "Framework node". other overflow Represents invocations of a type not specifically defined. See also work time. In Precise for J2EE, the process of moving the oldest active data slice under the overflow label when the age of active archived data exceeds the Aging Timespan value. If overflow is not enabled, the oldest active data slice is removed. An application that is created and/or maintained by a third party and is not custom-built to one's specific needs. The following packaged applications have special treatment by Precise: SAP, Oracle Applications, PeopleSoft, and Siebel. They are harder to modify because the application code is either not available or hard to understand. See also ERP extension. page size page views parent metric In Precise for Web, a counter that keeps track of the amount of data loaded from the server to display the page. In Precise for Web, a counter that keeps track of the number of Web pages viewed at a specific Web site during a selected time period. In Alerts, a joining of several child metrics. Each time a parent metric samples, it gathers data from a set of child metrics and presents it as a single metric query. The individual child metric values are displayed on the Thresholds tab of the Properties dialog box in Alerts. See also submetric. performance counter Performance Warehouse portal server In Precise for SQL Server and Precise for Oracle, a Windows performance counter as reported by the operating system. In Precise for Sybase, a sysmonitors counter collected by Sybase. In Precise for Web, an operating system or a Web server performance counter. The Precise data warehouse of performance and availability data. It can be hosted on an Oracle or SQL Server database. An application server for Web-based applications that commonly provide personalization, single sign-on, and content aggregation from different sources and that host the presentation layer of Information Systems. Aggregation is the action of integrating content from different sources within a Web page. A portal may have sophisticated personalization features to provide customized content to users. Portal pages may have a different set of portlets creating content for different users.
near-critical status network time
node
packaged application
Glossary
128
portlet
A Java-based Web component, managed by a portlet container, that processes requests and generates dynamic content. Portlets are used by portals as pluggable user interface components that provide a presentation layer to Information Systems. Includes and can refer to the following major product components: Alerts Insight Report Manager Precise for Web Precise for SAP Precise for J2EE Precise for Microsoft .NET Precise for Oracle Precise for DB2 Precise for SQL Server Precise for Sybase See also Insight. See also Alerts See also Report Manager
Precise
Precise deployment Precise FocalPoint Precise FocalPoint agent Precise Proxy agent Precise FocalPoint
An independent Precise system. It contains and manages various agent types and provides centralized monitoring and administration. A Precise deployment may contain multiple framework nodes. One of them is defined as the main framework node and it manages all other nodes of the Precise deployment. See Precise FocalPoint agent. An agent that manages all agents in a single Precise deployment. Additional product FocalPoint agents manage specific technologies and resources. When multiple Framework Nodes are managed by a single Precise deployment, the Precise FocalPoint agent manages all of the agents of the main Framework node, while every other framework node has a Precise Proxy agent to manage all its agents. An agent that communicates with the Listener agents installed on the monitored servers, receives data from the Collector agents, periodically processes and stores this data in Performance Warehouse, and serves UI requests. A session identifier in Precise for Oracle, Precise for DB2, Precise for SQL Server, Precise for Sybase, Insight, and Alerts. A program as sampled, for example, by the Precise for SQL Server Collector agent, is the name of the executable that connects to the database. Applications that do not set the application name have N/A as program. When SAP extension is installed, the SAP transaction overrides the program, and it may change during the application's lifetime. When Siebel extension is installed, the Siebel views override the program, and it may change during the application's lifetime. In Insight, program is the name of an executable as recognized by the operating system. If an executable is invoked from a script (a batch or a shell), the script is displayed as the command entity. In Alerts, program is part of the customized metrics definition and is the name of the executable or stored procedure executed in the database that runs when the metric is sampled. In action definitions, program is the name of the executable that will run if the metric exceeds its threshold. In Alerts, the management state of a metric for which an alert has been raised. The following statuses exist: Open: An alert is raised. Investigated: The alert is taken care of. Closed: The problem has been solved.
program
progress
Proxy FocalPoint recent data
See Precise Proxy agent A time series consisting of the most recent number of aggregation intervals of a Precise for J2EE Collector agent. When a new data sample is collected, it is placed at the beginning of the recent time series. Old recent series's items are removed from the end. In Precise for SQL Server, a function that uses the Microsoft Index Tuning Wizard to recommend on adding indexes or statistics for a selected statement, batch, or table. Based on the results of this function, the Optimizer will choose a better access plan and make the respective statement or batch perform better. For statements and batches, recommendations are based on the content of the statement or batch. For tables,
recommended index
Glossary
129
recommendations are based on all the statements that are stored in Performance Warehouse, are executed during the selected time period, and have an average duration time greater than the value defined in the registry (where 0 is the default). See also advice. related SQL relative frequency In Precise for Oracle, a generated statement that uses alternative syntax to access the database in different ways and returns the same output as the original statement. Number of contributor invocations per service request execution. For example, if a service request calls three methods each time it is invoked, the Relative Frequency for the method is three invocations per service request execution. Similarly, if a service request calls one method every other time it is invoked (half of the time), the Relative Frequency for the method is 0.5 invocations per service request execution. In Precise for Web, a counter that keeps track of the time that it takes for a Web page to be loaded from the moment the first byte arrives until the Web page is fully loaded or the user interrupts or abandons the loading process. A collection of queries, programming code, and layout settings that Report Manager executes to generate graphical results like tables and charts. Uses historical information to identify problematic conditions, track long-term performance, volume trends and patterns, view availability problems over long periods of time and on different levels, compare the performance of similar systems, correlate between performance metrics of different products, assist in capacity planning, and generate demand-driven, user-defined reports. An agent that examines the Performance Warehouse tables to produce scheduled performance reports. See also Performance Warehouse. In Report Manager, a keyword used in a report. Its value is set during the report execution. A parameter's value can be updated either permanently or for the current execution only. In Report Manager, the attributes that define a specific report, consisting of report parameters and scheduling information. See also report parameter. request request error sampling sampling base sampling period In Precise for Web, a counter that keeps track of the number of HTTP requests sent for a viewed entity. In Precise for Web, a counter that keeps track of the percentage of requests completed with an HTTP error. In Alerts, the process during which a metric queries a Precise product for a specific instance, retrieves values, and calculates the metric's alert level. In Alerts, the start time of a scheduled sampling process (by default Sunday, 00:00 AM). In specific Alerts metrics, the time frame during which statistical data is returned from other Precise products. Such a metric is for example Oracle's General Behavior metric, which returns database behavior for a certain period of time. In Alerts, the frequency of a metric's regular sampling schedule. The sampling rate is measured in minutes. An Insight agent that collects AppTier-specific performance data. A system's ability to withstand load. For example, positive scalability means that the system continues to function properly even when it is called upon to service a larger number of users. In Precise for Oracle and Precise for SQL Server, a process that captures schema changes and saves them in Performance Warehouse. In Precise for SQL Server, instance configuration parameters and database option changes are also captured. A component of Precise Agent Installer that enables adding a small JavaScript script, also known as a Precise for Web browser-side agent, to the Web pages of your Web site. Also called a host machine or server machine. The combination of a computer and associated operating system software that is accessed by multiple clients to perform requested functions and typically returns results to the clients. In Precise for Web, the collecting of performance data from the Web server instance through the Web server agent. In Precise for Web, a counter that keeps track of the service and network time, including the total amount of time the request took to reach the server.
rendering time
report Report Manager
Report Manager FocalPoint
report parameter report property
sampling rate Savvy scalability schema changes
Script Installer server
server-side collection service + network time
Glossary
130
Service Level Agreement service request
See SLA (Service Level Agreement). A top-level HTTP or EJB request. A service request can originate when a user clicks in a browser or an E-commerce server invokes a remote EJB. Precise for J2EE makes a distinction between service request invocations and other invocations. The first HTTP or EJB invocation within a call path is designated as a service request. The time elapsed from when a request is received by the server to the time a response is sent back to the computer that made that request. The service time is measured on the server side. In Precise for J2EE, the time it takes an invocation to complete execution. In other words, service time is the average length of time between the start time and end time of a Java method execution. For example, the SQL service time is the time it takes the JDBC method executing the SQL statement to be completed. The service time includes CPU and wait time. The service times are reported in the interval in which they complete execution. Though a contributor's average service time may be very small, the contributor may be called many times. As a result, a contributor's overall contribution to performance may be large even though its average service time is low. It is, therefore, a good rule of thumb to also analyze the throughput, weighted throughput, relative frequency, and weighted service time before making performance conclusions on the average service time. A class that is loaded only once and for which the application server uses multithreading to process requests. The servlet generates an HTML page that is sent back to the Web browser. In Precise for Web, a counter that keeps track of the bytes sent and received. A formal definition of an information system's performance goals. Within Precise, an SLA consists of clauses corresponding to various system activities. Once a system's SLA is defined, its SLA compliance can be analyzed, and breaches can be isolated to identify their causes. See aggregation interval. In Insight, a component that provides transactive, correlated information across AppTiers from the user's perspective. Insight SmartLink functions in PeopleSoft and Web applications environments. In Precise for Oracle, Precise for SQL Server, and Precise for J2EE, an algorithm that analyzes performance metrics, identifies and ranks potential problem areas, and provides advice for correcting the problems. An I/O abstraction layer that enables processes to communicate with each other, regardless of whether they are on the same machine. Sockets are bi-directional FIFO pipes that look like regular file I/O to the developer with the abstraction layer handling all of the low-level communication details. The opening page of Precise. It provides a quick overview of the environment status and links to launch any of the Precise products. Also called child metric. In Alerts, the subquery of a parent metric. A child metric gathers its own data and combines it with the data gathered by other child metrics to form the result of the parent metric. Each child metric has its own thresholds and may be enabled or disabled individually. See also parent metric. A container that stores the information collected by the Precise agents and loads it into Performance Warehouse. Summary tables store the same data at different levels of granularity: time slice, hourly, daily, weekly, and monthly. By storing data in multiple summary tables, Precise can present a detailed view and progressively higher-level views of the same data. Summary tables are particularly useful for data aging. A data purging policy can be implemented for each summary table so that detailed data is retained for short-term historical analyses while more summarized data is used for long-term analyses and trending. A technology identifies the monitored object. For example, Oracle, SQL Server, Sybase, and DB2 are different technologies, while all Web servers (such as: Apache, IIS, and WebSphere) are defined as a single Web technology. A single monitored object can be monitored by two different technology's Collector agents. For example, BEA WebLogic server can be monitored by both Precise for Web collector agent and Precise for J2EE Collector agent. The number of average completions per second that are observed during an interval. A range of one or more aggregation intervals. A unit used to break up long sessions into smaller time periods. The length of a time slice is preset and cannot be changed. It represents the maximum time that passes before the data collected can be displayed. For example, if the length of a time slice is 15 minutes, the collection is only updated at 15-minute intervals.
service time
servlet size SLA (Service Level Agreement) slice SmartLink SmarTune
socket
StartPoint submetric
summary table
technology
throughput time series time slice
Glossary
131
The length of a time slice is different for each i product: In Precise for Oracle, Precise for SQL Server and Precise for Sybase, a time slice is 15 minutes. In Precise for J2EE, a time slice is also called a data sample and a slice, the period of time over which data is collected, reported and stored for a JVM. The time slice period is Precise for J2EE's smallest storage unit. A time slice also represents the Precise for J2EE Collector agent's aggregation interval. The aggregation interval is the period from the start time to the end time of a time slice and summarizes all the events that occurred during the interval. In Precise for SAP, a time slice is comprised of 5-minute intervals, meaning that the data is summarized every 5 minutes. See also aggregation interval. Tuner agent In Precise for Oracle, Precise for SQL Server, and Precise for Sybase, a software component that provides a comprehensive database objects browser and a rich set of tuning features. See also agent. URI (Uniform Resource Identifier) URL mapping The relative path to a resource after the location (network node) is found.
In Precise for Web, a function that defines rules that map URLs (Uniform Resource Locators) with dynamic parameters originating from a specific domain to a format that identifies the Web pages and prevents them from having different URLs. A program that receives client requests for Web pages, retrieves the static pages and/or issues a request for dynamic page creation to an application server, and sends the pages to the client. In Precise for Web, a computer that delivers (serves up) Web pages. Every Web server has an IP address and possibly a domain name. The percentage of the total CPU time spent in different contributors. The total CPU time concerns the location displayed in the Navigation path. The percentage of the total response time spent in different contributors. The total response time concerns the location displayed in the Navigation path. For example, if a service request response time is 1 second and it makes two JDBC calls, each taking a quarter of a second, the JDBC Weighted Response time is 50 percent of the service request's response time. The percentage contribution of each displayed item to the total throughput. The total throughput concerns the location displayed in the Navigation path. For example, if a service request calls three Java methods each time it is invoked, the Java method Weighted Throughput is 300 percent of the service request's throughput. Similarly, if a service request calls one Java method every other time that it is executed (half of the time), the weighted throughput for the Java method is 50 percent. The time spent on everything not directly accounted for by instrumentation, including the invocation time or CPU time. In Precise for Web, a counter that keeps track of the type of the Web instance, such as Web, PeopleSoft, SAP, or Siebel. A display unit in Precise products. All workspaces display data from different perspectives. For example, in Precise for Oracle, Precise for SQL Server, and Precise for Sybase, the Current workspace shows information on the sessions currently active in an application, and the Objects workspace displays information on Oracle or SQL Server database objects that can be used to understand relationships and associations between database schema objects.
Web server
weighted CPU time weighted response time
weighted throughput
work time work type workspace
Index
A
Activity workspace 69 identifying performance problems 81 list of tabs 71 Adaptive Instrumentation 35 Adaptive Instrumentation Wizard page 38 Add Statistics to Configuration page 45 adding custom instrumentation configuration file 92 administration pages Business Transactions Administration page 27 FocalPoint Administration page 18 Java Virtual Machine Settings Administration page 15 SmarTune Administration page 20 Statistics Administration page 44 Status Details page 29 System Status page 28 Aging Timespan 19 All JVMs Health portlet 54 All JVMs Threads portlet 54 application server classes in Leak Seeker instrumentation 116 application server metrics 44, 85 applying instrumentation using Calls to EJB instrumentation feature 108 Archive Data Selection page 13 Archive File Selection page 14 Archive Slice Selection page 14 archiving options 19 Copy Instrumentation Wizard page 46 custom instrumentation adding 91, 92 configuration 112 custom instrumenter configuration 93
D
Dashboard workspace identifying performance problems 66 portlets 51 configuring 52 list of 53 time frame 51, 52 data files ICU 117, 118 database configuring 19 disabling instrumentation for method 119 instrumentation using ICU 119 display intervals 12
E
EJB implementation 106 EJB Service Requests 69 enabling additional configuration file 92 instrumentation using ICU 119 instrumentation for method 119 Exception Seeker portlet 55 Exceptions tab 80 extending instrumentation 96, 97, 100, 101 wildcards 97
B
build number and product version 11 Business Transactions creating 28 portlet 64 Business Transactions Administration page 27
C
call from method instrumenting 102 instrumenting 106 to method instrumenting 102 class instrumenting 98 Concurrent Active Threads portlet 55 configuration custom instrumentation 92, 112 custom instrumenter 93 enabling additional file 92 file instrumenter 91 instrumentation 112, 113
F
file configuration instrumenter 110 instrumenter reference 108 instrumenter structure 111 master 109 FocalPoint Administration page 18 functionality ICU 116
G
General Options bar 11 General toolbar 11 graphs 12 Grouped JVMs Health portlet 56 Grouped JVMs Threads portlet 57
Index
133
H
Highlights tab 72 Hotspots tab 73 HTTP Service Requests 69 HTTPS enabling 20
instrumenting 94 invocation context 71 Invocation Type Scalability portlet 57 invocations 70 Invocations tab 75 IXP Direct Connect enabling 17
I
ICU disabling instrumentation 119 enabling instrumentation 119 functionality 116 identifying methods 118 loading data files 118 obtaining data files 117 prerequisites 117 running 117 system requirements 116 using 116 identifying methods ICU 118 ignoring instrumentation configuration 113 implementing calls to EJB 106 in Leak Seeker instrumentation application server classes 116 Inactive Archive label 19 Inactive Archive Path 14 instrumentation 94 Adaptive Instrumentation 34 adding custom configuration file 92 configuring all calls from method 112 calls from method to method 113 copying 46 custom configuration 91, 112 extending 96, 97, 100, 101 feature 106, 108 ignoring configuration 113 modes 16, 33 preventing 103, 104, 105, 106 restricting 95, 99 Instrumentation Configuration Utility see ICU 116 Instrumentation Explorer page 42 instrumenter configuration custom 93 file 110 file reference 108 file structure 111 matching techniques 114 modifying configuration files 91 instrumenting calls from method 102 to EJB business method implementations 106 to method 102 class 98 interfaces 94 methods 94, 98 interface
J
Java Virtual Machine Settings Administration page 15 Java Virtual Machine Settings page 16 JDBC Metrics portlet 57 JVM Health portlet 58 JVM List portlet 53
L
Leak Seeker Metrics portlet 59 Loading Data ... page 15 loading data files ICU 118 Lock Seeker Metrics portlet 59 Locks tab 79 logging in 48
M
Main Area 11 master configuration file 109 matching method signature 115 techniques instrumenter configuration 114 MBeans 45 Memory Garbage Collection workspace 89 Memory Heap workspace 88 Memory LeakSeeker workspace 89 Memory Metrics portlet 59 Memory workspace 88 Method Scalability portlet 60 methods disabling instrumentation 119 enabling instrumentation 119 instrumenting 94, 98 signature matching 115 modifying instrumenter configuration files 91
O
obtaining data files ICU 117 Oracle database switching to 19 Overflow Enabled 19 Overflow label 19
P
Portal Server Metrics portlet 61 portlet 51 prerequisites ICU 117 preventing instrumentation 103, 104, 105, 106
Index
134
R
Recent Items Charted 18 Recent Slices 18 Refresh Enabled? 18 Refresh Interval 18 requirements ICU 116 restricting instrumentation 95, 99 running ICU 117
time series 12 Top Business Transactions portlet 64 Top Instrumented Methods portlet 64 Top Methods by Invocation Type portlet 65
U
Update button 18 user interface administration 18 launching 48 using custom instrumentation 91 ICU 116 wildcard character 115
S
security enabling HTTPS 20 SmarTune Application Summary portlet 63 SmarTune portlet 62 SmarTune workspace administration 20 application summary categories 23 contributor categories 21 SQL statements collected 17 SQL Statements portlet 61 SQL tab 77 Statistics Administration page 44 Statistics portlet 63 Statistics workspace 85, 86 solving performance problems 87 status 28 component 29 Status Details page 28, 29 structure instrumenter configuration file 111 system requirements ICU 116 System Status page 28
V
version product build number 11
W
wildcard 100 character * 115 extending 97 using 96, 100 Work Time 71 Work Times of Invocation Types portlet 66 workspace Memory Garbage Collection 89 Memory Heap 88 Memory Leakseeker 89 Workspace selection bar 10 workspaces Activity 69 Dashboard 50 Memory 88 Statistics 85 structure 9
T
techniques instrumenter configuration 114

Precise For J2EE v87 UG

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Precise For J2EE v87 UG

Caricato da

Copyright:

Formati disponibili

Precise for J2EE

Precise for J2EE Users Guide

Third-party legal notices

Document change history

Getting an overview of your environment in the Dashboard workspace

Examining performance over time in the Activity workspace

Examining application server metrics in the Statistics workspace

Examining usage and trends in the Memory workspace

Configuring Precise for J2EE instrumentation

Precise for J2EE Basics

How most workspaces are structured

Precise for J2EE Basics How most workspaces are structured

Workspace selection bar Status bar

General options bar Analysis tabs

About the Workspace selection bar

Dashboard Activity Statistics Memory

Precise for J2EE workspaces Description

Precise for J2EE Basics How most workspaces are structured

Table 2-1 Workspace

Precise for J2EE workspaces Description

Switching to a different workspace

About the General Options bar

Help System-working dots Precise logo

About the Call Path

About the General toolbar

About the Main area

Precise for J2EE Basics About display intervals

Invocations Business SQL Locks Exceptions

About Main area features

About bar graphs for a time slice

About line graphs for a time series

About the Association area

About display intervals

About the Time Frame

Precise for J2EE Basics About display intervals

Archive Chooser OK Cancel

Time Frame options Description

Enter a number and select a time interval.

See About Archiving Options on page 19.

About the Archive Data Selection page

Precise for J2EE Basics About display intervals

Archive Data Selection page options Description

About the Archive File Selection page

About the Archive Slice and Series Selection page

Precise for J2EE Basics About administration pages

Selecting data for analysis

About the Loading data... message

About administration pages

About the Java Virtual Machine Settings Administration page

In the General Options bar, click Settings.

About the Monitoring Configuration page

Precise for J2EE Basics About administration pages

About the Java Virtual Machine Settings Administration options

Java Virtual Machine Settings Administration options Description

Java Virtual Machine

Collection & Filtering

Run Adaptive Instrumentation now

Run Copy Instrumentation now

Open Expert Configuration

About the Java Virtual Machine Settings page

Precise for J2EE Basics About administration pages

Java Virtual Machine Settings Description