Optimizeit Profiler 6 - cca.yuntech.edu.twcca.yuntech.edu.tw/cca/ccawork/cca系統設備資料/jbxpdfdocs_e/profiler.pdf · Borland Software Corporation 100 Enterprise Way Scotts

Optimizeit™ Profiler 6.0

for Java™

User’s Guide

Borland Software Corporation100 Enterprise WayScotts Valley, California 95066-3249www.borland.com

Borland Software Corporation may have patents and/or pending patent applications covering subjectmatter in this document. Please refer to the product CD or the About dialog box for the list ofapplicable patents. The furnishing of this document does not give you any license to these patents.

COPYRIGHT © 1997–2003 Borland Software Corporation. All rights reserved. All Borland brand andproduct names are trademarks or registered trademarks of Borland Software Corporation in theUnited States and other countries. All other marks are the property of their respective owners.

For third-party conditions and disclaimers, see the Release Notes on your Borland product CD.

Printed in the U.S.A.

oi60p 4E3R10030304050607-9 8 7 6 5 4 3 2 1PDF

i

Chapter 1Getting Started 1When to use Profiler. . . . . . . . . . . . . . . . 1Installing Optimizeit . . . . . . . . . . . . . . . . 2

Using the virtual machine wizard. . . . . . . . 3Integrating Optimizeit with other tools . . . . . . . 4Running Profiler . . . . . . . . . . . . . . . . . . 4

Chapter 2Defining your test program 7Using the Startup page . . . . . . . . . . . . . . 8

Choosing your program type . . . . . . . . . . 9Choosing your program location . . . . . . . . 9Choosing operation options . . . . . . . . . 10Choosing extra Java or

program parameters . . . . . . . . . . . . 10Choosing your class path and

source path . . . . . . . . . . . . . . . . . 10Using the Filters tab . . . . . . . . . . . . . . . 11

Creating and editing filters . . . . . . . . . . 14Creating filters . . . . . . . . . . . . . . . . 14Editing filters . . . . . . . . . . . . . . . . . 15

Using the Virtual Machines tab . . . . . . . . . 17Adding a virtual machine . . . . . . . . . . . 17Setting virtual machine properties . . . . . . 17

Chapter 3Running Optimizeit from the command line 19

Starting from the command line . . . . . . . . . 19Setting up the audit system . . . . . . . . . 20Launching your program . . . . . . . . . . . 20Windows audit system options . . . . . . . . 21UNIX audit system options . . . . . . . . . . 23

Optimizeit libraries . . . . . . . . . . . . 26Java 2 Examples . . . . . . . . . . . . . 26

Using Profiler with the Hotspot runtime . . . 28Creating a custom JAR for

the bootclasspath . . . . . . . . . . . . 28Setting the bootclasspath for

Hotspot VMs. . . . . . . . . . . . . . . 29Connecting the audit system . . . . . . . . . 29

Starting on a different machine . . . . . . . . . 30Using the Filter Editor . . . . . . . . . . . . . . 31Offline profiling . . . . . . . . . . . . . . . . . 33

Memory Profiler offline testing options. . . . 35Examples . . . . . . . . . . . . . . . . . 36

CPU Profiler offline testing options . . . . . 37Starting from the test program . . . . . . . . . 37

Adding API calls in your program . . . . . . 38Starting your test program . . . . . . . . . . 38

Chapter 4Using the Memory Profiler 41Memory Profiler modes . . . . . . . . . . . . . 42Controlling the test program . . . . . . . . . . 42Using the heap view . . . . . . . . . . . . . . 43

Heap mode inspector options . . . . . . . . 45Using allocation backtraces . . . . . . . . . . . 45

Allocation Backtrace inspector options . . . 48Tracking temporary object allocations . . . . 49

Viewing instances and reference graphs . . . . 50Outgoing reference graph . . . . . . . . . . 51Reduced reference graph . . . . . . . . . . 52Instance Display inspector options . . . . . 53

Using the Memory Leak Detector . . . . . . . . 54Browsing references from roots. . . . . . . . . 56

Object graph inspector options . . . . . . . 58Using the Virtual Machine Information mode . . 58

Virtual Machine Information inspector options . . . . . . . . . . . . . . 60

Chapter 5Using the CPU Profiler 61Recording a test session . . . . . . . . . . . . 61Understanding CPU Profiler output . . . . . . . 63Refining the CPU Profiler display . . . . . . . . 66

Chapter 6Application Quality Analyzer 69Upper pane of the Application

Quality Analyzer view . . . . . . . . . . . . . 70

Contents

ii

Lower pane of the Application Quality Analyzer view . . . . . . . . . . . . . 71

Abnormal container growth information . . . 71Inefficient StringBuffer use information. . . . 71Abnormal garbage collection information . . 72Exception information . . . . . . . . . . . . 72Abnormal finalizer queue

length information. . . . . . . . . . . . . . 73Unclosed file descriptor information . . . . . 73

Inspector options for the Quality Analyzer view . . . . . . . . . . . . . 73

Quality Analyzer Options . . . . . . . . . . . 74

Chapter 7Display features 77Using snapshots. . . . . . . . . . . . . . . . . 77Generating PDF reports . . . . . . . . . . . . . 79Exporting data . . . . . . . . . . . . . . . . . . 81Viewing source code . . . . . . . . . . . . . . 82Displaying Optimizeit console messages . . . . 82Using the Find panel . . . . . . . . . . . . . . 83

Chapter 8Setting your preferences 85Selecting default displays . . . . . . . . . . . . 85Setting launch parameters . . . . . . . . . . . 86Setting the source code location . . . . . . . . 87

Changing the default source path . . . . . . 87Changing the class path . . . . . . . . . . . . 88Selecting a virtual machine . . . . . . . . . . . 89Configuring servlet support . . . . . . . . . . . 90Miscellaneous options . . . . . . . . . . . . . 91

Chapter 9Troubleshooting 93Starting your application . . . . . . . . . . . . 93Starting your application server . . . . . . . . . 97Problems during testing. . . . . . . . . . . . . 100Undoing an integration (Windows only) . . . . . 104

Index 105

Chapter 1: Get t ing Started 1

C h a p t e r

Chapter 1Getting StartedOptimizeit Profiler enables developers to test and improve the performance of their Java applications, applets, servlets, JavaBeans, Enterprise JavaBeans (EJBs) and JavaServer Pages (JSPs). Developers can go behind the scenes of the Java virtual machine to identify any Java code allocating too much memory or using the CPU in an inefficient way.

The following sections introduce Profiler and describe how it is installed and run:■ “When to use Profiler”■ “Installing Optimizeit”■ “Integrating Optimizeit with other tools”■ “Running Profiler”

When to use ProfilerOptimizeit Profiler includes a Java setup wizard for fast and simple configuration, and there is no need to recompile your program with a custom compiler or to modify class files before execution. Just run your program from Optimizeit Profiler to start testing its performance. Because no code modification is required, any Java code that your program uses is included in the test.

Once you launch Optimizeit Profiler, you can either access the Memory Profiler or the CPU Profiler:

2 Prof i ler User’s Guide

Instal l ing Opt imizei t

■ The Memory Profiler provides real-time display of all classes used by the test program and of the number of allocated instances. Use Memory Profiler to view incoming and outgoing object references in real time, string representations of allocated instances, and references from reference graph roots.

Memory Profiler includes:■ Filters so you can focus on relevant classes■ Controls for garbage collection■ API calls so you can invoke the Memory Profiler from inside the test

program■ Links to your source code

For Java 2 JDKs, the Memory Profiler has extra features, such as reduced reference graphs for incoming references and a Memory Leak Detector.

■ The CPU Profiler displays test results for each thread or thread group for pure CPU use or for elapsed time (pure CPU and inactive phases). You can start or stop testing at any time, with millisecond or microsecond precision. The CPU Profiler has both sampler-based and instrumentation-based (Java2 only) modes, and also contains filters to remove fast methods.

Optimizeit Profiler also has a Virtual Machine Info mode that displays and exports charts showing high-level VM information including heap size, heap used, number of threads, number of busy threads, and number of loaded classes. If you are using a Java2 JDK, Virtual Machine Info mode also displays a graph for garbage collector activity.

Profiler contains many options for viewing and saving your data, including a snapshot option that saves snapshots of a test session at any time. Snapshots can be reloaded later for analysis or test comparison. An offline testing mode can automatically save snapshots at fixed intervals and at VM exit.

Installing OptimizeitTo install Optimizeit, load your Optimizeit CD. Written installation instructions are located in the install.html file in the root directory of the CD. Optimizeit does not support directories with spaces in the name (for example, Program Files), so make sure there are no spaces in your installation directory name. Make sure your software and virtual machine are supported. Refer to the Release Notes for a complete listing of supported platforms and VMs.

Important Make sure you have installed the latest current release with all current patches for your OS and JDK version; for example, there are some problems using JDK version 1.3.1_02 that do not appear when JDK version 1.3.1_09 or JDK 1.4.2 are used.

If you are installing the Optimizeit Suite, you will be installing all three Optimizeit tools, Profiler, Code Coverage, and Thread Debugger, at once. All three tools share the same setting files and the same IDE and application server integrations:


Instal l ing Opt imizei t

■ Because all three tools share the same settings, you can load any Optimizeit setting file into any Optimizeit tool. For example, you can create some classpath, source path, and virtual machine settings in Profiler, save them, and then use these same settings with Thread Debugger.

■ If you integrate any Optimizeit tool with an IDE or an application server, all three tools will be immediately ready to use those environments, without any further configuration.

■ On Windows platforms, the Audit System Selector option places an icon on your toolbar that allows you to easily switch between the three tools.

The Optimizeit root directory also contains Release Notes. These Release Notes list added platforms and Java development environments, and describe a subset of known problems, workarounds, and tips for Optimizeit.

Using the virtual machine wizard

By default, Optimizeit uses a Java 2 runtime. When Optimizeit is installed, a default JDK version 1.4.2 is also installed, but as shown in the table above, Optimizeit is compatible with many Java virtual machines.

The first time you run Optimizeit, a Java setup wizard starts automatically to help you select a virtual machine:

Note You can also access this wizard at any time from Tools|Java Setup.

1 If you want to use the default JRE, click Cancel, and the wizard returns you to Optimizeit.

2 If you want to configure Optimizeit to use a different virtual machine, click Next.

3 Select the directory where you want the wizard to search for available virtual machines. The wizard scans the selected directory or drive and lists all available virtual machines.

Tip After you see the message Found 1 virtual machine you can click Stop to end the scan.

4 Select the virtual machine you want to use.


Integrat ing Opt imizei t wi th other tools

5 Click Next, then click Finish.

6 After changing the default virtual machine, Optimizeit prompts you to confirm that the new default virtual machine should be used with the current settings. Click Yes to start using that virtual machine.

Integrating Optimizeit with other toolsAs described in Chapter 2, “Defining your test program,” you can specify and start test sessions from the Optimizeit user interface without integrating with a web server or application server. However, to run Optimizeit from the command line and take advantage of offline profiling you must integrate with the Java tool used to run the application you are testing. Integration wizards are provided for all supported web and application servers. However, since Optimizeit can be integrated with most application servers that use compatible virtual machines, integration instructions are provided for manually integrating Optimizeit with a variety of different servers.

Optimizeit also integrates with several integrated development environments (IDEs) to help speed application development and test cycles.

See the Release Notes for a list of supported web and application servers, and IDEs, and refer to the Optimizeit Integration Guide for integration instructions and additional information. If you have trouble integrating your tool, see Chapter 9, “Troubleshooting.”

Running ProfilerOnce Optimizeit is installed, you must enter your test program information so that Optimizeit can locate the application, applet, or servlet to be tested, and can test the appropriate areas:

1 If you have never used Optimizeit before, or have never created your own settings file, start with Chapter 2, “Defining your test program.”

2 If you know about settings files but need to learn how to start a test from the command line, go to Chapter 3, “Running Optimizeit from the command line.”

Note Each chapter builds on the information contained in the previous chapter. Do not skip chapters unless you are familiar with the procedures.

To run Optimizeit Profiler:

1 By default, Profiler starts in Memory Profiler mode, as described in Chapter 4, “Using the Memory Profiler.”

2 To analyze the methods your program uses, switch to the CPU Profiler, as described in Chapter 5, “Using the CPU Profiler.”

3 To store and analyze your profile data, use the capture and display functions described in Chapter 7, “Display features.”


Running Prof i ler

4 Make changes to your source code and repeat these steps until you are satisfied with your program’s performance.

From within Profiler, use the menu items described in Chapter 8, “Setting your preferences,” to choose your startup window, your default source and class paths, and other defaults.

This manual also contains Chapter 9, “Troubleshooting,” which answers frequently asked questions on Optimizeit installation and configuration. The Troubleshooting chapter can also be accessed from the Info|Troubleshooting Optimizeit menu.


Chapter 2: Def in ing your test program 7

C h a p t e r

Chapter2Defining your test programWhen you first start Optimizeit, it opens the Edit Settings dialog box:

Use the Settings dialog box to modify your source path, class path, filters (if any), and virtual machines. This dialog box is a centralized location for many configuration items, which is convenient if you are testing a program from within the Optimizeit user interface. You can also access the Settings dialog box with the following File menu commands:


Using the Startup page

■ File|New Settings —opens a new settings dialog box, with only the Optimizeit defaults specified.

■ File|Open Settings —allows you to browse for a settings file to use.■ File|Open Recent Settings —displays a list of recently accessed settings

files (generated by any Optimizeit tool) for you to choose from.■ File| Edit Settings—opens the current settings file, which you can either run

again or edit to run a new test.

The Settings dialog box contains the following pages:■ Startup—this page contains the required elements for your configuration,

such as the program type, location, Class path and Source path.■ Filters—if there are specific packages or classes you wish to test or ignore,

use the Filters page.■ Virtual Machines—by default, Optimizeit tests with a Java 2 runtime. If you

want to specify a virtual machine other than the default, use the Virtual Machines page.

Once you have configured the settings, you can save this configuration in a file when you exit Optimizeit. By default, information from the last-saved settings file is automatically loaded into Optimizeit when you open the program. The same settings file can be used in Optimizeit Profiler, Code Coverage, or Thread Debugger. Use the Save and Open commands on the File menu to save settings files and access existing ones.

Using the Startup pageThis section describes how to fill out the Startup page of the Settings dialog box in Optimizeit. The Startup page lets you specify the following settings for testing:■ Program type■ Program location and working directory■ Operation options■ Extra Java or program parameters■ Class path and source path

Once you have filled out the Startup tab, if you want to use the default virtual machine and filters, click Start Now to begin testing. Optimizeit starts the application and opens the default view.

See also■ Chapter 8, “Setting your preferences,” for more information about setting

defaults.



Choosing your program type

The first option on the Startup tab of the Settings dialog box is to choose your program type:■ Click Application to test a Java application. Continue by choosing your

program location.■ Click Applet to test an applet. Continue by choosing your program location.■ Click Servlet/JSP to test a servlet or JSP. If this is the first time you have

tested a servlet with Optimizeit, the servlet wizard will start. The wizard will guide you through the servlet configuration; see “Configuring servlet support” on page 90 for more information. Continue by choosing your program location.

■ Click Remote Application to test a Java application that is started from the command line or that is located on another machine.

See also■ “Connecting the audit system” on page 29 for remote testing instructions.

Choosing your program location

What you enter in the location field depends upon what you are testing:■ For an application, Optimizeit expects a Program Main Class Or JAR File:

■ If the application is packaged in a JAR file, click Browse to select the JAR file location.

Note To run an application from a JAR file, the .jar file of the JAR-packaged application must have a manifest file that includes a main-class attribute. See the Sun Microsystems Java web site for more information on JAR-packaged applications.

■ If the application is in a ZIP file, enter the fully qualified name of the class containing the Main method. For example:

com.reg.bar.Main

■ If the application is not in a JAR or ZIP file, click Browse to select the class file that contains the main method.

■ For an applet, Optimizeit expects an Applet HTML File or URL. If the applet is on your local disk, click Browse and select the HTML file. If the applet is a web page, enter the URL of that page.

■ For a servlet, click Browse to choose the class file that contains your servlet.

The Program working directory field is not required; you only use it if your test points to a specific working directory.

10 Prof i ler User ’s Guide


Choosing operation options

The Startup tab contains options to configure the behavior of your test program on startup:■ Pause After Launch pauses the test program just before executing the

main() method. Use this option to give yourself some time to configure Optimizeit or to start recording test information before the tested application starts.

■ VM Cannot Exit disables the method System.exit() in the virtual machine. Use this option to test a command line program such as a compiler that performs a task and then exits the running virtual machine. Use the Stop button to exit the program when your testing session is complete.

■ Enable Audit API enables the Optimizeit Profiler audit system API. When the API is enabled, the Memory Profiler and CPU Profiler are disabled by default. This allows the tested program to use Optimizeit Profiler’s API to precisely enable both profilers when needed.

■ Disable Memory Profiler disables the Optimizeit Profiler Memory Profiler. The Memory Profiler adds overhead that can change the CPU Profiler results. Use this option when you are focusing on CPU-related issues only.

■ Auto-start CPU Profiler starts the CPU Profiler just before executing the main method. The CPU Profiler is started with the current option selected in the CPU Profiler inspector.

■ Open A Console opens a console window for the program when the testing session begins. Use this option if your program expects some input from System.in. When this option is off, anything printed using System.out and System.err is printed in the Optimizeit console.

Choosing extra Java or program parameters

The Extra Java Parameters and Extra Program Parameters fields are optional:■ Extra Java Parameters specifies a string passed directly to the virtual

