Profiling EPL Applications

Launching a custom profiling session

You can profile an Apama EPL application using a default launch configuration. You can also create custom profile launch configurations for launching profiling session. For example, you may want the profiler to launch the application using a correlator different from the project’s default correlator or to profile an application running on a remote correlator.

• When a default profile configuration is launched, it starts the profiler and the default correlator and the application if they aren’t already running. If they are already running the profiler just starts profiling the running application. See Launching a default profiling session for more information on launching a default profiling session.
• If you want to profile an application that runs on a non-default correlator, you need to create a launch configuration that points to the run configuration associated with the desired correlator. See Launching a custom profiling session for more information for creating and launching a custom profiling configuration.
• If you want to profile an application that runs on a remote correlator, you need to create a launch configuration that points to the machine where the correlator is running. In order to profile an application running on a remote correlator, the remote application needs to be running before you launch the profiling session. See Launching a remote profiling session for more information on creating and launching a configuration for a remote profiling session.

Launching a default profiling session

You can profile an Apama EPL application using a default launch configuration or you can create a custom profiler launch configuration for an application running on a remote correlator.

To launch a profiling session in Apama Plugin for Eclipse using the default launch configuration

1. From the Apama Plugin for Eclipse menu, select Run > Profile.

2. By default, Apama Plugin for Eclipse displays the Confirm Perspective Switch dialog asking if you want to use the Apama Profiler perspective. Click Yes. Apama Plugin for Eclipse switches to the Apama Profiler perspective and begins collecting data from the EPL application.

   Note, you can change the behavior of the Confirm Perspective Switch dialog by changing a setting in the Profiling Monitor view’s Preferences wizard; see Displaying Apama perspective preferences.

Launching a custom profiling session

You can create custom launch configurations for profiling Apama EPL applications. See Creating a custom profile launch configuration for more information on creating a custom profiler launch configuration.

To launch a profiling session in Apama Plugin for Eclipse using a custom launch configuration

1. In the Project Explorer right-click the project name and select Profile As > Apama Correlator Profiler. The Select Profile Application dialog appears.

2. In the Select Profile Application dialog, select the launch configuration you want to use and click OK.

3. By default, Apama Plugin for Eclipse displays the Confirm Perspective Switch dialog asking if you want to use the Apama Profiler perspective. Click Yes. Apama Plugin for Eclipse switches to the Apama Profiler perspective and begins collecting data from the EPL application.

   Note, you can change the behavior of the Confirm Perspective Switch dialog by changing a setting in the Profiling Monitor view’s Preferences wizard; see Displaying Apama perspective preferences.

Creating a custom profile launch configuration

You can create custom profile launch configurations for launching profiling session. For example, you may want the profiler to launch the application using a correlator different from the project’s default correlator.

To create a custom profile launch configuration

1. In the Project Explorer right-click the project and select Profile As > Profile Configurations. The Profile Configurations wizard starts.

2. In the Profile Configurations wizard, click the New launch configuration button.

3. In the Profile Configurations wizard, replace the default name in the Name field if desired.

4. In the Profile Configurations wizard, on the Connection Details tab, in the Profile a field, use the default Apama Launch configuration selection.

5. In the Launch Configuration field, click the Browse button. The Choose Launch Configuration dialog appears.

6. In the Choose Launch Configuration dialog, select the run configuration you want to profile and click OK.

7. In the Profile Configurations wizard, click Apply to save the profile configuration or Profile to save and launch the profiling session.

Correlator Profile Configurations

The Profile Configurations wizard lets you create, manage, and run correlator profiler configurations.

To add or modify the desired information

1. To create a new profiler launch configuration, select Apama Correlator Profiler in the tree view to the left and click the New Launch Configuration button (()).

2. To duplicate a correlator profiler configuration, select it and click the Duplicates button (()).

3. To delete a correlator profiler configuration, select it and click the Delete button (()). Click Yes to confirm deletion.

