Scenario Tool

Overview

The scenario tool enables profiling java programs run in Eclipse. It is available from the Eclipse Explorer Tool box. Scenario tool is a part of Dynamic Tools.


Figure: Toolbox.

Usage

Setup

Launch the java program you want to profile in debug mode in Eclipse. Make sure this is the only launch in the workspace, otherwise a scenario can't be started. Run the program until you wish to start profiling it. Note you can profile the program from its beginning by choosing Eclipse to pause the launch at the main() method of the launch.


Figure: Scenario Setup.

Starting a Scenario

When you want to start profiling the program, press the "Start Scenario" button of the Scenario Tool (at the Eclipse Explorer Tool box). The "Start Scenario" dialog interface appears. In it, you can specify the behavior of the scenario.
Actions
These are the profiling information you can gather. A scenario can execute any combination of the actions.
Thread diagram
This option will monitor threads creation and destruction. When the scenario ends, a thread diagram will be displayed, portraying information on what thread activity during the scenario:
Call tree diagram
This action can yield call trees of any threads that are alive when the scenario starts. If this action is chosen, you must specify at the "Choose thread" list which threads you want to create a call tree for.
Method hit count
Counts how many times a method had been called during the scenario. This action can be either launch-wide, meaning that method calls from different threads are treated the same. Alternatively, it can be thread-specific, meaning hit counts are calculated per thread. In order for this action to be thread-specific, choose "Get method hit count for each thread independently", and specify for which threads method hit counts should be calculated.
Class order diagram
Yields a list of classes accessed during a scenario. A class is "accessed" if a method defined in it is called. Like method hit count, this can be either launch-wide or thread specific (see Method hit count for explanation).
Breakpoint behavior
These options determine how breakpoints will be treated during the scenario. Choose exactly one of the following
Break when encountering breakpoints
The scenario will pause when encountering a breakpoint. When the scenario is paused, it can either be resumed or stopped.
Stop when encountering first breakpoint
The scenario will stop upon hitting the first breakpoint.
Ignore breakpoints
Hitting breakpoints will have no effect on the scenario.
Other Scenario Options
Resume monitored threads when scenario ends
If chosen, threads monitored by the scenario will be resumed when it ends. Otherwise, they will be suspended. If threads from the "Choose thread" list are chosen, these are the monitored threads. Otherwise, all of the threads are monitored.
Ignore Eclipse "meta threads"
Choosing this will cause the scenario not to monitor certain Eclipse-related threads, which are not likely to yield any interesting output. Eclipse meta threads are defined to be all threads named:
  • main
  • State Data Manager
  • Framework Event Dispatcher
  • Start Level Event Dispatcher
  • Java indexing
Obtain source code information
This option must be chosen if you want to use the "Place Breakpoint" option of the Call Tree output view. Note that not choosing this option can significantly speed the scenario.

Once you've specified the desired scenario behavior, press OK. The scenario will start.

Ending a Scenario

A scenario can end in three ways:

When a scenario ends, the desired output of the chosen actions is displayed in freshly opened views.

Pausing a Scenario

A scenario is paused when it hits a breakpoint and the "Pause when encountering breakpoints is chosen". When a scenario is paused, the monitored threads are suspended (and their stack frames are available). A paused scenario can be resumed and stopped (by the corresponding buttons in the Scenario Tool menu).

A Note on Profiling Eclipse Launches

If you wish to start a scenario on an Eclipse launch, consider using the "Ignore Eclipse 'meta threads'" option. The ignored threads are not likely produce relevant information. Especially, do not try to pause Eclipse's main thread. This will cause the Eclipse launch to halt, as the main thread handles critical events and operating system interaction.

Known Issues

If a thread was sleeping or waiting for a lock, it might stay suspended during the scenario instead of being stepped into. This is known to happen to the JDT reconciler thread. If problem encountered, pause the thread and step into it.


Fourth Contact Group
Last modified: Sun Jul 09 20:38:05 Jerusalem Daylight Time 2006