machine running the test program. Use this field to add Java virtual machine arguments such as -Xms256m or -verbosegc.

■ Extra Program Parameters specifies a string passed directly to the tested application when launched. This option is not applicable for applets.

Choosing your class path and source path

If the application requires special classes not indicated in the default CLASSPATH, click Change under the Class Path window to choose and add the directories, JAR files, or ZIP files containing the extra classes. You can also enter a multi-entry class path, such as c:\classes;d:\project\xmlParser.jar in the empty field. These additions apply only for the current test program.


Using the Fi l ters tab

The Source path lists the directories where Optimizeit will search for source code. If you want Optimizeit to highlight relevant source code, you may need to add your source code directories, ZIP files, or JAR files to the source path. To add or change the source code location, click the Change button to bring up the Source Path Chooser dialog box.

Use this dialog box to add, delete, and organize your source paths. Use the browser to search for a specific directory or file, or use the empty field under the browser if you have a multi-entry source path, such as c:\src;d:\project\src.jar. Enter your full path information into the field. Specific files can also be added later during the testing session. These additions apply only to the current test program.

See also■ By default, the Class Path dialog box contains the default class path as

defined by your CLASSPATH variable. This default can be changed using the Preferences menu; see “Changing the class path” on page 88 for more information.

■ By default, the Source Path dialog box is blank or contains the source path defined using the Preferences menu; see “Setting the source code location” on page 87 for more information.

Using the Filters tabFilters are sets of patterns that define packages, classes, or methods that should be grouped or ignored by Optimizeit when testing an application, an applet, or a remote application. Filters can be applied to the CPU Profiler, the Memory Profiler, method calls, or combinations of these three.

Filters are very convenient for testing servlets, EJBs and JSPs. In that context, they can be used to remove or group in one call the resources used by the application server, allowing you to focus on your Java code.



Optimizeit provides several filters ready to use, including filters dedicated to many application servers. The filters provided by Optimizeit are read-only. You can only modify and delete the filters you have created.

Note Filters only remove information about resources used by code matching the filter pattern. Filters don’t remove information about methods invoked from filtered methods. If a filtered method calls an unfiltered method that allocates an instance, this instance won’t be filtered. If a filtered method invokes a method that consumes CPU time, this CPU time won’t be filtered. For example, you can set the filter for all Jakarta Tomcat objects, but when you read your test results you may still find Jakarta objects if these objects were created by other methods not affected by your filters. You should not see any filtered packages with a red star or clock next to them in a Hotspot or Allocation View.

This section describes how to set up filters for Optimizeit using the Filters tab on the Settings dialog box. Filters are only applicable for Profiler and Code Coverage.

1 Start Optimizeit to open the Edit Settings dialog box by default. If Optimizeit is already started, or opens with a different dialog box:■ Choose File|New Settings to start a new settings file,■ Choose File|Open Settings... or File|Open Recent Settings to locate a

previous settings file to modify, or■ Choose File|Edit Settings... to edit the current configuration.

2 Click the Filters tab on the Settings dialog box to open the Filter Editor:

3 To filter methods, click in the Simplification Type column.

This column has two options, which can be selected by clicking in the Simplification Type column for a filter:



■ Group: select the Group option to condense methods of multiple classes into one single line in your stack trace. To use this option, specify a set of classes to filter and give it a name as an identifier. When you access Profiler backtraces, all calls to the filtered methods are condensed into one entry, labeled with the name you specified. For example, if your unfiltered back trace lists classes such as:

org.apache.catalina.core.x...org.apache.catalina.core.y...org.apache.catalina.core.z...javax.servlet.http...Myservlet...

you can group your Apache classes under the name Apache classes, and the filtered output for the same section shows:

Apache classesjavax.servlet.http...Myservlet...

This is especially useful for servlets.■ Eliminate: select Eliminate to filter these methods from your results. The

code matching this group is ignored, and will not show up in your backtraces. The time spent in this eliminated group will be associated with the caller.

Note The Eliminate simplification type is more efficient than Ignore CPU. Typically, you should select Eliminate for Simplification Type, and not enable Ignore CPU when enabling a filter.

4 To ignore CPU or time usage consumed by Java code matching the filter pattern, click the Ignore CPU column.

Any time spent in the filtered method will be unaccounted for in the backtrace. Ignore CPU is more precise than Eliminate, in that it assigns the correct amount of time spent to the methods in the backtrace, but Eliminate is useful in that all time is accounted for in the backtrace.

5 To enable a filter for the Memory Profiler, click the Ignore Memory column. Optimizeit Profiler ignores object allocations performed by Java code matching the filter pattern.

6 To disable all filters, click the Disable All Filters option.

7 To see the patterns associated with a filter, double-click on the filter in the table or highlight the filter and click Details.

8 When you are done with your filter selection, click on the Virtual Machines or Startup tabs, or click Start Now to begin your test. Click OK if you just want to save your information.

Note If you select more than one filter for a test run, Optimizeit always performs a logical OR of all the filters you have selected. Any top-level package, class, or method that meets any of the filter criteria is filtered.



See also■ “Using the Filter Editor” on page 31 for instructions on using the Filter Editor

executable when testing a remote application. This executable operates outside the Optimizeit user interface.

Creating and editing filters

Although Optimizeit provides filters for several common classes and packages, you can also create and edit your own filters. This must be done before you begin your test program, when you specify the virtual machine you will use for the test. Creating and editing can either be done from within Optimizeit, using the Filters tab, or from the command line, using the Filter Editor executable.

Creating filters

To create a new filter in Optimizeit Profiler:

1 Start the Filter Editor executable. Or, if you are within Optimizeit, choose any of the Settings options from the File menu and click the Filters tab to open the Filter Editor.

2 Click New. The New Filter dialog box opens:

3 Enter the name of your filter in the Name field.

4 Select Any Of The Following Patterns if you want to perform a logic OR between the different patterns of your filter, or click All Of The Following Patterns if you want to perform a logic AND between the different patterns of your filter.



5 To add a pattern, click Add. The Pattern Editor dialog box opens:

6 Enter your pattern in the box. Both the asterisk wildcard character (*) and the not character (!) are supported. Your pattern can define packages, classes, or methods.

7 When you are done with this pattern, click OK.

8 Your pattern appears in the Pattern pane of the New Filter dialog box. You can edit or delete this pattern, or you can continue to add other patterns to this filter.

9 When you have finished with your filter, click OK. Your filter appears at the end of the filter list. User filter names appear in bold, while Optimizeit filter names use regular typeface. By default, Optimizeit will select the column where this filter is most likely to be used.

Editing filters

Once you have created a filter, you can edit or delete it. Before you attempt this, you may want to make sure that the filter is not in use. You cannot edit a filter in use during a test run. Filters must be set before the test program is run, and cannot be modified once the program is running.

To edit a filter:

1 If you are within Optimizeit, choose any of the Settings options from the File menu and click on the Filters tab to open the Filter Editor. If you are outside of Optimizeit, enter editfilter at the command line in your Optimizeit root directory.



2 Click Edit or double-click on the filter in the table. The Filter Editor opens:

Note If you click on an Optimizeit default filter, a View Filter dialog box opens, because you cannot modify these filters.

3 Select Any Of The Following Patterns if you want to perform a logic OR between the different patterns of your filter, or click All Of The Following Patterns if you want to perform a logic AND between the different patterns of your filter.

4 To add a pattern:

a Click Add. The Pattern Editor dialog box opens.

b Enter your pattern. Both the asterisk wildcard character (*) and the not character (!) are supported. Your pattern can define packages, classes, or methods.

c When you are done with this pattern click OK.

5 To change a pattern, select the pattern in the list and click Edit.

6 To delete a pattern, select the pattern in the list and click Delete.

7 When you have finished modifying your filter, click OK.

8 Click on the corresponding column to enable it for the CPU Profiler, Memory Profiler, or Group methods.

Custom filters are part of Optimizeit configuration files. They are saved and loaded when using Save and Open commands from the File menu.


Using the Vir tual Machines tab

Using the Virtual Machines tabAt any time, you can change the virtual machine or add a virtual machine using the Virtual Machines tab on the Settings dialog box:

The main panel lists all of the virtual machines Optimizeit recognizes on this computer.

Adding a virtual machine

To add virtual machines to the list of machines available for Optimizeit:

1 Click Add Virtual Machines. This starts the virtual machine wizard.

2 Click Next.

3 Select the directory where Optimizeit should begin the search for available virtual machines.

4 Click Search. Optimizeit displays the virtual machines found.

5 Click Finish to add these virtual machines to the list of available virtual machines.

Setting virtual machine properties

The Virtual Machine Properties are settings that may or may not be activated, depending upon what type of virtual machine you are using. When you select a virtual machine from the list, Optimizeit only enables the available options for that virtual machine. For example, JRE 1.2 does not have a Hotspot


Using the Vir tual Machines tab

implementation, so the Hotspot option for Java runtime will not be available if you have that JRE selected.

The Java Runtime option sets the virtual machine runtime used. The following table shows which flag is added to the virtual machine invocation:

If you want to use a JIT (Just In Time compiler) when testing, check that option.

If you aren’t sure which options to use, or you want to return to your defaults, click Use Default Settings.

Once you have configured the Settings dialog box to start your application, you can save this configuration in a file when you exit Optimizeit. By default, information from the last-saved settings file is automatically loaded into Optimizeit when you open the program. The same settings file can be used in Optimizeit Profiler, Code Coverage, or Thread Debugger. Use the Save and Open commands on the File menu to save settings files and access existing ones.

Option Flag added Description

Default No flag added The virtual machine uses its default runtime.

Classic -classic Optimizeit forces the virtual machine to use its classic runtime.

Hotspot -hotspot Optimizeit forces the virtual machine to use its Hotspot runtime.

Chapter 3: Running Opt imizei t f rom the command l ine 19

C h a p t e r

Chapter3Running Optimizeit from thecommand line

This chapter describes how to start, run, and configure Optimizeit from outside the Optimizeit user interface. In addition to running your test program from within Optimizeit, you can also run it from a command prompt.

Invoking your application from outside the Optimizeit user interface allows you to do the following:■ Set custom variables■ Run the application as part of a script■ Run the program on a different machine

Starting from the command lineTo test your program from a command prompt:■ Set up the Optimizeit audit system.■ Launch the Optimizeit audit system, specifying your test program.■ Start your selected Optimizeit tool and connect the audit system to the

Optimizeit user interface.

These steps are described in the following sections.


Star t ing from the command l ine

Setting up the audit system

To use the Optimizeit audit system, you need to modify your environment variables to make certain Optimizeit files available on the CLASSPATH and the search path for libraries.

To do this on Windows,

1 Go to the directory where you have Optimizeit installed.

In this example, it is <OptItDir>.

2 Open a command prompt.

3 Set your PATH to include the Optimizeit lib directory:

set PATH=<OptItDir>\lib;%PATH%

4 Set your CLASSPATH to include the Optimizeit optit.jar file:

set CLASSPATH=<OptItDir>\lib\optit.jar;%CLASSPATH%

To do this on UNIX,

1 Enter the directory where you have Optimizeit installed.

In this example, it is <OptItDir>.

2 Open a command prompt.

3 Set your LD_LIBRARY_PATH to include the Optimizeit lib directory:

export LD_LIBRARY_PATH=<OptItDir>/lib:$LD_LIBRARY_PATH

4 Set your CLASSPATH to include the Optimizeit optit.jar file:

export CLASSPATH=<OptItDir>/lib/optit.jar:$CLASSPATH

Launching your program

The Optimizeit audit system is a set of Java classes and native code. There are two methods for launching the audit system: as a command or as a command option.■ To launch the audit system using the command option, use one of the

following arguments:

-Xrunpri:startAudit=t

or

-Xrunpri -Xbootclasspath/a:<OptItdir>\lib\oibcp.jar intuitive.audit.Audit

Either command structure is valid. The first option allows you to append Optimizeit start options directly to the -Xrun command using a colon. You can add more than one option, as long as they are separated by a comma. The second option includes -Xbootclasspath because -Xbootclasspath is a Virtual Machine start option. In an Optimizeit command, the Virtual Machine options must come before the Optimizeit options unless the Optimizeit options have been appended to the -Xrun command with a colon.


Start ing f rom the command l ine

■ To launch the audit system as a separate command, enter the following on the command line:

On Windows:

java intuitive.audit.Audit

On UNIX:

java intuitive.audit.Audit

Note Only use one of these options in a command. If a command contains both startAudit=t and intuitive.audit.Audit, the system returns an error message that the audit system or port is already in use.

If you launch the audit system as a separate command, Optimizeit returns a list of all the audit system start options. The output depends upon your platform and which JDK version you are using. The following tables list all available options.

Windows audit system options

The following tables list the audit system invocation options on Windows platforms. There are two types of start command options: Virtual Machine and Optimizeit. The VM options go before the intuitive.audit.Audit specification in a command, and the Optimizeit options follow the audit system invocation.

Note Some command options are only available on specific JDK versions.

Table 3.1 Windows audit system Virtual Machine start options

Option Description

-classic JDK 1.2 and 1.3 only. Forces Classic runtime.

-hotspot JDK 1.3.1 and 1.4/Hotspot only.

-Xrunpri JDK 1.2 and newer only. Starts the Optimizeit Profiler JVMPI agent. You must also add a filter file specification as shown in the examples below.

-Xrunoii Starts the Optimizeit Suite JVMPI agent. This option is only available if you have Optimizeit Suite installed. All Optimizeit command options, including those that are tool-specific, can be used with -Xrunoii.

-Xbootclasspath/a:<OptItdir>\lib\oibcp.jar

JDK 1.2 and newer only. Appends Optimizeit classes to the boot classes. Replace <OptItdir> with the directory where you installed Optimizeit.

-Djava.compiler=NONE JDK 1.2 only. This option disables the JIT, which is required for JDK version 1.2.

-Xnoclassgc (JDK 1.2 only) With early Java versions, the Optimizeit Profiler audit system must have class garbage collection disabled. Always use the -Xnoclassgc JVM argument when starting an application from the command line.



Table 3.2 Windows audit system Optimizeit start options

Option Description

[-startAudit] [-intuitive.audit.Audit]

Starts the Optimizeit audit system. startAudit=t or intuitive.audit.Audit is required in a command.

[-port portNumber] Specifies the port you want to use for the communication link between the Optimizeit audit system and the Optimizeit user interface.

[-pause] Makes the launched program pause immediately after launch. If set to t, the virtual machine waits for the Optimizeit tool to attach to the tested program before starting it. The default setting is f.

[-wait] Makes the virtual machine wait for Optimizeit Profiler to attach to the tested program before starting it.

[-dmp] Disables the Memory Profiler. This option is for JDK 1.3.1 and greater.

Note: When testing with Hotspot, use -Xrunpri:dmp=1 to disable the Memory Profiler. This improves performance.

[-directi] Uses direct instrumentation. By default, Optimizeit Profiler enables direct instrumentation on supported VMs (JDK 1.4.x). Use directi=t to force Optimizeit to use direct instrumentation (the default) or enter directi=f to turn off direct instrumentation.

[-noexit] Disables the System.exit() method in the virtual machine. This prevents the tested application from exiting the virtual machine. The default is f.

[-filter] Specifies the filter file that Optimizeit will use for this test. The format of the filter specification is filter=<filter>, where <filter> is the name of (and path to) a filter (.oif) file. Filter specifications are required.

[-enableAPI] Enables the audit system API. When the API is enabled, the Optimizeit tools are disabled. The audit system waits for the test program to enable the Optimizeit tool from Java.

[-auditOption] Specifies audit system options that are listed in an ASCII file. The format of the file specification is auditOption=<filename>, where <filename> is the complete path to file containing the audit system options. This file can contain all the Optimizeit audit system options. Only one option is allowed per line. The same option file may be used for different tests.

Note: When this option is used, OISelector settings are overridden.



See also■ “CPU Profiler offline testing options” on page 37 for more information on the

available options.■ “Offline profiling” on page 33 for more information on the available options.

UNIX audit system options

The following tables list all the audit system invocation options on UNIX platforms. There are two types of start command options: Virtual Machine and Optimizeit. The VM options go before the intuitive.audit.Audit specification in a command, and the Optimizeit options follow the audit system invocation.

Note Some command options are only available on specific versions of JDK.

[ClassName] The main class for the test program. If the test program is an applet, use sun.applet.AppletViewer and then add the path of the applet HTML file or URL.

Note: With Code Coverage, you must use oldjava instead of java to run an applet.

[-startCPUprofiler [:<CPUProfilerOptions>]]

Starts the CPU Profiler just before executing the main method. This Optimizeit start option cannot be appended to the -Xrun command with a colon. It must be specified separately.

[-offlineprofiling [:<offlineprofilingOption

s>]]

Starts the testing in offline mode. Snapshots are generated automatically at a given time. This Optimizeit start option cannot be appended to the -Xrun command with a colon. It must be specified separately.

Table 3.2 Windows audit system Optimizeit start options (continued)

Option Description

Table 3.3 UNIX audit system Virtual Machine start options

Option Description

-classic JDK 1.2 and 1.3 only. Forces Classic runtime.

-Xrunpri JDK 1.2 and newer only. Starts the Optimizeit Profiler JVMPI agent. You must also add a filter file specification as shown in the examples below.

-Xrunoii Starts the Optimizeit Suite JVMPI agent. This option is only available if you have Optimizeit Suite installed. All Optimizeit command options, including those that are tool-specific, can be used with -Xrunoii.

-Xbootclasspath/a:<OptItdir>/lib/oibcp.jar