4. To collapse the profiler configurations hierarchy so that you see only the top-level categories, click the Collapse button (()).

5. To control which correlator profiler configurations appear in the tree view, select Apama Correlator Profiler in the tree view, click the Filter launch configurations button (()) to display the Preferences (Filtered) dialog. Alternatively, you can click the down-arrow to the right of the Filter button to select Filter Closed Projects, Filter Deleted/Unavailable Projects, Filter Configuration Types, Apply Window Working Set(s) or Filtering Preferences, which also displays the Preferences (Filtering) dialog.

6. To modify a profiler configuration, select it in the tree view. Then edit it as needed and click Apply.

7. The Profile Configurations dialog also displays a link to the Perspectives Preferences dialog. You can configure launch perspective settings in Perspectives Preferences.

Launching a remote profiling session

In Apama Plugin for Eclipse, you can profile an Apama application running on a remote correlator by creating a custom profiler launch configuration that points to the remote machine where the correlator is running.

Before you launch a profiling session for an application running on a remote correlator, the remote application needs to be already running, and you must also create a remote profiler launch configuration.

To launch a profiling session for an application on a remote correlator

1. In the Project Explorer right-click the project name and select Profile As > Apama Correlator Profiler. The Select Profile Application dialog appears.

2. In the Select Profile Application dialog, select the launch configuration you want to use to connect to the remote correlator and click OK.

3. By default, Apama Plugin for Eclipse displays the Confirm Perspective Switch dialog asking if you want to use the Apama Profiler perspective. Click Yes. Apama Plugin for Eclipse switches to the Apama Profiler perspective and begins collecting data from the EPL application.

   Note, you can change the behavior of the Confirm Perspective Switch dialog by changing a setting in the Profiling Monitor view’s Preferences wizard; see Displaying Apama perspective preferences.

Creating a remote profiler launch configuration

To create a remote profiler launch configuration

1. From the Project Explorer, right-click the project and select Profile As > Profile Configurations. The Profile Configurations wizard appears.

2. In the Profile Configurations wizard, enter a meaningful name for the configuration in the Name field if you do not want to use the default name.

3. On the Connection Details tab, in the Profile a field, select Remote Apama correlator.

4. In the Remote Correlator Details section, enter the name of the host and the port in the Host and Port fields.

5. If desired, and if the remote correlator is running, click Test Connection to confirm the specified location information is correct.

6. Click Apply to save the profile configuration or Profile to save and launch the profiling session.

The Apama Profiler perspective

The Apama Profiler perspective consists of the following views:

• Profiling Monitor view
• Execution Statistics view

Profiling Monitor view

The Profiling Monitor view shows a tree view of the available profiler sessions. These sessions could be associated with different applications or associated with applications running on different correlators.

The tool bar for the Profiling Monitor view contains the following buttons:

• () — Resume the profiling session.
• () — Pause the profiling session.
• () — Stop the profiling session.
• () — Manually refresh the Execution Statistics view with collected data. By default the data is automatically refreshed at 10 second intervals; you can change the refresh behavior with the Preferences button described below.
• () — Displays a page of the Apama preferences on which you can change the profiler settings. For more information, see the description of the Apama preference page Profiling and Logging.
• () — Collapse the entries in the tree view displayed in the Profiling Monitor view.
• () — Display the Profiling Monitor view’s drop down menu.

Execution Statistics view

The Execution Statistics view displays the timing details of the profiled EPL application. This view includes the following tabs:

• The Execution Statistics tab

• Comparison of Execution Statistics tab

You can adjust the way the information appears using the buttons on the view’s tool bar. The following tools are available:

• () — Apply and manage filters for displaying subsets of the profiling data. This tool is not available for the Comparison of Execution Statistics tab. For more information on filtering the data, see Using filters
• () — Expand the entire of tree of entries.
• () — Collapse the entire of tree of entries.
• () — Take a snapshot of the profiling data.
• () — Manage snapshots.
• () — Specify how to organize the profiling information by Contexts, Monitors/Events, or Action.
• () — Choose which columns to display. You can also change the order in which the columns are displayed.