JDK 1.2 and newer only. Appends Optimizeit classes to the boot classes. Replace <OptItdir> with the directory where you installed Optimizeit.



-Xboundthreads JDK 1.3.1 and 1.4/Hotspot on Solaris machines only. This option is used to bind user threads to lightweight process (LWP), required by Profiler.

-Djava.compiler=NONE JDK 1.2 only. This option disables the JIT, which is required for JDK version 1.2.

-Xnoclassgc (JDK 1.2 only) With early Java versions, the Optimizeit Profiler audit system must have class garbage collection disabled. Always use the -Xnoclassgc JVM argument when starting an application from the command line.

-native JDK 1.2 on Solaris platforms only. If your virtual machine uses green threads you should suppress the -native option and add -DOPTITTHR=green and -DOPTITDIR=<OptDir> (where <OptDir> is the directory where you installed Optimizeit). The invocation becomes:

java -native -Xnoclassgc -Djava.compiler=NONE -DOPTITTHR=green -DOPTITDIR=<OptItDir> intuitive.audit.Audit ...

-green JDK 1.2 on Linux platforms only. If your virtual machine uses native threads you should suppress the -green option and add -DOPTITTHR=native and -DOPTITDIR=<OptDir> (where <OptDir> is the directory where you installed Profiler). The invocation becomes:

java -greeen -Xnoclassgc -Djava.compiler=NONE -DOPTITTHR=native -DOPTITDIR=<OptItDir> intuitive.audit.Audit ...

Table 3.4 UNIX audit system Optimizeit start options

Option Description

[-startAudit] [-intuitive.audit.Audit]

Starts the Optimizeit audit system. startAudit=t or intuitive.audit.Audit is required in a command.

[-port portNumber] Specifies the port you want to use for the communication link between the Optimizeit audit system and the Optimizeit user interface.

[-pause] Makes the launched program pause immediately after launch. If set to t, the virtual machine waits for the Optimizeit tool to attach to the tested program before starting it. The default setting is f.

Table 3.3 UNIX audit system Virtual Machine start options (continued)

Option Description



[-wait] Makes the virtual machine wait for Optimizeit Profiler to attach to the tested program before starting it.

[-dmp] Disables the Memory Profiler. This option is for JDK 1.3.1 and greater.

Note: When testing with Hotspot, use -Xrunpri:dmp=1 to disable the Memory Profiler. This improves performance.

[-directi] Uses direct instrumentation. By default, Optimizeit Profiler enables direct instrumentation on supported VMs (JDK 1.4.x). Use directi=t to force Optimizeit to use direct instrumentation (the default) or enter directi=f to turn off direct instrumentation.

[-noexit] Disables the System.exit() method in the virtual machine. This prevents the tested application from exiting the virtual machine. The default is f.

[-filter] Specifies the filter file that Optimizeit will use for this test. The format of the filter specification is filter=<filter>, where <filter> is the name of (and path to) a filter (.oif) file. Filter specifications are required.

[-enableAPI] Enables the audit system API. When the API is enabled, the Optimizeit tools are disabled. The audit system waits for the test program to enable the Optimizeit tool from Java.

[-auditOption] Specifies audit system options that are listed in an ASCII file. The format of the file specification is auditOption=<Path to the file>. This file can contain all the Optimizeit audit system options. Only one option is allowed per line. The same option file may be used for different tests.

Note: When this option is used, OISelector settings are overridden.

ClassName The main class for the test program. If the test program is an applet, use sun.applet.AppletViewer and then add the path of the applet HTML file or URL.

Note: With Code Coverage, you must use oldjava instead of java to run an applet.

[-startCPUprofiler [:<CPUProfilerOptions>]]

Starts the CPU Profiler just before executing the main method. This Optimizeit start option cannot be appended to the -Xrun command with a colon. It must be specified separately.

[-offlineprofiling [:<offlineprofilingOptions>]]

Starts the testing in offline mode. Snapshots are generated automatically at a given time. This Optimizeit start option cannot be appended to the -Xrun command with a colon. It must be specified separately.

Table 3.4 UNIX audit system Optimizeit start options (continued)

Option Description



See also■ “CPU Profiler offline testing options” on page 37 for more information on the

available CPU Profiler options.■ “Offline profiling” on page 33 for more information on the available Memory

Profiler options.■ “Offline profiling” on page 33 for more information on the

auditOption=filename command option.

Optimizeit librariesOptimizeit Profiler contains two libraries to support Java and Java 2 virtual machines:

The audit system automatically detects which virtual machine is used and then selects the matching library. If you want to select a specific library to load, use the -DAUDIT=<libraryType> property, where <libraryType> is 11 or jni.

For example, the following Windows command starts the testing of the SwingSet program and specifies that Profiler will use the Java 2 Universal library:

java -classic -Xrunpri:startAudit=t,filter=<OptItDir>\filters\DefaultAllOn.oif

-DAUDIT=jni -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar SwingSet

Java 2 ExamplesWith JDK 1.2, you can use the following commands to pause the com.busy.BusyApp application immediately after launch.

Note This command uses an alternate way to specify the pause and audit functions, directly after -Xrunpri.■ On Windows:

java -classic -Xrunpri:startAudit=t,filter=<OptItDir>\filters\DefaultAllOn.oif,pause=t -Xnoclassgc -Djava.compiler=NONE -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar com.busy.BusyApp

■ On Solaris:

java -native -Xrunpri:startAudit=t,filter=<OptItDir>/filters/

Name Option Description

Java 2 Universal -DAUDIT=jni This library provides universal virtual machine support. It supports any JDK 1.2 or later virtual machine that is fully JVMPI/JNI compliant. It also supports Just In Time compilers (JIT).



DefaultAllOn.oif,pause=t -Xnoclassgc -Djava.compiler=NONE -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar com.busy.BusyApp

■ On Linux:

java -green -Xrunpri:startAudit=t,filter=<OptItDir>/filters/DefaultAllOn.oif,pause=t -Xnoclassgc -Djava.compiler=NONE -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar com.busy.BusyApp

With JDK 1.3, use the following commands to start the com.busy.BusyApp application with the CPU Profiler automatically started:■ On Windows:

java -classic -Xrunpri:filter=<OptItDir>\filters\DefaultAllOn.oif -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar intuitive.audit.Audit -startCPUprofiler com.busy.BusyApp

■ On Linux:

java -classic -Xrunpri:filter=<OptItDir>/filters/DefaultAllOn.oif -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar intuitive.audit.Audit -startCPUprofiler com.busy.BusyApp

Note The JDK 1.3 Hotspot runtime does not support the profiling API (JVMPI) well. For that reason only the Classic runtime can be used when profiling with JDK 1.3. Use JDK 1.3.1 if you want to test using Hotspot. Because the Solaris version of JDK 1.3 is Hotspot only, Optimizeit does not support JDK 1.3 for Solaris machines.

With JDK 1.3.1, use the following commands to start the com.busy.BusyApp application with the CPU Profiler automatically started and the Memory Profiler disabled:■ On Windows:

java -Xrunpri:filter=<OptItDir>\filters\DefaultAllOn.oif -Xbootclasspath/p:<OptItDir>\lib\bootcp\oibcp.jar intuitive.audit.Audit -startCPUprofiler com.busy.BusyApp

■ On Solaris:

java -Xrunpri:filter=<OptItDir>/filters/DefaultAllOn.oif,dmp=1 -Xboundthreads -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar intuitive.audit.Audit -dmp -startCPUprofiler com.busy.BusyApp

■ On Linux:

java -Xrunpri:filter=<OptItDir>/filters/DefaultAllOn.oif,dmp=1 -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar intuitive.audit.Audit -dmp -startCPUprofiler com.busy.BusyApp



Note To focus on the CPU testing, you can reduce testing overhead by disabling the Memory Profiler. To disable the Memory Profiler, change the -Xrunpri parameter to -Xrunpri:dmp=1 and specify the -dmp option to the audit system. This option is for JDK 1.3.1 and greater.

Using Profiler with the Hotspot runtime

When you use Optimizeit Profiler with the Java Hotspot VM, Profiler requires a custom set of classes to be added to the default bootstrap class path (bootclasspath) for the Application Quality Analyzer to provide complete error reporting. The classes used are dependent upon the VM. When you use the Profiler user interface to start an application for testing, whether or not you specify the Java Hotspot runtime for your virtual machine, Profiler automatically creates a JAR file containing the needed classes to use for the bootclasspath. The JAR file, oibcp_<vm_version>.jar (where <vm_version> is the version for the virtual machine), created in the <OptItDir>/lib/bootcp directory. Custom JAR files are for use with Java Hotspot VMs only, and need to be created just one time. Once a custom JAR file is created for a specific VM, it can be reused.

Optimizeit Profiler comes with a utility for creating custom bootclasspath JAR files from the command line. When you use Optimizeit Profiler from the command line, using the Java Hotspot runtime, you must add the custom bootclasspath JAR file, oibcp_<vm_version>.jar, to the beginning of the bootclasspath. The following sections, describe how to create a custom bootclasspath JAR file from the command line, and how to add the custom JAR file to the bootclasspath.

Note The use of the custom bootclasspath JAR file for Hotspot VMs applies to Optimizeit Profiler only. Although the Quality Analyzer will not report some errors, you can still use Profiler with the Hotspot VM and the standard Optimizeit bootclasspath JAR file, oibcp.jar in the <OptItDir>/lib directory. Creating and using a custom bootclasspath JAR file is not necessary if the Memory Profiler is disabled or not used, or if you are not focusing on the output of the Quality Analyzer.

Creating a custom JAR for the bootclasspathThe makeBootCP script in the root directory of your Optimizeit installation lets you generate a custom JAR file containing the classes that should be added to the bootclasspath when you use Optimizeit Profiler with the Hotspot VM. If you have already generated a custom bootclasspath JAR file for your VM with the Optimizeit Profiler user interface, there is no need to use the makeBootCP script file.

To generate a custom bootclasspath JAR file from the command line, enter the following command:

makeBootCP <jdk>

where <jdk> is the path to your Java virtual machine. For example, the command might look like:



makeBootCP /jdk1.4.0_02

The custom JAR file is created in the <OptItDir>/lib/bootcp directory.

Setting the bootclasspath for Hotspot VMsOnce Optimizeit Profiler has generated a custom JAR file for the bootclasspath, you must set the bootclasspath on the command line in the following way:

Note The /p option in the following examples specifies that the custom JAR file be prepended in front of the default bootstrap class path.■ On Windows:

java -hotspot -Xrunpri:filter=<OptItDir>\filters\DefaultAllOn.oif -Xbootclasspath/p:<OptItDir>\lib\bootcp\oibcp_<version_num>.jar intuitive.audit.Audit -startCPUprofiler com.busy.BusyApp

■ On Solaris:

java -hotspot -Xrunpri:filter=<OptItDir>/filters/DefaultAllOn.oif -Xboundthreads -Xbootclasspath/p:<OptItDir>/lib/bootcp/oibcp_<version_num>.jar intuitive.audit.Audit -startCPUprofiler com.busy.BusyApp

■ On Linux:

java -hotspot -Xrunpri:filter=<OptItDir>/filters/DefaultAllOn.oif -Xbootclasspath/p:<OptItDir>/lib/bootcp/oibcp_<version_num>.jar intuitive.audit.Audit -startCPUprofiler com.busy.BusyApp

Connecting the audit system

Once the test program is running, you need to direct the audit system results to the Optimizeit user interface. This procedure is called attaching Optimizeit to the test program.

To show the audit system results:

1 In Optimizeit, choose File|New.

2 In the Settings dialog box, click Remote Application in the Program Type section.


Star t ing on a d i f ferent machine

The Remote Application dialog box opens:

3 In the Host Name field, type either:■ localhost

■ The name of your local host■ The name of the machine where the audit system is running■ The IP address of the machine where the audit system is running

4 In the Port Number field, enter the port number you want to use for the communication link between Optimizeit and the audit system.

Change the default value only if you used the port option when launching the test program.

5 To show relevant source code not found in the default source path, click Change under the Source Path list to locate and add directories or JAR files containing the additional source files.

Specific files can be added later during the testing session.

6 Click Attach Now.

Once you configure your test program, you can attach to the audit system by choosing Program|Attach.

Starting on a different machineTesting a Java program running on a different machine is similar to testing a Java program started from the command line:


Using the Fi l ter Edi tor

1 Set up the Optimizeit audit system, as described in “Setting up the audit system” on page 20.

2 Launch the Optimizeit audit system, specifying your test program, as described in “Launching your program” on page 20.

3 Start your selected Optimizeit tool and connect the audit system to the Optimizeit user interface using Remote Application as the Program type, as described in “Connecting the audit system” on page 29.

4 In the Host Name field, enter the name of the machine running the test program.

5 Click OK when you have finished entering your test information in the Settings dialog box.

6 Choose Program|Attach to attach Optimizeit to the test program.

Using the Filter EditorFilters must be specified before you run your test program, when you specify your virtual machine. For this reason, Optimizeit has command-line functions to create, modify, and specify filters from outside of Optimizeit. This is required when you are testing a remote application.

The Optimizeit Filter Editor creates and edits filter files for use in remote and offline (batch) testing. These filter files, which use a .oif extension, are specified in an Optimizeit command.

Because it is used for both Profiler and Code Coverage, the Filter Editor dialog box has columns for both Profiler and Code Coverage filter operations. Only one column, Ignore Coverage, is applicable for Code Coverage testing. Ignore Coverage combines the two Code Coverage filter options, Include Class and Exclude Class, into one column.

To use this program:

1 Make sure you have integrated with an application server and chosen your virtual machine.

2 Start the Filter Editor:■ If you are on a UNIX machine, go to your root Optimizeit directory and

enter ./Editfilter.sh at the command prompt.■ If you are on a Windows machine, select the Optimizeit Filter Editor from

your Optimizeit program menu, or double-click on the Filter Editor executable icon in your Optimizeit root directory.


Using the Fi l ter Edi tor

3 The Filter Editor opens:

Click New to create a filter, or double-click on one of your filters to edit that filter. You can also choose an existing filter from the Filter Editor File|Open command to use as a starting point.

4 Check the applicable column(s) for your filter:■ To filter methods, click in the Simplification Type column.

This column has two options:■ Group: select the Group option to condense methods of multiple

classes into one single line in your stack trace. To use this option, specify a set of classes to filter and give it a name as an identifier. When you access the stack trace, all calls to the filtered methods are condensed into one entry, labeled with the name you specified.

For example, if your unfiltered back trace lists classes such as:

org.apache.catalina.core.x...org.apache.catalina.core.y...org.apache.catalina.core.z...javax.servlet.http...Myservlet...

you can group your Apache classes under the name Apache classes, and the filtered output for the same section shows:

Apache classesjavax.servlet.http...Myservlet...

This is especially useful for servlets.■ Eliminate: select Eliminate to filter these methods from your results.

The code matching this group is ignored, and will not show up in your


Off l ine prof i l ing

backtraces. The time spent in this eliminated group will be associated with the caller.

Note The Eliminate simplification type is more efficient than Ignore CPU. Typically, you should select Eliminate for Simplification Type, and not enable Ignore CPU when enabling a filter.

■ To ignore CPU or time usage consumed by Java code matching the filter pattern, click the Ignore CPU column.

Any time spent in the filtered method will be unaccounted for in the backtrace. Ignore CPU is more precise than Eliminate, in that it assigns the correct amount of time spent to the methods in the backtrace, but Eliminate is useful in that all time is accounted for in the backtrace.

■ To enable a filter for the Memory Profiler, click the Ignore Memory column. Optimizeit Profiler ignores object allocations performed by Java code matching the filter pattern.

■ To enable a filter for a Code Coverage class, click the Ignore Coverage column. This filter excludes a class from testing.

If you want the reverse (the equivalent of the Include Coverage filter option in Code Coverage) use the not (!) character.

5 To see the patterns associated with a filter, double-click on the filter in the table or highlight the filter and click Details.

6 Make your selections and chose the Filter Editor’s File|Save option to save your filter file. This creates an .oif file that can be accessed by command-line test runs.

Custom filters are part of Optimizeit configuration files. They are saved and loaded when using Save and Open commands from the File menu.

Note If you select more than one filter for a test run, Optimizeit always performs a logical OR of all the filters you have selected. Any top-level package, class, or method that meets any of the filter criteria is filtered.

You can also create and edit filters in the Filter Editor. For information on how to create and edit filters, see “Creating and editing filters” on page 14.

Offline profilingYou can start a testing session from the command line and automatically generate snapshots at fixed intervals. Reload the captured snapshots in Optimizeit Profiler for later analysis. This allows you to test an application server over a long period, or in a production environment. Offline testing also limits overhead because you do not attach to the application.

By default, the Optimizeit CPU Profiler is only started when triggered from within the Profiler user interface. Use offline profiling to start the CPU Profiler automatically before the tested program is started.

If you have integrated with an application server, your application server must support start-up with a script file or by command line to use offline profiling. If



the JVM is started by the application server, then you will not be able to add in the offline profiling startup parameters. For example, offline profiling is not possible with the iPlanet Web Server 6.0.

Note You cannot attach Optimizeit Profiler to an audit system configured for offline profiling.

To start offline testing, you must start your application from the command line. There are two Optimizeit command choices:■ -offlineprofiling: (for Memory Profiler) and/or -startCPUprofiler (for CPU

Profiler) followed by your selected offline testing options■ auditOption= followed by a filename

The auditOption file is an ASCII file containing your selected offline testing parameters. For example:

Using an auditOption file is the preferred method for offline testing commands. Files can be used, re-used, tracked, and shared, and it is easier to change and track command parameters.

Each offline profiling option and its value must be separated with an equals character (=). The options are separated by commas (,). No spaces should be used, or line breaks. The values of the directory and comments options may contain spaces. In that case, make sure to include the values between doublequotes (" "). In the auditOption file, each command option, such as -offlineprofiling, -port, and -startCPUprofiler must go on a separate line.

Note Optimizeit start options (such as port, in the above example) can be included in auditOption files. Optimizeit VM start options, such as -Xrunpri or -Xbootclasspath, cannot be included. Each option must be placed on a separate line in the file. The port option is unique. The portnumber requires a space, so the port option is entered on one line, the portnumber is entered on the line below, and the next option is entered on the following line.



Memory Profiler offline testing options

The following table describes the offline testing options for Memory Profiler:

Option Values Description

onExit [true,false] If true, saves a snapshot when the application exits. This option is not compatible with the noexit audit system Start option.

initialDelay [0....(s,m,h)] The delay before the generation of the first snapshot. The time unit is specified just after the value, with h for hours and m for minutes. For example, initialDelay=2h sets the initial delay to 2 hours. By default, Optimizeit uses the value of the delay option.

delay [1...(s,m,h)] The delay between the generation of two snapshots, measured in seconds by default. The time unit is specified just after the value, with h for hours and m for minutes. For example, delay=10 sets the delay at ten seconds.

counter [1...] The number of snapshots to be generated. If you do not set this option, the number of snapshots generated is unlimited.

directory [validDirectoryName] The directory where the snapshots are generated. By default, snapshots are generated in the current directory.

filename [fileName] The name used for the snapshots. If no filename is specified, the filename is constructed from the main class name.

updateFile [true,false] Reuses the same snapshot file. If true, only one file is used for all the snapshots and the preceding snapshot is overwritten each time a new snapshot is generated.

appendTime [true,false] Appends the date and time of the snapshot generation to the end of the filename. This value is true by default. If false, a counter is used to differentiate the different snapshot files.



ExamplesOn JDK 1.3.0 and later, the following command starts the testing of BusyApp. A snapshot is regenerated every 5 minutes in the current directory, using the filename test.snp. The CPU information is included. This example uses an auditOption file. Although the example is in Windows, the UNIX version is similar.

java -Xrunpri:filter=<filtername>.oif,auditOption=optionfile.txt -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar BusyApp

The auditOption file for this command:

Note The auditOption file does not contain the application name (in this case, BusyApp). This means that the same auditOption file can be used with any tested program.

includeCPU [true,false] Stores CPU test information in the snapshot. If this value is true and the CPU Profiler is not automatically started, it starts the CPU Profiler with the default options. See “CPU Profiler offline testing options” on page 37 for more information.

includeMemory [true,false] Stores the Memory Profiler heap and backtrace information in the snapshot. The value is true by default.

includeReferences [true,false] Stores the Memory Profiler reference graph (and reference from roots with JDK 1.2 and later) in the snapshot. The value is false by default.

Note

The amount of data to be stored for the reference mode is important. The snapshots generated with this option are larger files and take more time to be generated. Only select this option when you really need the reference mode information.

comment [yourTextHere] String used to add comments to the snapshot.



Start ing from the test program

CPU Profiler offline testing options

The following table describes the CPU Profiler offline testing options. These options are similar to the CPU Profiler options accessible from within Optimizeit Profiler. See “Using the CPU Profiler” on page 61 for more information.

Starting from the test programIn some environments, the Java virtual machine is started automatically. The Optimizeit audit system can be invoked from the test program using the Profiler or Code Coverage application programming interface (API). To invoke Optimizeit from inside your test program:

1 Set up the Optimizeit audit system, as described in “Setting up the audit system” on page 20.

This is done in exactly the same way for all command-line or batch testing.


type [sampler, instrumentation]

Type of CPU profiler used. The default is Sampler.

Note: Instrumentation is only available with JDK 1.2 or newer.

displayPrecision [method,line] Sets the precision of the sampler. This option is only active with type=sampler. The default is method.

samplingPeriod [1..1000] Sets the sampling period (in milliseconds) of the sampler. This option is only active with type=sampler. The default is 50 ms.

onlyCPU [true,false] If true, only the pure CPU usage is taken into account. The default is false.

precision [micro,milli] Controls wether the profiler has microsecond or millisecond precision. This option is only active with type=instrumentation. The default is milli.

filterEnabled [true,false] If true, methods executed in less than the delay specified by the filterDelay property are excluded. This option is only active with type=instrumentation. The default is false.

filterDelay [0..1000] Sets the delay, in milliseconds, of the filter used to exclude short methods. This option is only active with type=instrumentation and filterEnabled=true. The default is 100.


Star t ing from the test program

2 Add API calls in your program, as described in “Adding API calls in your program” on page 38.

3 Launch the Optimizeit audit system, specifying your test program, as described in “Starting your test program” on page 38.

4 Start your selected Optimizeit tool and connect the audit system to the Optimizeit user interface using Remote Application as the Program type, as described in “Connecting the audit system” on page 29.

5 In the Host Name field, enter the name of the machine running the test program.

6 Click OK when you have finished entering your test information in the Settings dialog box.

7 Choose Program|Attach to attach Optimizeit to the test program.

Adding API calls in your program

The following example shows how to start the Optimizeit Profiler audit system from Java code.

import intuitive.audit.Audit;

void startAuditSystem() {/** Start the Optimizeit audit system with some default options **/Audit.start(1470, Audit.DEFAULT_OPTIONS);}

/** Note: after starting the audit system, you need to start the profilers by using Audit.enableProfiler(). If you want the profilers to be enabled all the time, change the option in Audit.start() from Audit.DEFAULT_OPTIONS to Audit.PROFILERS_ALWAYS_ENABLED **/

Once the Profiler audit system has been started, Optimizeit Profiler starts retrieving the test information when the Java code is executed.

See also■ For more information about Optimizeit Profiler Audit API, read the online

API reference documentation.

Starting your test program

Although the test program starts the audit system, extra parameters need to be added to the code or to the shell script that starts the virtual machine.

With JDK 1.2, you must use the following options:■ disable class garbage collection■ start the profiling interface (Xrunpri)


Start ing from the test program

■ enable the audit system■ specify a filter■ enable the API■ disable the JIT■ disable Hotspot■ set the bootclasspath

For example, on Windows:

java -native -classic -Xnoclassgc -Xrunpri:startAudit=t,filter=<OptItDir>/filters/filtername.oif, enableAPI=t -Djava.compiler=NONE -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar TestProgram

With JDK 1.3, you must use the following options:■ select the classic runtime■ start the profiling interface (Xrunpri)■ enable the audit system■ specify a filter■ enable the API■ set the bootclasspath

For example, on Linux:

java -native -classic -Xrunpri:startAudit=t,filter=<OptItDir>/filters/filtername.oif, enableAPI=t -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar TestProgram

With JDK 1.3.1 and 1.4, you must use the following options:■ start the pri profiling interface■ enable the audit system■ specify a filter■ enable the API■ set the bootclasspath■ set boundthreads (on Solaris platforms)■ set classic runtime (you cannot use Hotspot because of some JVMPI bugs)

For example, on Windows:

java -Xrunpri:startAudit=t,filter=<OptItDir>\filters\filtername.oif, enableAPI=t -Xbootclasspath/a:<OptItDir>\lib\oibcp.jar TestProgram

For example, on Solaris:

java -classic -Xrunpri:startAudit=t,filter=<OptItDir>/filters/filtername.oif, enableAPI=t -Xboundthreads -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar TestProgram


Chapter 4: Using the Memory Prof i ler 41

C h a p t e r

Chapter 4Using the Memory ProfilerThe Memory Profiler provides information about the objects allocated by your Java program. It displays all allocated instances in real time, and allows you to see precisely which method is responsible for object allocations. The Memory Profiler also allows you to browse incoming and outgoing object references.

Use Memory Profiler to improve the performance of your program:■ Minimize temporary object allocations. Excessive temporary object

allocations can cause the garbage collector to run every few seconds. When running, the garbage collector slows down your Java program.

■ Minimize the number of instances required for a given operation, and therefore decrease the memory your program requires.

■ Reduce memory waste by making sure every object is garbage collected.

By default when your program is started, Optimizeit opens the Memory Profiler. To return to Memory Profiler from the CPU Profiler or any other mode, click Memory.


Memory Prof i ler modes

Memory Profiler modesThe Memory Profiler provides several different views into the test information. Switch between these views, or modes, using the buttons in the toolbar:

Controlling the test programThe Optimizeit tool bar provides the following buttons to control the test program run:

By default the Memory Profiler opens in the Heap view, which displays all classes and the number of instances currently allocated for each. For more information, see “Using the heap view” on page 43.

The Allocation Backtrace view shows the methods involved in object allocation for a class selected in Heap mode. For more information, see “Using allocation backtraces” on page 45.

The Instance Display view shows the incoming, outgoing, or, for Java 2, reduced references of a given instance. Incoming references are references from an object to the selected object. Outgoing references are references from the selected object to other objects. Reduced references are a transitive closure of the full reference graph. See “Viewing instances and reference graphs” on page 50 for more information.

The Memory Leak Detector lets you compare different heap states. See “Using the Memory Leak Detector” on page 54 for more information. This feature is only available for Java 2 machines.

The Reference from roots mode shows the entire content of the heap so you can view the hierarchy between different objects. These objects include busy monitors, variables, constants, and Java threads. For more information, see “Browsing references from roots” on page 56. This feature is only available for Java 2 machines.

Starts or resumes the test program. This control is red when the test program is running.

Pauses or resumes the test program. Use this button when it is necessary to freeze the flow of execution to better study the interaction between different parts of the tested program.

Stops testing. If you are running your test program from within the Profiler user interface, the program will stop and the test will end. If you are connected to a remote server, and the test program is running on the remote machine, stop will just disconnect your Profiler user interface; the test program itself will keep running on the remote server.


Using the heap view

Using the heap viewBy default when your program is started, Optimizeit appears in the Heap mode, displaying all classes and the number of instances currently allocated:

To sort the values in a column of the table, click the column header.

The filter box on the bottom of the window allows you to select the classes that you want to view. The classes that you exclude will still be tested, but Optimizeit will not show them in the Heap mode. This is different from the filters you set when you specify the virtual machine, before the test is run; those filters determine what will be tested. The filter box on the Heap mode window determines what, of the test results, is shown.

For example, to only see AWT classes, enter:

java.awt.*

Both the asterisk wildcard character (*) and the not (!) are supported. It is possible to enumerate more than one pattern using a comma (,) separator. For example, to see all classes matching image except java.awt.Image classes, enter:

*image*, !java.awt.Image*

To see all tested classes, clear the filter completely, or enter an asterisk (*).

Click the Disable garbage collector option to study object allocations without having the garbage collector remove instances. The garbage collector is not


Using the heap view

really disabled; however, the heap mode shows you what would happen if the garbage collector was not running.

Right-click on any row in the heap table to bring up a shortcut:

■ Show Allocation Locations opens the Allocation Backtrace view for the entry in the highlighted row.

■ Show Instances opens the Instance Display for the entry in the highlighted row.

At the bottom of the heap table is a Total row:

The Total row shows the total size or count for all classes in the Heap views. Select this row and click on Allocation Backtrace to view the allocation backtrace data for all classes. If you use a filter, the total is for all classes matching the selection.

Select the total row and click on Show Instances and Reference Graphs to view the current instances of all objects.

You can also click Garbage Collector to force the garbage collector to run immediately.

Click Mark to mark the current instance count. A mark appears on the red bar for each row item. This mark represents the number of instances allocated at the time you set the mark. The time difference in the Diff column is then set to zero for all classes. The mark allows you to see the instances allocated by a specific action in your program. For example, if you are testing a Swing application, click Mark, then open one of the test program dialog boxes. Click the Diff column header to sort the column so you can see the instances allocated when the dialog box was created. The Allocation Backtrace and Instance Display modes also display information relative to a mark.


Using al locat ion backtraces

Heap mode inspector options

The Inspector dialog box provides the following options to refine the Heap mode display:

Using allocation backtracesAfter you have identified a class with an excessive number of instances, the next step is to identify the code or the part of the program that is responsible for these allocations. In Heap mode, select the line displaying the class you want to focus on, and click Allocation Backtrace. Optimizeit switches to

Option Description

Always sorted Sorts the display in real time. Use this option to keep track of specific object allocations while the test program is running.

Classes without instances Displays all classes in the class list, including classes that currently have no allocated instances.

Show sizes Adds total memory (Size) and changed memory (Size Difference) columns to the table. The Size column displays the memory required by all instances of each class. The Size Difference column shows the memory size difference since the last time a mark was set.

Note: The displayed memory size is the shallow size of the object. This size only includes size of the memory required for the instance and does not include the size of objects retained by the instance.

Show freed instances Adds freed object count and freed object count difference columns in the main display. Use this option to understand performance issues related to the allocation of too many temporary objects.

Relative difference sorting By default differences are sorted by absolute value. Use the option to sort by relative differences.



Allocation Backtrace mode to display the code responsible for the selected class object allocations:

The top pane in Allocation Backtrace displays calls from the first method of the Java program to where allocations occur. This view helps you understand which feature of your program is responsible for object allocations. By opening nodes in this view, you can see precisely where allocations originate. Any line with an allocation icon is a line that is responsible for one or more object allocations.

By default, instances are sorted by allocation, with the most recently allocated instances at the top of the table. The top rows of the table may be populated with unknown, unresolved allocations. Click on the Alloc Order column header to view instances last-to-first.

The bottom pane displays the names of methods responsible for object allocations. This view shows which methods perform excessive allocations.

Click Reverse Display to reverse the lists. This shows backtraces from the place where the allocations take place to the Main method of the Java program. This view can be useful when you need to focus on methods or lines of code responsible for object allocations rather than broad features of your program. This option is not applicable for the Aggregated view - Graph mode.

To display the code corresponding to a line in the top or bottom sections of the window, select the line, then click Source Code. You can also double-click the line to show the source code. For more information, see “Viewing source code” on page 82.

The two buttons at the top left corner of the bottom pane allow you to choose a view for your data: Hierarchical view - Tree, or Aggregated view - Graph.



Hierarchical view - Tree is the default. In tree views, a particular method may appear in multiple places, depending upon who calls the method and where, but in the graph view, the node denoting that particular method appears only once. It can still have multiple parents.

In the Aggregated view - Graph mode, a node will have incoming lines, or edges, from multiple nodes, each corresponding to a method that calls this method. Unlike trees, a graph can have loops. The graphic display can help you trace resources. If you want to find out who a statement calls, then the graphic structure is a quick and easy way to navigate through the connections between a parent statement and its multiple children.

When you choose the graph display, a graphical representation of the stack trace appears. Each call is shown in a square node. If you place your cursor over the node, Profiler shows a summary of the objects allocated for the node:

At the top of the graph are two sliders:■ Use the Detail Level slider to raise and lower the level of detail in the graph;

the further to the right you move the slider, the more detail, in terms of nodes and connections, is displayed.

■ Use the Zoom slider to make the nodes and edges in the graph larger or smaller. Zoom does not affect what is contained in the graph; you can move the slider to the left until there is no more room on the node for text, but the node will not disappear.

All colors have a specific meaning:■ Blue nodes are callers; they do not allocate objects directly, but they call

other nodes/methods that do.■ Red nodes are allocators; they create objects.



■ The more objects a node creates, the darker (or, more saturated) the color. The edges attached to the node also become larger as more objects are allocated in and under the node.

■ As fewer objects are allocated, the nodes become lighter in color, until they become gray or tan in color and move towards the bottom of the graph. There is less difference, at this point, between callers and allocators.

■ Backward calls are shown with green edges. A backward call is a call made to a node higher up in the stack trace hierarchy. All forward calls are shown with blue edges; a forward call is a call made to a node lower in the stack trace hierarchy.

■ Simplified invocation sequences are shown with yellow/orange edges. These edges indicate that there are more calls between the nodes, but that these in-between calls are considered unimportant and so aren’t being shown. In some cases, you can use the Detail slider to increase the graph detail and reveal these hidden calls. When this happens, the edges will change to blue.

■ When a node is selected, the edges connecting that node to its parent and all its ancestors (all the way to the beginning of the graph) will flash.

Allocation Backtrace inspector options

The Inspector dialog box provides options to refine the Allocation Backtrace display. To open the Inspector dialog box, click Inspector:

The Inspector dialog box contains the following options for Allocation Backtrace:

Option Description

Show allocations since mark

Displays only the backtrace for the methods responsible for allocating instances since the last time you pressed the Mark button in Heap mode.

Note: If this option is checked and no objects have been created since the last time you set a Mark, then there is no data for that class in the view.



Tracking temporary object allocations

Excessive temporary object allocations are often a source of performance problems in Java programs. Although allocating an object is a fast operation on most Java virtual machines, excessive temporary objects keep the garbage collector busy. Running the garbage collector can block the Java program for as much as a couple hundred milliseconds. If the garbage collector has to run very often, these interruptions cause the Java program to appear slow to the user.

To track down excessive temporary object allocations in Memory Profiler:

Precision By default, graphs show test results by method; changing the granularity allows you to organize the graph by line of code.

Type By default, the bottom pane has a column showing the Allocation count and the percentage of the total count held by this object. You can also choose to organize and display objects by Allocation size, where the percentage value is related to the total size of the object. Allocation size is especially useful in identifying large integer arrays, which may go unnoticed in a table sorted by count.

1 Click Heap. Click the Instance Count column header to sort the display.

2 Exercise your program, noting the classes that show quick changes in their number of instances. Select one of these classes.