The Execution Statistics tab

The Execution Statistics tab carries a sub-title of “Session Summary”. By default the left-hand column displays a tree view of the application’s contexts, monitors, and actions organized by contexts. You can change the display to show profiler information organized by monitors/events and by actions using the Organize View By button [].

You can filter the profiler information in order to focus on specific application behavior using the Filter button []. For more information on using filters, see Using filters.

By default the display includes the following three columns of information:

• CPU time — The time in seconds this action has been executing.
• Cumulative time — The time in seconds spent in this action and all its child actions.
• Idle — The time in seconds this context has been idle, waiting for events.

You can also display the following information by using the Choose Columns button [].

• Empty — The time in seconds this context has been empty, that is, without monitors.
• Non-Idle — The time in seconds this context has been non-idle, in other words, when it has had events to process.
• Runnable — The time in seconds this context has had work to do, but during which the work has not been executed by the scheduler.
• Plugin — The time in seconds spent in a plug-in call.
• Blocked — The time in seconds this context has been blocked, for example, waiting for a queue to become non-full.

Comparison of Execution Statistics tab

This tab compares the most recent profiling data with that of a previous set. For each type of information there are three associated columns, for example CPU, Old CPU, and Diff CPU. The leftmost column is the current information, the column labelled “Old” is the information from the previous set, and the column labelled “Diff” is the change between the new and the previous information. The previous set is considered the baseline.

By default, the “previous set” consists of the data from the last time it was refreshed. You can change this behavior to compare the most recent data to data captured in a snapshot at a particular moment in time. For information on capturing data in a snapshot, see Taking snapshots

As with the Execution Statistics tab, you can change the type of information and how it appears on the Comparison Execution Statistics tab as follows.

• Use the Organize View By button [] to organize the profiler information by Contexts, Monitors/Events, or Actions.
• Use the Choose Columns button [] to add, remove, or change the order of the information columns.

Viewing EPL code

In the Execution Statistics view you can display the EPL code for a specific action or listener. Only the action-level entries that are shown with the code icon [] are able to display the associated code. There are other entries, such as garbage collector timings (that is, GC-mark, GC etc.), events and others for which there is no code association.

To display the code for an action or listener:

In the Execution Statistics view, double-click the action or listener for which you want to view the code. The EPL source file containing the code for the action or listener opens (if it is not already open) in the EPL editor.

Using filters

When viewing the Execution Statistics tab of the Execution Statistics view, you can focus on specific data by applying a filter to the profiling information.

Creating a Filter

You can create filters to concentrate on particular profiling data.

To create a filter

1. On the Execution Statistics tab, click the Filter button [] on the view’s tool bar and select Manage Filters. The Manage Filters dialog appears.

2. In the Manage Filters dialog, click Add. The Create Filter dialog appears.

3. In the Create Filter dialog, specify the Filter Name and an optional Filter Description.

4. In the Create Filter dialog, click the Add New Row button []. This adds a row in the table field as indicated by a new set of parenthesis marks ( ).

5. Specify the filter criteria as follows:

   1. Click the Type column and from the drop-down list select the type of data you want to filter for.

   2. Click on the Operation column and from the drop-down list specify the operation that is appropriate to the Type you are filtering for.

   3. Double-click in the Value column and enter an appropriate value; then click in a blank area of the table to accept the value you specified.

   4. You can add other criteria to the filter by using AND or OR. In the AND/OR column, select the appropriate operator from the drop-down list, click the Add New Row and specify the additional filter criteria as described above.

6. Click OK.

7. In the Manage Filters dialog, select the filter you want and click Apply.

   The Execution Statistics tab is updated according to your filter criteria.

Managing Filters

Use the Filter tool to manage the filters. You can add, edit, or remove filters; change which filter is used; and revert to the default display of unfiltered data.

To manage filters