3 Click Garbage Collector to free current temporary objects.

4 Click Mark to place a mark on the currently allocated instance.

5 Exercise your program again to recreate the problem. This time the garbage collector is disabled and the number of instances does not decrease.

6 Click Allocation Backtrace.

7 Click Inspector.

8 Choose Since last mark to only display newly allocated objects. The Allocation Backtrace mode displays the code responsible for the allocations.

Option Description


Viewing instances and reference graphs

After you have identified which line of code or API is responsible for all these objects, change your program so it uses different APIs or reuses the same objects.

Viewing instances and reference graphsIn a development environment that has no garbage collector, a program that does not free the allocated memory loses this memory, creating a memory leak. With Java’s garbage collector, it is no longer necessary for programmers to keep track of allocated objects and free them explicitly when they are no longer required.

However, it is quite common for a Java program to keep some references to some objects that are not really necessary anymore. For example, a Java program displays a large splash screen only at startup. If a static variable somewhere references an object with a hashtable that references the splash screen image, the image will never be garbage collected because it is still accessible from the Java program. Thus, the program requires more resources than necessary to maintain the splash screen image.

To solve these kinds of problems, Optimizeit Profiler provides an Instance Display mode. This mode displays all instances of a given class and their incoming and outgoing references. Incoming references are references from an object to the selected object. Outgoing references are references from the selected object to other objects.

To switch to Instance Display mode, click Instance:

■ The top pane displays the string representations of the selected class instances. By default, instances are sorted by allocation, with the most recently allocated instances on top. You can click on the Alloc order column header to toggle the sort between first-to-last or last-to-first. The Retained size column shows the amount of memory that would be reclaimed if the



object was freed. You can click on this column header to sort the instances by size; click on any column header to sort by the information in that column. The Inspector options allow you to add/remove columns; see “Instance Display inspector options” on page 53 for more information.

The string representations are obtained by calling the method toString() on each object. By implementing useful toString() methods in your classes you can use this view to identify the currently allocated instances. By default, the length of a string representation is limited to 140 characters. To set a larger string size, change the Object Representation Maximum Size on the Miscellaneous dialog box from the Edit|Preferences menu.

■ The middle pane displays the objects that are referenced by the object selected in the top view. When available, the instance variable that references the object is in bold. By clicking on the pane header, you can also view outgoing references or, with Java 2, reduced references. If a cycle is found in the graph, the point where the cycle occurs is displayed with the icon.

■ The bottom pane lists where the object highlighted in the middle pane graph is allocated.

Outgoing reference graph

Optimizeit Profiler can also display outgoing references. To display outgoing references, click the reference graph pane header, and then choose Outgoing:

The middle pane displays objects referenced by the object selected in the top view. Icons indicate the meaning of each line:

Instance variables

Instances



To display the code corresponding to a line in the middle or bottom panes of the window, select the line, then click Source Code. You can also double click the line to show the source code. For more information, see “Viewing source code” on page 82.

Reduced reference graph

With JDK versions 1.2 and newer, Optimizeit Profiler provides a reduced reference graph, the transitive closure of the full reference graph. If an object A is referenced by B and D, and if D also references B, the reference D->A won’t be displayed. This mode helps you discover which reference should be removed to allow the selected object to be garbage collected. All displayed references are references preventing the object from being garbage collected.

To open the reduced reference graph, click the reference graph pane header and choose Reduced:

Note If available with your JDK, reduced reference graph is the default for the middle pane.



Instance Display inspector options

The Inspector dialog box provides options to refine the Instance Display mode display. To open the Inspector dialog box, click Inspector:

The Inspector dialog box contains the following options for Instance Display:

Option Description

Show allocations since last mark

Displays only the instances that have been allocated since the last time you pressed the Mark button in Heap mode.

Note: If this option is checked and no instances have been allocated since the last time you set a Mark, then there is no data for that class in the view.

Show allocation points Creates a column showing exactly which method the object is allocated at. The difference between this option and the bottom pane is that the bottom pane is a stack trace, but this option creates an Allocated At column that you can sort by clicking the column header.

Show sizes Creates a column showing the default size of the basic object and its references; in other words, the shallow size of the object. This is most useful for character arrays.

Show retained sizes Creates a column showing the combined size of the object plus its referenced objects, unless those objects are referenced by something else. This is the amount of memory that would be garbage collected if you deleted this object.

Show reach sizes Creates a column showing the combined size of this object and all its referenced objects; in other words, the full or deep size of the objects. In the case of circular references, the reference is counted, but the referenced object is only counted once.

Reference graph type Lets you choose the type of graph displayed, incoming, outgoing, or reduced.

Note: Selecting graph from here is similar to selecting by clicking the graph type column header on the Instance Display center panel.


Using the Memory Leak Detector

Note By default, Optimizeit hides finalizer, weak, and other referent references. The only way to see all the references to the objects being held is by selecting the reference Inspector options.

Using the Memory Leak DetectorMemory leaks are often caused by objects that continue to be referenced as the processes continue, so they are still using resources. Because of this, if you can locate an object with lots of references, you can often locate the source of a memory leak near that object. To locate objects with large amounts of references, and trace those references, open the Memory Leak Detector:

To search for potential memory leaks, Profiler needs a set of heap states to compare. To create a new heap state, click Save Heap, and perform an action or actions with your application. You can then click Save Heap again to

Include soft references Includes soft references, which are garbage collected only when memory is low, in the object graph. Checked by default.

Include weak references Includes weak references, which are garbage collected even if memory is abundant, in the object graph.

Include phantom references

Includes phantom references, which are references pointing to objects that are dead and have been finalized, in the object graph.

Include finalizer references

Includes finalizer references, which are references waiting in the finalizer queue to be garbage collected, in the object graph.

Option Description


Using the Memory Leak Detector

generate a new heap state. You can create as many heap states as you like, and can then set your comparison (between heap states one and two, or between heap states 3-6) by highlighting the heap information in the top pane.

Once you have set your comparison, the middle pane fills with the sources of new references that have been created between your selected heap states. The count value is the number of new references recursively contained by this object. If you sort by count, the most likely sources of memory leaks appear at the top of the table. You can select a reference to see a graph showing all of the references connecting this object to the other objects in the heap state:

The object will have incoming lines, or edges, from multiple nodes, each corresponding to a reference. If you place your cursor over a node, Profiler shows the number of new references and the toString() representation for that node. If you place your cursor on an edge, Profiler displays the instance variable for this reference.

Note By default, the length of a toString() string representation is limited to 140 characters. To set a larger string size, change the Object Representation Maximum Size on the Miscellaneous dialog box from the Edit|Preferences menu.





Browsing references from roots

All colors have a specific meaning:■ Blue nodes are indirect reference holders; they do not have new direct

references, but they reference other objects that do (an indirect reference).■ Red nodes are reference holders; they have new direct references.■ The more new references a node has, the darker (more saturated) the

color. The edges attached to the node also become larger.■ Backward links are shown with green edges. A backward link is a reference

to an object higher up in the reference hierarchy. All forward links are shown with blue edges; a forward link is a reference to an object lower in the reference hierarchy.

■ When a node is selected, the edges connecting that node to its references will flash.

Highlight any selection, and click your right mouse button. Profiler opens the selection in the Instance Display mode. This mode displays all instances of a given class and their incoming and outgoing references, so you can drill down to the location of your memory leak.

Click Delete all heap states to wipe out all of the current heap information to start a new test.

Browsing references from rootsWith JDK versions 1.2 and newer, Optimizeit Profiler allows you to browse references from roots with an object graph. Roots are the roots of the reference graph and include:■ Busy monitors■ Class static variables■ Class constants■ JNI global and local references■ Java threads and native stacks


Browsing references from roots

To show the object graph, click Reference from roots. Profiler shows the entire content of the heap, so you can view the hierarchy between the different objects:

The icons used in the graph have the following meaning:

If the selected row in the top pane is an object, the bottom pane displays where the object was allocated. As usual, double clicking on the row or clicking the Source Code button shows the source code corresponding to the selection.

Note The instances are string representations obtained by calling the method toString() on each object. By default, the length of a toString() string representation is limited to 140 characters. To set a larger string size, change the Object Representation Maximum Size on the Miscellaneous dialog box from the Edit|Preferences menu.

Root

Instance variable

Instance


Using the Vir tual Machine Information mode

Object graph inspector options

The Inspector dialog box provides options to refine the references from roots object graph. To open the Inspector dialog box, click Inspector:

Click the apply button to apply these options immediately.

Using the Virtual Machine Information modeOptimizeit Profiler offers real-time display of high-level performance-related data about your test program. Using the Virtual Machine Information feature, you can discover if a performance problem is related to CPU, memory, or both.

Click Virtual Machine Info on the Optimizeit Profiler toolbar. In this mode, Optimizeit displays four panes of performance graphs. Each graph describes a different activity:■ The heap graph shows in red the current heap size required by the tested

application and in green the current heap size that is actually used by the application. The heap size is the amount of memory required to allocate Java objects. It does not include:■ any memory allocated by the VM itself or by native code used by your

program,■ classes,■ any threads stack (both Java and native), or■ memory overhead caused by Optimizeit itself.

Option Description

Include soft references Includes soft references, which are garbage collected only when memory is low, in the object graph. Checked by default.

Include weak references Includes weak references, which are garbage collected even if memory is abundant, in the object graph.

Include phantom references

Includes phantom references, which are references pointing to objects that are dead and have been finalized, in the object graph.

Include finalizer references

Includes finalizer references in the object graph.


Using the Vir tual Machine Informat ion mode

■ The Thread graph shows in red the current number of threads running and in green the number of threads actually using some CPU.

■ The Class graph shows the number of classes currently loaded in the virtual machine. This is a count of distinctly loaded classes, not necessarily a reflection of current instance allocations.

■ The GC graph shows the garbage collector activity, which is the time spent garbage collecting divided by the total time. This graph is only available with Java 2.

On Java machines, the heap graph runs across the top pane, with the thread and class graphs beneath.

On Java 2 machines, the heap and the GC graphs are above the thread and class graphs, respectively:

Click Mark to mark the current point in time. A yellow mark appears on each graph. This resets count information and allows you to isolate the information for a specific method or function.

Click Export to export the graph data and save it in a location you specify.


Using the Vir tual Machine Information mode

Virtual Machine Information inspector options

Click Inspector for options to refine and filter the information on the Virtual Machine Information graphs:

Option Description

Sampling period Defines how often Optimizeit Profiler updates all graphs.

Update when invisible Defines whether graphs are updated when the virtual machine mode is not currently selected. When this option is selected the graphs are updated continuously, even when you are using the CPU Profiler or the Memory Profiler.

Chapter 5: Using the CPU Prof i ler 61

C h a p t e r

Chapter5Using the CPU ProfilerThe CPU Profiler shows which methods your program spends its time in. To use CPU Profiler, you record a test session and then examine the results. Optimizeit Profiler gives you a per-thread description of the time spent in each method or CPU used during the test session. This helps you understand what to change in your program to improve its performance.

To use CPU Profiler:■ Follow the instructions in “Recording a test session” on page 61 to capture

your test results.■ Use “Understanding CPU Profiler output” on page 63 to interpret your

results.■ Refine your output using the options described in “Refining the CPU Profiler

display” on page 66.■ If you want to start the CPU Profiler as soon as you start Optimizeit Profiler,

you can start the program from the command line. See “Running Optimizeit from the command line” on page 19 for more information.

Recording a test sessionTo use CPU Profiler, you need to run your program, or a section of the program, from within Optimizeit Profiler. Then you can examine, filter, and customize the results to discover the bottlenecks or weak points in your code. To create a test session with the Optimizeit Profiler CPU Profiler:


Recording a test session

1 Launch a Java program (or attach Optimizeit Profiler to it), and start your test (Program|Start).

2 Open the CPU Profiler view (File|CPU).

3 Click the Start CPU Profiler button on the toolbar to start recording data.

4 Exercise the Java program to recreate a performance problem.

5 When the test program completes the action, click Start/Stop to stop the CPU Profiler.

The indicator bar on the button returns to blue.

6 You can pause (Program|Pause) or stop (Program|Stop) the Java program when you are through looking at the test data.

The Optimizeit Profiler window shows the CPU usage for each thread during the test session.

You can also start or resume your test by clicking the Start Java Program button on the toolbar, or by pressing Ctrl+T. The arrow on the button turns red when the test program is running.

You can also open the CPU Profiler view by clicking the Show CPU Profiler button on the toolbar, or by pressing Ctrl+U.

When you click this button, the indicator bar on the button turns red, and CPU Profiler starts to record information.

You can also pause the program by clicking the Pause button, or by pressing Ctrl+P.

You can also halt the test program by clicking the Stop button, or by pressing Ctrl+K. If you are running your test program from within the Profiler user interface, the program will stop and the test will end. If you are connected to a remote server, and the test program is running on the remote machine, stop will just disconnect your Profiler user interface; the test program itself will keep running on the remote server.


Understanding CPU Prof i ler output

Understanding CPU Profiler outputAfter you have recorded a test session, the CPU Profiler selects the busiest thread and displays information describing the time spent in each method, or the CPU usage in the Java program:

The bottom section displays the methods used during the test session, sorted by hot spots. Hot spots are methods where the most time is spent. The time shown is the time the program spent in a method, no matter where the method was called from. Use this view to discover if a single method acts as a bottleneck and can be optimized to speed up all the tested features.

The middle pane is a backtrace tree showing how time was spent or how CPU was used during the test session. Icons indicate the meaning of each line:

Click Reverse Display to reverse the backtrace tree from the leaves to the root. This view can be useful when you need to focus on methods or lines of code rather than broad features in your test program.

The method immediately calls another method

The method actually consumes time or CPU. The Hot Spots table lists all these methods, sorted by time used.



The two buttons at the top left corner of the bottom pane allow you to choose which a view for your data: Hierarchical view - Tree, or Aggregated view - Graph.

When you choose the graph display, a graphical representation of the stack trace appears. Each call is shown in a square node. If you place your cursor over the node, Profiler shows a summary of the CPU usage for the node:




Hierarchical view - Tree: this is the default. In tree views, a particular method may appear in multiple places, depending upon who calls the method and where, but in the graph view, the node denoting that particular method appears only once. It can still have multiple parents.

Aggregated view - Graph: in this view, a node will have incoming lines, or edges, from multiple nodes, each corresponding to a method that calls this method. Unlike trees, a graph can have loops. The graphical display can help you trace resources. If you want to find out who a statement calls, then the graphic structure is a quick and easy way to navigate through the connections between a parent statement and its multiple children.



All colors have a specific meaning:■ Blue nodes are callers; they do not use CPU time directly, but they call

other nodes/methods that do.■ Red nodes are consumers; they use CPU time directly.■ The more CPU time a node uses, the darker (more saturated) the color.

The lines and connectors attached to the node also become larger as more CPU time is consumed in and under the node.

■ As less CPU time is used, the nodes become lighter in color, until they become gray or tan in color and move towards the bottom of the graph. There is less difference, at this point, between callers and consumers.

■ Backward calls are shown with green edges. A backward call is a call made to a node higher up in the stack trace hierarchy. All forward calls are shown with blue edges; a forward call is a call made to a node lower in the stack trace hierarchy.

■ Simplified invocation sequences are shown with yellow/orange edges. These edges indicate that there are more calls between the nodes, but that these in-between calls are considered unimportant and so aren’t being shown. In some cases, you can use the Detail slider to increase the graph detail and reveal these hidden calls. When this happens, the edges will change to blue.

■ When a node is selected, the edges connecting that node to its parent and all its ancestors (all the way to the beginning of the graph) will flash.

The graph on the top, narrow frame represents the sampling period of the selected thread. The colors in the graph indicate the state of the thread each time the sample occurred:■ Green dots mean that the thread was using the CPU.■ Red dots mean that the thread was waiting on a condition.■ Gray dots mean that the thread did not exist at the sampling time.


Ref in ing the CPU Prof i ler d isplay

To show all threads and thread groups, click the graph (or the drop-down box arrow on the right side of the graph). This opens an expanded thread graph:

In this graph you can select a thread or thread group. Selecting a thread group shows how the time was spent for all threads and thread groups belonging to the thread group.

To display the code corresponding to a line in the display, select the line, then click Show Source Code. You can also double click the line to show the source code. For more information, see “Viewing source code” on page 82.

Note To minimize the overhead of the CPU Profiler, you can disable the Memory Profiler when you want to focus on CPU testing only. To do this, choose the Disable memory profiler option in the Settings dialog box.

Refining the CPU Profiler displayOptimizeit Profiler provides two types of CPU Profiler, sampler and instrumentation:■ The sampler profiler is the default. The sampler profiler interrupts all

running threads every p period, where p is a user-defined sampling period. Once all threads are interrupted, the CPU Profiler records what each thread is currently doing and whether each thread is currently using CPU. It then resumes all running threads.

■ The instrumentation profiler, which is recommended for precision testing, intercepts method invocations. Each time a method is called, the CPU Profiler records the fact that a method was called and gives the control back to the application. The profiler also intercepts when a method returns from executing and records the amount of time/CPU that was spent in the method.


Refining the CPU Prof i ler display

One type of profiler may work better for your code that the other. The sampler profiler is very good at testing a large amount of code for a long time. The instrumentation profiler is very good at precisely testing a small amount of code. The instrumentation profiler also shows if a method is slow or if it is called too often.

The following table shows the recommended use for each profiler:

The type of profiler you are using determines what options you have to refine your CPU Profiler display.

The Inspector dialog box provides options to refine your test results. To open the Inspector dialog box, click Inspector.

Profiler type Recommended use Disadvantages

Sampler ■ Testing a program for a very long time, for example, testing a server overnight. This is because sampler has very low overhead and excellent scalability.

■ Testing a feature that requires a lot of different code, for example, the startup of a large UI-intensive application. Because sampler pauses all threads before recording any information, it does not distort performance data. Sampler can also detect performance bottlenecks within methods because it is not based on method invocations.

■ Lack of precision. A sampler’s precision is not greater than its sampling period.

■ Does not record the number of method invocations.

Instrumentation ■ Testing anything that executes in less than a few hundred milliseconds, for example, a menu action. Instrumentation can measure precision in microseconds, and each time a method is invoked, it is recorded.

■ Testing a system that has many threads executing many small requests, for example, a servlet. Instrumentation records the number of times each method is invoked.

■ Lack of scalability: this profiler records a lot of information.

■ Information distortion: this profiler actually runs in the tested program threads. All method invocations are slower. Even if the profiler compensates, this can lead to distorted results.

■ Large overhead: the tested application runs several times slower.


Ref in ing the CPU Prof i ler d isplay

The Inspector has the following options for both sampler and instrumentation profilers:

The Inspector dialog box also contains the following options for the instrumentation profiler only:

Note To minimize overhead, inspector options for the CPU Profiler in Java 2 are not real-time. When an option is changed, you have to start a new recording session for the change to take effect.

Option Description

Display precision Controls the granularity of the profiler output. By default the data is organized by line of code; changing the granularity allows you to organize the data by method.

Display CPU usage only Displays only the pure CPU usage and excludes any methods where the tested thread was waiting for a condition.

Sampling period Controls the granularity of the profiler output. Use a small value for a short test session and larger value for a long test session. Usually this value varies between 1 and 100 ms.

Option Description

Precision Controls whether the profiler has microsecond precision or millisecond precision. The microsecond precision has more overhead.

Filters To minimize instrumentation overhead, a filter can be used to exclude any methods that need less than n milliseconds to execute.

Chapter 6: Appl icat ion Qual i ty Analyzer 69

C h a p t e r

Chapter6Application Quality AnalyzerThe Quality Analyzer view contains the results from Optimizeit’s automated Application Quality Analyzer, which will detect errors and warnings in the code being profiled. Click the Show Quality Analyzer button to view a list of any errors or exceptions that have occurred in the current test run. Optimizeit’s real-time validation routine checks your code for basic error conditions.

Figure 6.1 Quality Analyzer view


Upper pane of the Appl icat ion Qual i ty Analyzer v iew

Upper pane of the Application Quality Analyzer viewThe upper pane contains a table that lists error conditions and warnings reported by the Application Quality Analyzer. The table contains the following columns:

For each type of error, the threshold values used by Optimizeit to determine when to report errors are specified in the Quality Analyzer Options dialog box. The Quality Analyzer Options dialog box is accessed from the Inspector for the Quality Analyzer view. See “Inspector options for the Quality Analyzer view” on page 73 for more information.

Table 6.1 Quality Analyzer view, upper pane column descriptions

Column Description

Error Shows the error or exception that occurred. It can be one of the following:

Abnormal container growth: <container_name>This error is reported when the growth count and minimum capacity or size for the container are exceeded. Growth count and minimum capacity or size are specified in the Quality Analyzer Options dialog box. The Quality Analyzer monitors for abnormal growth in the following types of containers:

■ Byte-based containers, including StringBuffer, BitSet, ByteArrayOutputStream, and derived classes

■ Array-based containers, including Vector, ArrayList, and derived classes

■ Hashtable-based containers, including Hashtable, HashMap, and derived classes

Inefficient StringBuffer useThis error is reported when the number of string buffer allocations per method invocations exceeds the maximum allocation count specified in the Quality Analyzer Options dialog box.

Abnormal garbage collectionThis error is reported when Optimizeit detects excessive garbage collector activity.

Exception <class_name> thrownExceptions are reported when the name of the class throwing the exception matches the pattern specified in the Quality Analyzer Options dialog box.

Abnormal finalizer queue lengthThis error is reported when the queue length specified in the Quality Analyzer Options dialog box is exceeded. This may indicate, for example, that the finalize() method is overused in your code.

Unclosed file descriptorThis warning is reported when a file or socket is closed by the finalizer.

Occurrence Shows the number of times the error or exception occurred in the test run, or since the errors were last reset with the Reset All Errors button.


Lower pane of the Appl icat ion Qual i ty Analyzer v iew

To update the Quality Analyzer view, click the Update Errors button on the toolbar. See “Inspector options for the Quality Analyzer view” on page 73 for setting the Quality Analyzer view to update continuously.

To clear all collected application error data, click the Reset All Errors button on the toolbar.

Lower pane of the Application Quality Analyzer viewWhen you select an error in the upper pane of the Quality Analyzer view, the lower pane lists information about the error. The type of information displayed depends upon the type of error selected in the upper pane. The following sections describe the contents of the lower pane for each type of error.

Abnormal container growth information

When you select an Abnormal container growth error, two panes appear beneath the upper pane. The upper of the two, the middle pane, displays the occurrences of abnormal container growth captured by the Quality Analyzer. For each occurrence, the number of times the container was extended (Growth Count), and the largest size of the container are provided. When you select an occurrence in the middle pane, the bottom pane displays the associated stack trace.

Inefficient StringBuffer use information

When you select an Inefficient StringBuffer use error in the upper pane, the bottom pane displays the methods associated with each occurrence of the


Lower pane of the Appl icat ion Qual i ty Analyzer v iew

error. Each method listing includes the maximum number of times StringBuffer was allocated.

Abnormal garbage collection information

When you select an Abnormal Garbage Collection error in the upper pane, the lower pane displays garbage collector performance statistics, including:■ Minimum garbage collection duration■ Average garbage collection duration■ Maximum garbage collection duration

The lower pane contains some tips for improving garbage collection performance.

Exception information

When you select an exception in the upper pane, the lower pane displays a stack trace to show where the exceptions were thrown.


Inspector opt ions for the Qual i ty Analyzer v iew

Abnormal finalizer queue length information

When you select an Abnormal Finalizer Queue Length error in the upper pane, the lower pane displays the classes waiting to have the finalizer run, and the number of objects waiting to be finalized.

Unclosed file descriptor information

When you select an Unclosed File Descriptor error in the upper pane, two panes appear beneath the upper pane. The upper of the two, the middle pane, lists descriptions for each FileDescriptor object that was left open, and lists the FileDescriptor type, File or Socket. When you select an occurrence in the middle pane, the bottom pane displays the associated stack trace.

To display the code corresponding to a line in the bottom pane, select the line (Location). For more information, see “Viewing source code” on page 82.

Inspector options for the Quality Analyzer viewThe Inspector provides options to refine the data displayed in the Quality Analyzer view. Additionally, it provides entries to control the types of errors and exceptions that Optimizeit detects. To open the Inspector, click the Inspector button or choose Tools|Inspector.

The Inspector contains the following options for the Application Quality Analyzer:■ Options: this button opens the Quality Analyzer Options dialog box, which

allows you to set the threshold values to trigger errors for specific types of performance problems. See “Quality Analyzer Options” on page 74 for more information.



■ Update Continuously: check this option to have Optimizeit dynamically update the error information in the Quality Analyzer view. When this option is unchecked, the error information is updated when you switch to the Quality Analyzer view from another view, and when you click the Update Errors button. By default, this option is turned off to cut down on excess data fetches.

Quality Analyzer Options

The Quality Analyzer Options dialog box lets you specify the conditions for which the Quality Analyzer will report errors and exceptions. The dialog box has two panes. The left pane contains a hierarchical listing of the types of performance problems for which the Quality Analyzer monitors. When you make a selection in the left pane, the right pane displays the threshold values for error reporting in editable text boxes.

The following table lists the default threshold values for the different types of errors:

Abnormal container growth, Byte-based container

Quality metric Default value DescriptionMinimum Sizea 1024 bytes If the container size is greater than or equal to

this value, and the number of times the container is extend is greater than or equal to the Growth Count value, the Quality Analyzer reports an error.

Growth Count 2 If the number of times the container has been extended meets or exceeds this value, and the size of the container is greater than or equal to the Minimum Size value, the Quality Analyzer reports an error.



Abnormal container growth, Array-based container

Quality metric Default value DescriptionMinimum Capacity 100 When the number of objects in the container is

greater than or equal to this value, and the number of times the container is extended is greater than or equal to the Growth Count value, the Quality Analyzer reports an error.

Growth Count 2 If the number of times the container has been extended meets or exceeds this value, and the number of objects in the container is greater than or equal to the Minimum Capacity value, the Quality Analyzer reports an error.

Abnormal container growth, Hashtable-based container

Quality metric Default value DescriptionMinimum Capacity 101 When the number of objects in the container is

greater than or equal to this value, and the number of times the container is extended is greater than or equal to the Growth Count value, the Quality Analyzer reports an error.

Growth Count 2 If the number of times the container has been extended meets or exceeds this value, and the number of objects in the container is greater than or equal to the Minimum Capacity value, the Quality Analyzer reports an error.

Inefficient StringBuffer Use

Quality metric Default value DescriptionMax. Allocation Count 10 If the number of StringBuffer allocations per

invocation for a given method exceeds this value, the Quality Analyzer reports an error.

Garbage Collector Pauses

Quality metric Default value DescriptionMax. GC Pause Delay 100 (milliseconds) A garbage collector pause is reported as an

error by the Quality Analyzer if the virtual machine is blocked for more than the time specified (in milliseconds) in the Max. GC Collector Pauses text box.

Exception Tracing

Quality metric Default value DescriptionExclude java.lang.ClassNotFoundException Exceptions thrown by classes matching the

pattern specified in the Exclude text box, will not be reported by the Quality Analyzer. Wildcard characters can be used.

Include * Only exceptions thrown by classes that match the pattern in the Include text box will be reported by the Quality Analyzer.



Abnormal Finalizer Queue Length

Quality metric Default value DescriptionMax Finalizer Queue Length

1000 (entries) When the number of objects waiting to be finalized is greater than or equal to the Max Finalizer Queue Length value, the Quality Analyzer reports an error.

Unclosed File Descriptor

Quality metric Default value Description

n/a n/a The Quality Analyzer reports a warning whenever a file or socket is closed by the finalizer.

Chapter 7: Display features 77

C h a p t e r

Chapter 7Display featuresOptimizeit Profiler allows you to capture and display your data in a variety of ways, including:■ Using snapshots■ Exporting data■ Generating PDF reports■ Viewing source code■ Displaying Optimizeit console messages■ Using the Find panel

Using snapshotsAt any time, Optimizeit Profiler allows you to save test information into a snapshot. Snapshots are binary files that capture all the data from a particular test run. You can then reload the snapshot later for further analysis. This is useful, for example, when you are testing several different classes in one test pass.

Note Snapshots can only be generated within the Optimizeit UI or with Optimizeit offline profiling.


Using snapshots

To generate a snapshot,

1 Choose File|Generate snapshot.

2 In the Directory field, enter the directory where you would like the snapshot to be saved.

3 In the Name field, enter the name for the snapshot.

4 If you would like to have the time and date added to the end of the name you have chosen, check Append Time And Date When Saving.

5 If you would like to include CPU Profiler data, check Include CPU Profiler Data. The data can only be included if the CPU Profiler is currently running.

6 If you would like to include Memory Profiler data, check Include Memory Profiler Data.

This stores both heap and backtrace mode information.

7 If you would like to include reference graph and memory leak detector data, check Include Reference Graph And Memory Leak Data.

Tip Snapshots generated with this option checked are larger, and can take a long time to generate. Only choose this option when you really need reference or memory leak information.

8 You may add comments to the snapshot in the Notes area.

9 Click Write Snapshot to create the snapshot.

Note The data of the virtual machine information mode is not stored in the snapshot.

Optimizeit Profiler works the same way with snapshots as when testing an application, with a few differences. When you open a snapshot:■ All real-time operations, such as Mark and Virtual Machine Information, are

not available.■ The console shows information about the opened snapshot:

■ Date of generation■ Host where it was generated


Generat ing PDF reports

■ User that generated it■ Comments

■ Some inspector options are disabled, although you can still use such options as the Since Mark inspector option in Allocation Backtrace.

To open a snapshot,

1 Choose File|Open Snapshot or File|Open Recent Snapshots.

2 Double-click a recent snapshot, or highlight a snapshot and click Open, to view the snapshot’s test results.

It may take a few moments to load, because a snapshot uses a VM to display the data. The VM installed with Optimizeit is used to load the snapshot.

3 You can navigate through all available modes, but you cannot perform real-time actions such as starting or pausing the test run or setting a mark.

Snapshots are binary files that can only be opened from within the Optimizeit user interface. If your snapshot takes a long time to load, and your connection times out before the load is completed, you can increase the connection time-out using the Launch option from Edit|Preferences.

Generating PDF reportsThe reporting feature (File|Generate Report) creates reports containing test information for the currently attached application or open snapshot. Reports are generated as portable document format (PDF) files. The contents of the reports are based on the contents and selection in the current view. For example, if you generate a report for the Heap view, the report will reflect the column order and row selection made in the view.

Reports can be generated for the following views:■ Heap (Memory Profiler)■ Allocation Backtraces (Memory Profiler, Hierarchical View - Tree only)■ Quality Analyzer (Application Quality Analyzer)

To generate a report for the current view,

1 Configure the view to display the information you want in the report.

Any row or node selections, or column ordering choices are reflected in the report, as are Inspector (Tools|Inspector) settings. If the view has multiple panes, the display in each pane will be included in the report.

2 Choose File|Generate Report.


Generat ing PDF reports

The Generate Report dialog box opens:

3 In the Directory text box, enter the path to the directory where you want to generate the report.

Alternatively, you can click the Browse button and use the Directory Chooser to choose the directory.

4 Type a the file name for the report in the Name text box.

5 Specify a title for the report in the Title text box.

The report title appears in the header for each page of the generated report.

6 Choose whether or not to append the file name with the date and time the report is generated.

When Append Time And Date When Saving is checked, the file name itself will include the date and time the report is generated, in the following format:

<filename>_Mmm_DD__YYYY_HH-MM-SS_Z.pdf

where <filename> is the file name specified in the Name field. Mmm_DD__YYYY is the month, day, and year, HH-MM-SS is the time in hours, minutes, and seconds, and z is the time zone (AM or PM).

7 Optionally, check Reset Statistics On Completion to clear the collected data when you write the report.

When this option is checked, Optimizeit automatically resets the data collected for the test run when you generate the report.

8 Click Write File to close the dialog box and generate the report.

If you have Adobe Acrobat or Acrobat Reader on your system, Optimizeit will automatically launch Acrobat or Reader and load the generated PDF file.


Export ing data

Exporting dataData exports are HTML or ASCII files that contain just the test information from your current, open view. Optimizeit can export test data as ASCII, HTML, or Importable ASCII. After the data is exported it can be printed, compared, and archived.

Note Optimizeit cannot export the contents of the Aggregated View - Graph option found in the CPU Profiler, the Memory Leak Detector, and the Allocation Backtrace view. To capture information in these modes, you must use the Hierarchical View - Tree option.

To export the contents of a screen:

1 Choose File|Export Data, or click the Export Data button.

The Export Data dialog box opens:

2 In Export, choose the information you want to export, such as Heap Data or All Instances.

Your options will depend upon what view is active.

3 In Export As, choose the output of the file format.

Select HTML to produce an HTML document that presents data in the same format as the Optimizeit views. Select ASCII for a more compact file. Select Importable ASCII if you expect to use the output as input to another tool.

4 In the Filename field, enter the full path name of the file.

5 If this file already exists, and you want to append the new data at the end of the file, check Append Data At The End Of The File.

6 Use Title to insert a description at the top of the exported document.

7 If you wish, use the Comments section for information such as additional text to distinguish this test from others.

8 Click OK to export the data.

After exporting the data into the specified file, Optimizeit opens the file with your default editor or web browser.


Viewing source code

Viewing source codeWhen available, Optimizeit can display the source code corresponding to a selection in any of the Optimizeit windows. This includes source code from JAR files.

To view source code, double-click the object or instance in the Optimizeit Profiler window, or click Show Source Code. Optimizeit Profiler opens a separate window displaying the source code responsible for the allocation or definition of the selected object:

The relevant lines of code are highlighted in yellow. If more than one line of code is highlighted, use the small arrow buttons to automatically scroll to the next relevant line of code.

If the Java file is not found, the source code viewer provides a button to browse the file system and retrieve the file. Once the file is loaded, Optimizeit Profiler prompts you to store the source file location in the default source path, so any Java file in the same package is immediately available.

Displaying Optimizeit console messagesClick Console to print audit system-specific messages as well as the test program standard output and standard error messages. Use this printout to browse messages from the test program or to see errors if the Java program does not start.

Note If you select Open A Console in the Settings dialog box when you begin your test, the standard output and the standard errors of the test program won’t be redirected to the Optimizeit console.


Using the Find panel

Using the Find panelIn any view, you can find the information you are looking for by using the Find panel accessible from the Edit menu.

Note Sometimes the list or graph in which the search occurs does not have all the information required for the search. When this happens, the Find panel displays Fetching data... in its status field. Once the data is fetched, the search occurs.


Chapter 8: Sett ing your preferences 85

C h a p t e r

Chapter 8Setting your preferencesThis chapter describes how to use the Edit|Preferences menu option to set defaults for Optimizeit Profiler. You can set these defaults:■ Selecting default displays■ Setting launch parameters■ Setting the source code location■ Changing the class path■ Selecting a virtual machine■ Configuring servlet support■ Miscellaneous options