1. On the Execution Statistics tab, click the Filter tool [] and select Manage Filters from the pop-up menu.
   • If you want to create a new filter click Add. The Create Filter dialog appears. See `Creating a Filter for more information on creating filters.
   • If you want to edit an existing filter click, select the name of the filter and click Edit. The Edit Filter dialog displays the current filter criteria. Edit the filter information as necessary and click OK.
   • If you want to remove a filter, select the name of the filter and click Delete.
2. Select the filter you want and click Apply. If you remove all the filters and click Apply, the profiler displays shows the default unfiltered set of information.

If you are looking at a filtered data set and want to return to the default display of unfiltered data, click the Filter tool [] and select Reset Filter from the pop-up menu.

Taking snapshots

You can capture profiling data at any moment in time by taking snapshots. You can then compare current profiling data to the data represented in a snapshot.

To take a snapshot

1. In the Execution Statistics view, click the Take Snapshot button []. The Create Snapshot dialog appears.

2. Enter a meaningful name for the snapshot in the Snapshot Name field.

3. Specify the source of the data you want to use to create the snapshot as follows:

   • To populate the snapshot with data that the correlator captures at this point in time, select Current correlator.

   • To populate the snapshot with data that has previously been stored on disk in a .csv file, select Select from file. This data would typically be collected using the engine_management tool as, for example:

     engine_management -r profiling get > myfile.csv
     

     Note, however to be used this way, the .csv file must have been generated using Apama release 5.0.1 or later.

     For more information on the engine_management utility, see Shutting down and managing components.

4. Click OK.

In the Comparison of Execution Statistics tab, the baseline columns (labelled “Old”) display the data captured in the snapshot and the columns labelled “Diff” are similarly updated to compare the current information with that captured in the snapshot. For more information on managing snapshots, see Using snapshots.

Using snapshots

After you create a snapshot the display on the Comparison of Execution Statistics tab is updated to compare the current data with that captured in the snapshot. You can change this to compare the current data to another snapshot or the default setting that compares the current data to the data seen the previous time the data was refreshed.

To change the compared sets of data

In the Comparison of Execution Statistics tab, click the Show Previous Snapshots button [].

• If you want to use the data from another snapshot, select the name you assigned to it.

• If you want to return to the profiler’s default comparison, select Compare last data.

• If you want to manage your snapshots

  1. Select Manage snapshots.
  2. Select the name of the snapshot you want to apply or remove.
  3. Click OK to apply the snapshot or Remove to remove the snapshot.

• If you want remove all snapshots, select Clear Snapshots.

Choosing profiling information columns

You can specify which information to display in the Execution Statistics view. You can also change the order in which the columns are displayed. By default, the following columns are displayed:

• CPU — The time in seconds this action has been executing.
• Cumulative — The time in seconds spent in this action and all its child actions.
• Idle — The time in seconds this context has been idle, waiting for events.

1. In the Execution Statistics view, click the View menu button [] and select Choose columns. The Choose Columns dialog appears.

2. Add a check to the check boxes that correspond to the columns you want to display.

3. Click OK.

The Execution Statistics view is updated to show all the selected the columns.

Updating profile data

By default, the Apama profiler polls for data every 10 seconds and then updates the display in the Execution Statistics view.

You can change the polling frequency in the Apama preferences, using the Refreshing views option. You can also change the way the profiler updates the data from a polling mode (the so-called automatic refresh) to an on-demand mode (the so-called manual refresh). For more information, see the description of the Apama preferences page Profiling and Logging.

Info

You can directly access the appropriate Apama preferences page by clicking the Preferences button () in the Profiling Monitor view.

Displaying Apama perspective preferences

By default, when you launch a profiling session, the Confirm Perspective Switch dialog is shown asking if you want to switch to the Apama Profiler perspective. You can change this behavior in the Apama preferences. For more information, see the description of the Apama preferences page Profiling and Logging.

Info

You can directly access the appropriate Apama preferences page by clicking the Preferences button () in the Profiling Monitor view.