Your choices will appear in the Settings dialog box, where they can be customized for each applet or application you are testing.

Selecting default displaysAlthough the Edit Settings dialog box opens by default when you start Optimizeit Profiler, you can set a new default using the Startup option on the Preferences pull-down menu. You can also determine the mode that testing will begin in.


Sett ing launch parameters

The Preferences dialog box, Startup view determines the default mode once testing begins. Click Default display to choose your default workspace, such as CPU Profiler or VM Information.

Click After startup, open: to choose which window opens in the default workspace:■ Choose Settings Editor if your settings change depending upon which test

case you are running.■ Choose Attach Panel if you usually test your programs from outside of

Optimizeit.■ Choose Nothing if you rarely change your default settings, and want to go

directly to the default view when you open Profiler.

Click OK to close the form. The next time you open Optimizeit, your new defaults are activated.

Setting launch parametersThe Launch menu option lets you set your connection time-out and default port:■ By default, the connection time-out is set at ten seconds. If your connection

is timing out before you can access all the required information (for example, when you are loading a large snapshot), then you can make this option larger.

■ The default port for Profiler is 1470.

Important Make sure to use the correct port when you attach.

When you integrate Optimizeit with an application server, you start the Optimizeit audit system inside the virtual machine of the application server. By attaching the Optimizeit GUI to the audit system, you test the virtual machine of your application server and get the test information for your servlets/JSPs/EJBs.


Sett ing the source code locat ion

Optimizeit uses a port to get the test information from the audit system running in your application server. This port is only used by Optimizeit and is not related to any port of your application server. The default value for that port is 1470. If you start your application with Optimizeit from a script, the port is specified in the script. If you use the Optimizeit servlet to start the audit system, the port is specified from the servlet.

Setting the source code locationWhen Optimizeit Profiler has access to the source code for an application, it highlights the relevant lines as they are run. If the source code is not accessible, Optimizeit Profiler can still provide testing results for Java classes.

Optimizeit Profiler maintains a source path, which is a list of directories containing source code. When it requires a source file, Optimizeit Profiler searches each directory in the source path in the order specified.

Changing the default source path

The Preferences panel can be used to change the default source path:

1 Choose Edit|Preferences.

2 Click on Default Source Path in the top selection box.

3 Click the Edit button. The Source Path Chooser opens.

4 In the top box, either:■ Use the browser to search for and select the directory, JAR file, or ZIP

file you want to add.

If you select a directory, choose the directory that contains the top-level package of your Java source code. If you aren’t sure, select any Java file in your application and Optimizeit Profiler adds the appropriate directory. If you select a JAR or ZIP file, Optimizeit looks for a source file from the root of the JAR or ZIP content or from the src directory in the package.

■ Use the empty field under the browser if you have a multi-entry source path, such as c:\src;d:\project\src.jar. Enter your full path information into the field.

5 Click the Down Arrow button to add your selection to the source path.

If you entered a multi-entry source string, Optimizeit adds all the entries to the source path.

6 Repeat these steps for other directories you would like to add to the source path.

7 Click the OK button.

8 Click the OK button again to close the Preferences dialog box.


Changing the class path

Note When Optimizeit Profiler is testing an application, if a Java file is not available, you will be prompted to locate the file. After you locate the missing Java file, a dialog box prompts you to add the file’s directory to the default source path.

To set a different source path for an applet, servlet, or application that you are testing with Optimizeit Profiler, define the changes to the default source path in the Settings dialog box.

Changing the class pathWhen Optimizeit launches your applet or application, the Java virtual machine needs the location of all classes your application uses. By default, Optimizeit points to the classes that are defined in your CLASSPATH environment variable.

The CLASSPATH environment variable is a list of directories containing class files. Optimizeit searches each directory in the class path in the order they appear. If there are certain classes, ZIP files or JAR files that you would like to always be available for all test programs, add them to the default Optimizeit class path using the Settings dialog box or the Edit|Preferences menu option.

To customize the CLASSPATH using Edit|Preferences:

1 Choose Edit|Preferences.

2 Click on Default Class Path in the top selection box:

3 Uncheck the Use CLASSPATH Environment Variable option.

4 Click the Edit button. The Class Path Chooser opens.

5 In the top box, either:■ Use the browser to search for and select the directory, JAR file, or ZIP

file you want to add to the class path. If you select a directory, choose the directory that contains the top-level package of the source tree.

■ Use the empty field under the browser if you have a multi-entry class path, such as c:\classes;d:\project\xmlParser.jar. Enter your full path information into the field.


Select ing a v i r tual machine

6 Click the Down Arrow button to add your selection to the class path.

If you entered a class path string, Optimizeit adds all the entries to the class path.

7 Click the OK button.

8 Click the OK button again to close the Preferences dialog box.

Selecting a virtual machineYou can add and set your virtual machine using the Virtual Machines tab on the Settings dialog box for a specific settings file, and you can also set your default virtual machine and add virtual machines from the Virtual machine option of the Preferences dialog box:

1 Choose Edit|Preferences from the main menu bar.

2 Click on Virtual Machine in the top selection box:

3 Click Setup. This starts the virtual machine wizard.

4 Click Next.

5 Select a directory. Optimizeit will begin the search for a virtual machine from this point.

6 Click Search.

7 Optimizeit Profiler displays the virtual machines found. Click Finish to add these virtual machines to the list of available virtual machines.

8 Highlight the virtual machine you would like to be the default, and click OK to set the default. This virtual machine will now appear automatically in every new settings file.


Conf igur ing servlet support

Configuring servlet supportThe Servlet option on the Preferences menu allows you to configure servlet/JSP testing.

1 Choose Edit|Preferences from the top menu.

2 Click on Servlet in the top selection box:

3 The Path To The Tomcat 4 Server Used field contains the current path to your Tomcat installation, if any. You can enter a path or change the existing path to point to this application, which is required for direct servlet/JSP testing.

4 If you are unsure of the correct directory for your Tomcat application, click Servlet Setup to open the Setup wizard and browse for the correct location.

5 Edit the Directory Used For Temporary Files field if the default location is too small or is not easily accessible.

6 By default, Profiler filters out Tomcat classes so you can concentrate on the testing of your application. Uncheck this option if you need to see the interaction between your tested application and Tomcat classes.

7 In the Tomcat configuration section, you can choose to either automatically generate the server.xml file (the default option), or you can use an existing server.xml file if you already have one that you have used for other Tomcat operations. You can browse for the correct file and double-click to select it, or you can enter it in the file path field directly.

8 When you start the direct testing of a servlet or JSP, Profiler runs your servlet in a servlet runner. The default port used by the servlet runner is 8080. If you have another application that already uses that port, change the value in the Port Used By Tomcat field.

9 Click OK to save your changes.


Miscel laneous opt ions

Miscellaneous optionsThe Miscellaneous option on the Preferences menu allows you to configure time-outs and string lengths for CPU Profiler. These options allow you to fine-tune the operation of CPU Profiler to work faster or return more information, depending upon your priority.

In the Memory Profiler, when you use■ Instance Display■ Reduced or Outgoing Reference Graphs■ Browse Object References from Roots■ Memory Leak Detector

the string representation length can get very long, especially with detailed hash table references. To slightly improve performance, the length of these strings is set at a default of 140 characters. Enter a larger number if you need full string names.

For improved performance, the string representation time-out is set at 5 ms. Make this number larger if you see a timeout entry in the results table and need complete information.

Check the Select Best CPU Profiler Type Automatically box if you are using the Auto-start CPU Profiler option in your startup settings. When this box is checked, Optimizeit chooses the best CPU Profiler (sampler or instrumentation) for your JDK, regardless of what is selected as the default.


Chapter 9: Troubleshoot ing 93

C h a p t e r

Chapter9Troubleshooting

Starting your application1 My application starts correctly, but an alert explaining that Optimizeit failed

to attach is displayed.

2 My application ran successfully, but the Optimizeit tools are not working correctly. Most of the buttons are disabled, and the views do not contain information.

3 When starting my application, I get an alert reporting a Class not found.

4 When starting my application, the console reports that my JDK is not supported.

5 When starting my applet, the console returns java.util.MissingResourceException: Can’t find resource at java.util.ResourceBundle.getObject.

6 My application or applet cannot be started from the Optimizeit user interface. What should I do next?

7 When starting my application, the console reports a java.lang.UnsatisfiedLinkError.

8 When starting my application, the console returns an error message that it cannot find or could not locate an entry point or field.

9 (Windows only) When starting my application, the console appears but closes immediately, Optimizeit times-out and I get a warning that Optimizeit was not able to attach to my application.


Start ing your appl icat ion

10 (UNIX only) I cannot start Optimizeit. The Optimizeit script fails with the error Class not found: intuitive.optit....

11 (Solaris only) Does Optimizeit support JDK 1.2.x? When configuring Optimizeit to use JDK 1.2.x, an error box reports that JDK is incompatible with Optimizeit.

12 (Solaris only) Does Optimizeit support JDK 1.3? When configuring Optimizeit to use JDK 1.3, an error box reports that JDK is incompatible with Optimizeit.

13 Attaching to a remote process does not work. The remote audit system throws some exceptions and switching to the virtual machine information mode hangs the profiler.

1 My application starts correctly, but an alert explaining that Optimizeit failed to attach is displayed.

Optimizeit uses a default connection time-out of 60 seconds on Windows or 20 seconds on UNIX machines to attach to the virtual machine.

In some environments, the Optimizeit audit system may require more than the default time-out to initialize. If this happens, choose Edit|Preferences, select the Launch section and increase the connection time-out value.

2 My application ran successfully, but the Optimizeit tools are not working correctly. Most of the buttons are disabled, and the views do not contain information.

Optimizeit’s audit system runs inside the same virtual machine as the tested application. If the tested application ends, the virtual machine exits and Optimizeit loses contact with its audit system and cannot retrieve data (a Test program exited alert pops up in Optimizeit).

To resolve this problem, Optimizeit provides an option to disable the Java method System.exit(). This option can be enabled either by using the VM Cannot Exit or Disable Exit option in the Settings dialog box or by using the command line option -noexit (java ... intuitive.audit.Audit -noexit ...). That way the virtual machine will not exit when your application ends. Use the Stop button in Optimizeit to exit the program when your testing is complete.

If you are starting your test from the command line, or testing remotely, the -Xrunoii argument uses the configuration of the Audit System Selector. Make sure your Audit System Selector is not set to none. On Windows machines, your selected tool appears in the Windows icon tray. The Optimizeit icon is red for Profiler, green for Thread Debugger, and blue for Code Coverage.

If you have integrated Optimizeit with an application server, make sure that you are attaching the correct tool to the Audit process started with your application server. If, for example, the Audit System Selector has the Thread Debugger tool selected and you started your WebLogic tool with Thread Debugger, then you must attach with the Thread Debugger tool.

3 When starting my application, I get an alert reporting a Class not found.



This error is very likely related to a CLASSPATH setting problem. Open the Settings dialog box, and make sure that the Class Path window includes the paths to the packages and classes required by your application.

4 When starting my application, the console reports that my JDK is not supported.

The virtual machine you are using is not supported by Optimizeit. See the Release Notes for a complete list of supported JDKs. Make sure to select a supported virtual machine in the Virtual Machines tab of the Settings dialog box.

5 When starting my applet, the console returns java.util.MissingResourceException: Can’t find resource at java.util.ResourceBundle.getObject.

Optimizeit starts your applet in the Sun applet viewer in order to test it. The applet viewer throws that error when the HTML file of your applet specifies the size of your applet in percent. Make sure that the HTML file you are using to start your applet uses hard values for the width and height.

6 My application or applet cannot be started from the Optimizeit user interface. What should I do next?

The best way to investigate the cause of the problem is to start your application from the command line. This may give more information. For complete instructions on how to start Optimizeit from the command line and all available start options, please see Chapter 3, “Running Optimizeit from the command line.”

If that still does not help, contact Borland Technical Support. Remember to include the version of the operating system you are running, the version of Optimizeit and the version of the JDK you are using, and give as much information as possible about the problem. The more information you provide the quicker and more effective the response from the support team!

7 When starting my application, the console reports a java.lang.UnsatisfiedLinkError.

This error may happen if for some reason Optimizeit loads a library of an older version of Optimizeit. If you have a previous version of Optimizeit installed, make sure that your LD_LIBRARY_PATH does not point to this older version.

On Windows machines, this problem can also happen if you have integrated a previous version of Optimizeit with an IDE or an application server. When you integrate Optimizeit with an IDE or an application server, the wizard that performs the integration may copy the Optimizeit library oii.dll in the Windows directory or in the IDE directory. The PATH may still reference the IDE directory causing the old oii.dll to be used, even if you have uninstalled the previous version of Optimizeit. To make sure the correct oii.dll is used, perform a find on your hard drives for the oii.dll library. Remove any oii.dll that is not located under the Optimizeit directory.



8 When starting my application, the console returns an error message that it cannot find or could not locate an entry point or field.

This error may happen if you have two versions of the dynamic link library oii.dll on your system. This can also occur if you have an older oibcp.jar or optit.jar in the CLASSPATH or bootclasspath and/or you are loading the older oii.dll, pri.dll, or auditjni.dll instead of the newer ones. When you upgrade to a new version of Optimizeit, make sure all older versions of these files are deleted.

9 (Windows only) When starting my application, the console appears but closes immediately, Optimizeit times-out and I get a warning that Optimizeit was not able to attach to my application.

The console may flash when you are using a JDK or JRE located in a path with spaces in the path name. In the Virtual Machines tab of the Settings dialog box, make sure to select a virtual machine located in a path without spaces.

10 (UNIX only) I cannot start Optimizeit. The Optimizeit script fails with the error Class not found: intuitive.optit....

If your DISPLAY environment variable is set to a display that does not exist, the Optimizeit script fails with the message Class not found: intuitive.optit.toolclassname. This message is sent by the virtual machine that Optimizeit uses and is not accurate. Make sure to set your DISPLAY to a correct value.

For example on a machine named asterix, the DISPLAY is set with the command:

export DISPLAY=asterix:0

11 (Solaris only) Does Optimizeit support JDK 1.2.x? When configuring Optimizeit to use JDK 1.2.x, an error box reports that JDK is incompatible with Optimizeit.

You may be running the JDK 1.2.x production release. Optimizeit for Solaris does not support this JDK. The JDK 1.2.x production release does not implement JVMPI well. JVMPI is the low-level API from Sun used to retrieve information from the virtual machine. Optimizeit fully supports the JDK 1.2.x reference implementation.

12 (Solaris only) Does Optimizeit support JDK 1.3? When configuring Optimizeit to use JDK 1.3, an error box reports that JDK is incompatible with Optimizeit.

JDK 1.3 is not supported by Optimizeit for Solaris. JDK 1.3 only comes with a Hotspot runtime on Solaris, and the Hotspot runtime has several bugs in its JVMPI implementation. JVMPI is a low-level API from Sun used to retrieve information from the virtual machine. Because of these bugs, Optimizeit cannot test reliably with the JDK 1.3.

These problems have been fixed in JDK 1.3.1 (j2se 1.3.1). Make sure to either configure Optimizeit with JDK 1.3.1, or to use the JDK 1.2.2 reference implementation.


Start ing your appl icat ion server

JDK 1.3.1 can be downloaded from http://java.sun.com/j2se/1.3/download.html.

JDK 1.2.2 can be downloaded from http://java.sun.com/products/jdk/1.2/download-solaris.html.

13 Attaching to a remote process does not work. The remote audit system throws some exceptions and switching to the virtual machine information mode hangs the profiler.

The audit system for Optimizeit 6.0 is not compatible with earlier audit systems. Make sure the remote process you are attaching to is from the same version of Optimizeit.

Starting your application server1 (Windows only) Starting the testing in the VisualAge WebSphere Test

environment does not work. The browser reports an error message Error 503: Application is currently unavailable for service.

2 (Solaris only) When starting my application server with the parameters required by Optimizeit, it fails to start and displays the error Cannot find JVMPI(-3).

3 (UNIX only) My application server no longer starts since I configured it with Optimizeit.

4 My application server starts, but when I try to attach from Optimizeit I get a crash or an error dump.

5 Why can’t I attach from the Optimizeit GUI? Which port should I use to attach? Why is no test information displayed when I attach?

6 (Windows only) Starting an applet from JBuilder does not work. Optimizeit displays virtual machine not found error messages.

1 (Windows only) Starting the testing in the VisualAge WebSphere Test environment does not work. The browser reports an error message Error 503: Application is currently unavailable for service.

This problem happens if the JSPs are enabled in the web application you are trying to test with Optimizeit. Unfortunately testing JSPs is only possible inside VisualAge. So when you want to run the WebSphere Test Environment with Optimizeit, you need to disable the JSPs. To do that, edit the file <VisualAge_Dir>\ide\project_resources\IBM WebSphere Test Environment\hosts\default_host\default_app\servlets\default_app.webapp.

In this file, comment out the deployment information for the JSP servlet. To do that, add  after the section:



<autostart>true</autostart> <servlet-path>*.jsp</servlet-path> </servlet>

2 (Solaris only) When starting my application server with the parameters required by Optimizeit, it fails to start and displays the error Cannot find JVMPI(-3).

This problem happens because you are using the JDK 1.2.x production release. Optimizeit for Solaris does not support this JDK. The JDK 1.2.x production release does not implement JVMPI well. JVMPI is the low-level API from Sun used to retrieve information from the virtual machine. Optimizeit fully supports the JDK 1.2.x reference implementation.

Note: To know if a JDK 1.2.x is a reference implementation or a production release, type with this JDK:

java -version

If this command returns a line starting with “Solaris VM” you are running the production release (not supported by Optimizeit), if it starts with “Classic VM” you are running the reference implementation (fully supported by Optimizeit).

3 (UNIX only) My application server no longer starts since I configured it with Optimizeit.

First, make sure to check the outputs and/or log files of your application server for any error message. Here are the most common issues:■ On Solaris machines, you may be using the JDK 1.2.x or JDK 1.3

production release rather then the JDK 1.2.x reference implementation or another supported virtual machine. Make sure to read the JDK 1.2 section for more information.

■ In your application server configuration, the LD_LIBRARY_PATH (or native library path) does not include the Optimizeit lib directory. When you configure an application server with Optimizeit, you add the parameter -Xrunoii. When the virtual machine is started with this parameter, it loads the Optimizeit library liboii.so. If it cannot find it in the LD_LIBRARY_PATH, the virtual machine fails to start. Make sure that the LD_LIBRARY_PATH, or the library path of your application server points to the Optimizeit lib directory.

4 My application server starts, but when I try to attach from Optimizeit I get a crash or an error dump.

This could be caused by one of the following issues:■ You are using an unsupported JVM. Check the Optimizeit list of

supported virtual machines in the Release Notes and make sure that Optimizeit has access to a supported JVM. If you have integrated with an application server, make sure that the application server is also using a supported JVM.

■ Your bootclasspath does not contain oibcp.jar.■ Your classpath does not contain optit.jar.



■ There is an older version of the oii.dll on the machine.■ You have a Solaris machine and have not included the -Xboundthreads

option in your command.

5 Why can’t I attach from the Optimizeit GUI? Which port should I use to attach? Why is no test information displayed when I attach?

When you integrate Optimizeit with an application server, you start the Optimizeit audit system inside the virtual machine of the application server. By attaching the Optimizeit GUI to the audit system, you test the virtual machine of your application server and get the testing information for your servlets/JSPs/EJBs. Optimizeit uses a port to get the testing information from the audit system running in your application server. This port is only used by Optimizeit and is not related to any port of your application server. The default value for that port is 1470. If you start your application with Optimizeit from a script, the port is specified in the script. If you use the Optimizeit servlet to start the audit system, the port is specified from the servlet. Make sure to use the correct port when you attach.

Make sure that the process running on the remote machine is running on the port that you are attaching to. Also make sure that no other Optimizeit user interface is trying to attach to that same audit system. Only one Optimizeit user interface can attach to an audit system.

If you have other versions of Optimizeit, make sure that you have the same versions of Optimizeit installed and running on both the host and remote machine. For example, you cannot attach the Optimizeit Profiler 6.0 user interface to an Optimizeit audit system from version 4.1.

If you change test parameters (for example, you check the Disable Memory Profiler option), you must re-start your application server before beginning a new test. You must also re-start your application server to connect with another tool. For example, if you have been testing an application with Profiler and want to run a test against the same application with Thread Debugger, you must

a Shut down your Profiler test.

b Shut down your application server.

c Use the oiselector (Audit System Selector) to select Thread Debugger.

d Restart your application server.

e Start Optimizeit and attach to your test program.

For a test script, make sure that you use the correct -Xrun version for your chosen tool: -Xrunpri for Profiler, -Xruncci for Code Coverage, and -Xruntdi for Thread Debugger.

6 (Windows only) Starting an applet from JBuilder does not work. Optimizeit displays virtual machine not found error messages.

When you define a new virtual machine within JBuilder, make sure to select the executable java.exe in the bin directory, not in jre/bin.

Optimizeit uses oldjava.exe to start applets; this executable does not exist inside the jre/bin directory.


Problems dur ing test ing

Problems during testing1 While testing my application, my application stops or crashes unexpectedly.

2 While testing my application, the application stops, the console shows a java.lang.OutOfMemoryError.

3 Why can’t I test applets with my JRE?

4 (Windows only) During a testing session, the Optimizeit user interface becomes unresponsive, and the Optimizeit window is all white.

5 The Optimizeit GUI looks wrong. The text is clipped, the windows are the wrong size.

6 Optimizeit seems to run slowly. Are there some strategies to improve performance?

7 While testing my application, the console shows a lot of lines saying Should not happen GCOPBuffer too small... and then the virtual machine crashes.

8 Opening a snapshot does not work, Optimizeit says it could not attach to the virtual machine.

9 (UNIX only) The CPU Profiler does not work. Results are wrong and sometimes the CPU Profiler crashes.

10 (UNIX only) The CPU Profiler does not work: when I stop the CPU Profiler, it shows no results and my application hangs.

1 While testing my application, my application stops or crashes unexpectedly.

Take a look at the external console. It may give more information on what went wrong. If you do not have an external console, it means you have not selected the Open A Console option in the Settings dialog box. Make sure to select the option, and start the testing again.

Also, try running the same test using the default JDK installed with Optimizeit. Sometimes, errors are related to the JVM used.

2 While testing my application, the application stops, the console shows a java.lang.OutOfMemoryError.

The virtual machine ran out of memory. You can increase the size of the java heap by using the extra java parameters -Xms and -Xmx. For example, -Xms128m -Xmx128m sets the size of the java heap to 128 Mb.

If you are starting the testing from Optimizeit, add those parameters in the Extra Java Parameters field on the Settings dialog box.

If you are starting your application from the command line, add those parameters to your command. For example, the following command starts the testing of BusyApp with the JDK 1.3, setting the size of the java heap to 256 Mb:

java -classic -Xrunoii:filter=<OptIt_Dir>/filters/DefaultAllOn.oif -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar -Xms256m -Xmx256mintuitive.audit.Audit BusyApp



3 Why can’t I test applets with my JRE?

When you test applets with JDK 1.2 or 1.3, Optimizeit runs your applet in the applet viewer using oldjava rather than java, to avoid security exceptions. The JRE 1.2 and 1.3 do not include oldjava. This is why Optimizeit requires a JDK to test applets.

However, you can still test applets with a JRE from Optimizeit by following these steps:

a Edit the java.policy file of your JRE located under the lib\security directory of your JRE.

b At the end of the file include the following lines:

grant codeBase "file:<OptItDir>/lib/optit.jar" { permissionjava.security.AllPermission; };

c Replace <OptItDir> with the directory where you installed Optimizeit, using / instead of \ (for example: c:/Optimizeit/OptimizeitSuite).

d Set the environment variable OI_APPLET_JRE to true.

4 (Windows only) During a testing session, the Optimizeit user interface becomes unresponsive, and the Optimizeit window is all white.

This problem can occur if the Optimizeit user interface runs out of memory. Optimizeit is a Java program. By default the virtual machine is created with a minimum heap set to 8 Mb and a maximum heap set to 64 Mb.

You can override these default values by using the following environment variables:■ OIMINHEAP

■ OIMAXHEAP

These variables should be set to a new memory size. The notation should be compatible with the virtual machine options -ms and -mx. For example, 12000 means 12000 bytes, 64K means 64 Kb and 64M means 64 Mb.

To increase the max heap to 128 Mb on Windows NT:

a From the Start menu, select the Settings menu and then Control Panel.

b Double-click on the System icon.

c Select the Environment tab.

d In the Variable field, enter OIMAXHEAP.

e In the Value field, enter 128M.

f Click on Set, and then Apply.

If increasing the heap size does not help, use the following procedure to troubleshoot the issue:

g Open Windows Explorer.

h Browse and select the directory containing Optimizeit.

i Select the jre directory.



j Double click on startOptimizeit.bat to start Optimizeit with a console window.

k Recreate the issue. Please send any error message / exception to Borland Technical Support.

You may need to increase the console window buffer size to capture the whole error message:

l Choose Properties from the console window.

m Select the Layout tab.

n Enter a larger value in the Screen buffer size height field.

5 The Optimizeit GUI looks wrong. The text is clipped, the windows are the wrong size.

Some X-servers, including Exceed, have problems with Swing applications, such as over-large fonts or wrong-sized windows. The best way to test remotely is to run the Optimizeit GUI locally. If you test remotely from your Windows platform on your UNIX machine, make sure to use Optimizeit for Windows on the Windows platform.

To configure Exceed 7 to display the right fonts with Optimizeit:■ Open the Exceed Xconfig window from the Windows Start menu,

Hummingbird.../Exceed/Xconfig.■ Double click the Font icon to open the Font Settings dialog box.■ Click the Font Database... button.■ Unselect the Automatic Font Substitution option then click OK.■ Restart Exceed.

6 Optimizeit seems to run slowly. Are there some strategies to improve performance?

To improve Optimizeit performance:■ Check the command line argument (shown in the console if you are

running from the user interface) and make sure there are no debugging arguments passed into the JVM. The JVMPI and the debugging interface cannot work simultaneously, so this will slow down performance.

■ Are you using a Hotspot runtime? This can sometimes degrade performance.

■ For Profiler, make sure you do not set the minimum heap size to a high value. This causes the heap to be resized less often. For better performance, use approximately a 4:1 ratio for RAM:Heap size. You can use a 2:1 ratio as long as you also add RAM to cover non-heap VM use and Optimizeit user interface overhead. disabling the garbage collector will slow down the backtrace view in both Tree and Graph modes because the instance count keeps increasing. This affects the time it takes to compute the backtrace views.



■ For Profiler, you can improve performance by disabling the Memory Profiler when you are testing CPU, or disabling the CPU Profiler when you are testing memory use.

7 While testing my application, the console shows a lot of lines saying Should not happen GCOPBuffer too small... and then the virtual machine crashes.

This problem happens when the gc operation buffer is full. You can increase this buffer size with the GCOPSIZE property. For example:■ to use 4 Mb: -DGCOPSIZE=4■ to use 6 Mb: -DGCOPSIZE=6

The default value is 2 Mb and is generally large enough.

Add -DGCOPSIZE=n in the Extra Java parameters field of the settings editor if you start the testing from Optimizeit. Add this property to the command line if you start your application from the command line. For example:

java -classic -Xrunoii:filter=<OptIt_Dir>/filters/DefaultAllOn.oif -Xnoclassgc -Djava.compiler=NONE -GCOPSIZE=6 intuitive.audit.AuditBusyApp

The gc operation buffer is a buffer that Optimizeit uses to take into account garbage collector actions. When an action is received while the garbage collector is running, Optimizeit cannot use malloc and increases this buffer. This is why a constant must be used.

8 Opening a snapshot does not work, Optimizeit says it could not attach to the virtual machine.

When you open a snapshot in Optimizeit, Optimizeit starts the snapshot reader with your snapshot and attaches to it. Set the environment variable SnapAuditConsole to true. This causes the console to open when you start the testing. The console may give important information if there are some problems.

9 (UNIX only) The CPU Profiler does not work. Results are wrong and sometimes the CPU Profiler crashes.

This problem occurs when using J2SE 1.3.1 (JDK 1.3.1) without the correct options. When starting a Java program or an application server with JDK 1.3.1, you need to add the following options:■ -Xint, to run in interpreted mode (Solaris only, and only required if you

are using the instrumentation-based profiler.)■ -Xboundthreads, to bind threads to LWP

10 (UNIX only) The CPU Profiler does not work: when I stop the CPU Profiler, it shows no results and my application hangs.

Optimizeit comes with different libraries for green thread virtual machines and native thread virtual machines. Solaris machines use native threads by default, and Linux uses green threads. If for some reason Optimizeit loads the wrong libraries, the CPU Profiler does not work correctly and may very likely hang the application when you press the Stop button. A typical


Undoing an integrat ion (Windows only)

situation is when you start your application with the audit system from the command line or from a script on a Solaris machine, and you are using the JDK 1.2.2 reference implementation which defaults to green threads. In that case, you can choose to either:■ Force the virtual machine to use native threads, by adding -native as the

first argument to the java invocation, or■ Tell Optimizeit to use its green thread library by adding -DOPTITTHR=green

and -DOPTITDIR=<OptItDir> to the java invocation (where <OptItDir> is the directory where you installed Optimizeit).

For example, to start the SwingSet demo with Optimizeit using native threads:

java -native -Xrunoii:filter=<OptIt_Dir>/filters/DefaultAllOn.oif -Xnoclassgc -Djava.compiler=NONE -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar SwingSet

Or, an example using green threads:

java -green -Xrunoii:filter=<OptIt_Dir>/filters/DefaultAllOn.oif -Xnoclassgc -Djava.compiler=NONE -Xbootclasspath/a:<OptItDir>/lib/oibcp.jar -DOPTITDIR=/home/Optimizeit -DOPTITTHR=green SwingSet

Note that the -native and -green parameters should always be the first parameters. If they are not, the virtual machine does not recognize them and fails to start. You can also enter an export THREADS_FLAG=(native or green)command before running the Optimizeit startup command to set the threads for your test run.

Undoing an integration (Windows only)1 How do I undo the integration with VisualCafe?

2 How do I undo the integration with IBM VisualAge?

1 How do I undo the integration with VisualCafe?

Delete the file <CafeDir>\Bin\Components\oivcplugin.jar.

Also, VisualCafe stores some classes and other archives in a repository. This repository can sometimes hold a reference to plug-ins. Rename the file <CafeDir>\local.rps to <CafeDir>\local.rps.old and then start Cafe.

When a dialog appears, click yes. Cafe rebuilds the repository and the problem goes away.

2 How do I undo the integration with IBM VisualAge?

Remove the directory <VisualAge>\ivjtools\tooldata\OptimizeitPlugin and the directory <VisualAge>\ide\tools\OptimizeitPlugin.

Index 105

Aadding a virtual machine 17adding API calls in your program 38aggregated view - graph 47, 64Allocation Backtrace mode 45

options 48applet

testing 9application

testing 9application programming interface (API) 37Application Quality Analyzer view 69attach panel 86attaching the audit system 29Audit API 38audit system 86

attaching 29description 20

audit system start optionsnative 23

auto-start CPU profiler 10

Bbootclasspath 28

Cchanging the default source path 87choosing

class path and source path 10, 87, 88extra Java or program parameters 10operation options 10program location 9program type 9

class path 88class path window 10classic runtime 18CLASSPATH environment variable 20, 88command line, testing from 19configuration file 8, 18, 33configuring servlet support 90connection time-out 86console 82console options 10CPU Profiler

mode 4

CPU profiler 61comparison sampler/instrumentation 67instrumentation 66Instrumentation options 68options 68starting from the command line 37

custom bootclasspath JAR 28

Ddefault

class path 10port 86source path 87

default displayclass path 88setting 85virtual machine 89

disable memory profiler 10display options

graph 47, 64tree 47, 64

EEdit Settings dialog box 7, 85enable audit API 10environment variables 20error detecting 69example

command line with JDK 1.2 26exclude Filter option 31extra Java parameters 10extra program parameters 10

FFilter Editor 31Filter Editor columns 31filters

creating 14editing 15

Find panel 83

Ggarbage collector

disabling 44generating reports 79graph view 47, 64

Index


Hheap

graph 58heap mode 42, 43

Heap mode 42, 43filtering 43options 45

heap size 58hierarchical view - tree 47, 64host name 30Hotspot runtime 18HTML

exporting to 81

Iignore coverage column 31include only Filter option 31installing 2Instance Display mode 50

options 53Instrumentation. See CPU profiler,

instrumentation 66integrating Optimizeit 4Integration Guide 4intuitive.audit 38

JJAR files 88Java 2 runtime 3Java runtime option 18Java setup wizard 3JIT

supporting library 26JIT compiler 18

Llaunch parameters 86location field 9

MmakeBootCP 28Memory Leak Detector 54Memory Profiler 41

mode 4

Nnative start option 23

Oobject graph

options 58offline profiling 33oibcp.jar 38Open A Console 10Optimizeit

Integration Guide 4

Ppause after launch 10PDF

reports 79port 86

used between the audit system and UI 22, 24port number 30preferences 5

default class path 88default source code 87launch 86servlet 90startup 85virtual machine 89

preferences menu 10, 85Profiler

installing 2integrating 4running 4using 1

profilingoffline. See offline profiling 33

programlocation 9options 10types 9working directory 9

QQuality Analyzer

inspector options 73

Rreadme file 3Release Notes 3remote application

connecting the audit system 29testing 9, 30

reporting functions 4reports 79running Profiler 4

Index 107

Sselecting a virtual machine 89selecting default displays 85selecting test options 8servlet

testing 9servlet testing 90setting up the audit system 20setting virtual machine properties 17Settings dialog box 7, 88settings editor 86settings file 8, 18snapshot

generating 77source code

directories 11location 11, 87viewing 52, 66, 82

source path 30chooser 11

source path chooser 87starting from the test program 37starting Optimizeit and connecting the audit

system 29starting your test program 38startup option 85startup tab 8System.err 10System.in 10System.out 10

Ttemporary object allocation

minimizing 41tracking 49

testinga program running on another machine 30applets 9applications 9remote applications 9, 29, 30servlets 9

testing a program from the command line 19threads

CPU profiler thread graph 66selecting a thread 66VM Info thread graph 59

tree view 47, 64

Uusing

Filter Editor 31virtual machine wizard 3

Vviews

Application Quality Analyzer 69virtual machine

adding 17classpath 88runtime 18selecting 89setting properties 17starting automatically 37wizard 3

Virtual Machine information 58exporting data 59options 60

Virtual Machines tab 17vm cannot exit 10vm options 10

Wwhen to use Profiler 1working directory 9

Documents

Optimizeit Profiler 6 - cca.yuntech.edu.twcca.yuntech.edu.tw/cca/ccawork/cca系統設備資料/jbxpdfdocs_e/profiler.pdf · Borland Software Corporation 100 Enterprise Way Scotts