wxparaver Quick Reference

Main window

Overview

The main window centralizes most of the information of files, windows and their properties. The main window also allows navigating the main functionalities by the means of menus and buttons.

Every window is identified and their properties can be modified. The main window also allows creating/selecting/combining timelines or histograms.

The following image represents the main window during an analysis session:

The general arrangement of the different sections is as follows: at the top there's a menu bar and a button bar; below them there's the “Workspaces” section and the “Window browser” section and the “Files & Window Properties” section.

<<

Menu bar

The menus and their entries follow general rules. They're separated by areas; some of them have associated shortcuts; others, ending with “...”, tells you that a dialog will be opened; those showing an arrow pointing to the right open submenus.

There are 3 menus, “File”, “Hints” and “Help”. Menu “Hints” may appear disabled if there's no loaded trace.

If you click the menu “File” what you get is:

Basically, the menu entries let the analyst load/unload traces, load Paraver Configuration Files (analysis views constructed as combinations of timelines or histograms), or load/save Sessions (a global analysis state snapshot). Also the user will be able to change the main wxParaver settings with Preferences.

Under “Hints” you'll find a two-level structure of menus related to your your current enabled Workspaces. The second level contains the analysis hints for it. In the example below, you see that only the MPI workspace is enabled.

Finally, the “Help” menu unfolds to the documentation and credits windows:

<<

Main buttons bar

The main buttons appear grouped in three areas: windows creation, windows destruction and utilities, as shown below.

The first three buttons create single, derived timelines and histograms, the button with a red cross icon destroys the current selected window. Finally, the last two buttons open dialogs in order to cut/filter your trace or execute other tools.

<<

Workspaces

Workspaces are sets of the most useful analyses and views and can be enabled or disabled at user request. Their state modify the “Hints” menu next time it's opened.

In the image below there are two active workspaces. The selection can be changed manually by clicking on the right button.

<<

Window browser

It provides information about the available windows for the selected trace.

The current trace is shown in the trace combo box. Changing the selector will show the windows for the new selected trace into the below windows section. Initially it may be empty if no window has been created or no configuration file has been loaded yet for that trace.

The icons on the left of every window entry describe the type of window. In the figure above there are:

Clicking on a timeline or a histogram entry selects it. Then, it's surrounded with a grey square (in the example image, “MPI call” timeline appears this way), their properties are fed back into the properties section and if the window itself is currently open, it rises.

Double-click instead shows/hides that window. Notice that being hidden is different from being destroyed (with the button with a red cross icon in the main buttons bar). If you destroy a window then you'll have to create it again if needed, while a hidden window remains loaded.

The tool also allows drag and drop operation picking one timeline into another to create a derived timeline, as if the second button seen in the previous Main icons bar section was clicked. The derived timeline dialog will be open.

Also, right click in a timeline or a histogram entry will open their popup menus.

<<

Files & Window Properties

The last section of the main window is used for two different purposes. These purposes are as a file browser and as a property editor of the current selected window.

You can change from one to the other clicking one of the two buttons on the top left. Left button is for files browser and right button is for window properties.

When “Files” button is clicked a simple file browser is shown. It can be used to navigate and double click to load a file. They can be filtered with the bottom selector between CFG files (*.cfg), Trace files (*.prv or *.prv.gz) or both.

When “Window Properties” button is clicked a collection of properties for the current selected window is shown. These properties depends whether it's a timeline, a derived timeline or a histogram. Every time another window's selected its properties are shown.

The following image depicts the properties of a single timeline:

This one is for the properties of a histogram window:

The properties are grouped under subsections that you can fold/unfold.

Every subsection contains a list of properties, with their names to the left and their values to the right. If you compare the two images above, for the timeline and the histogram, you'll see how fields and sections are varying depending on the type of window.

The value of a property can be changed by clicking into the right side of the property. Some properties get the data with text boxes, others from lists of values and others open intermediate dialogs.

When the value of a property is modified, the changes are brought inmediately to the window, so it would be recomputed again if needed.

<<

Main Buttons

There's a reduced set of main buttons in wxparaver focused on the main actions: create windows and invoke utilities/external tools.

They're basically divided between the main window and the histogram window.

Main Window

<<

Histogram

<<

Shortcuts Keys

Overview

Using shortcuts keys in wxparaver is a good way to improve your productivity. As you'll see, most of them are generic for many applications, so probably you won't need any special effort to get used with them.

Some of the shortcut keys may vary depending on your operative system. This reference is written for GNU/Linux, so variations will explicitly tell for which OS happens. It's also possible that your desktop/virtual machine had them assigned. Current version of wxparaver can't override them.

Menus

The navigation through menus is done with the arrow keys and the Home/End keys, both for the main menu in the main window and for the contextual menus of timelines and histograms (after right click inside them).

<<

Dialogs and Fields

The interaction with wxparaver dialogs follow the usual dialog standards: Tab to move to next field, Space or Enter to change checkboxes or radiobuttons, and common textbox edition.

<<

Main Window Shortcut Keys

They mainly manage the dialogs for handling sessions and opening traces.

<<

Timeline Shortcut Keys

<<

Histogram Shortcut Keys

<<

(*) After "Ctrl+C", "Ctrl+V" can be applied to the same kind of window as well as from timelines to histograms, and vice versa.

Objects Selection

Objects selection window

The objects selection window can be shown clicking the mouse right button both from timeline or histogram windows. The following pop-up menu is then shown:

After clicking the "Select Objects" option, the symbolic information about objects is shown in a selection dialog.

wxparaver reads these symbolic information from the .row file. It usually contains the names for the levels contained in the trace.

This dialog allows objects selection at available levels, separated in different tabs. They can be all checked/unchecked at the same time with buttons "Select All" and "Unselect All", or use "Invert" to swap checked/unchecked states.

A quick way to perform complex selection is by using the "Add checks by objects matching" box. After clicking the "Apply" button, the objects matching the regular expression written in the textbox will be checked.

All the selections or changes are cumulative. It is specially useful when we want a complex selection that can only be done by combining more than one regular expression. Then, just apply them one by one: write the first expression, click on the "Apply" button, and carry on with next expression. Of course, in any step it's possible to swap between Posix and Quick form for less or more general selections, or select some objects by directly clicking on them.

<<

Objects default labelling

The objects default naming convention in EBNF is as follows:

1. id = [1-9][0-9]*
2. node = id
3. cpu = id
4. appl = id
5. task = id
6. thread = id
7. resource_hierarchy_label = "SYSTEM" | "NODE ", node | "CPU ", node, ".", cpu
8. process_hierarchy_label = "WORKLOAD" | "APPL ", appl | "TASK ", appl, ".", task | "THREAD ", appl, ".", task, ".", thread
9. label = resource_hierarchy_label | process_hierarchy_label

No id level starts with 0. Some valid labels are: "TASK 2.24", "NODE 4", etc. The multilevel numeric suffix references the upper levels index in the defined hierarchy, i.e: "TASK 2.8" is task 8 of application 2, "THREAD 1.2.16" is the 16th thread of task 2 from the application 1.

Most of the times, in the instrumentation phase, Extrae can gather object names and properly label every object for all these levels. If it isn't able, then it will just apply this default labelling. Also, in analysis phase, if the .row file is missing, wxparaver will apply it.

<<

Objects selection using regular expressions

It uses by default the Quick Form, a subset of Posix basic regular expression adapted to our object name conventions, mainly around dot selection and repetitive metachars like '*','+' or '?'. It widely covers the most common selection expressions. For more specific and complex selections that this form can't express, the second option is to directly use Posix Form (Posix basic regular expressions). It can be selected checking "Match as Posix Regular Expression" option. To see how they work, you can find a table with some examples below.

Quick form:

Posix basic regular expression form:

One important issue is about the presence of spaces at the end of this regular expression when writing in the textbox. Given that in some cases we explicitly want them, they're never trimmed, so it's important to be aware of that because they may totally change the selection.

<<

Examples

The following examples compare Quick and pure Posix forms to highlight their differences. The same expressions are written for both of them. It shows how the Quick form is more compact in most of the use cases.

Some results can be matched in many ways (denoted by 'or'). Others can only be done by combining more than one expression (denoted with 'then').

Also note that when writing a 3-level expression it only can refer to threads matching them in an unique way. Nevertheless a 2-level one can match some labels at two levels, like, i.e, Quick form('1.*') matches 'THREAD 1.2.3' at app-task level but also matches 'THREAD 2.1.4' at task-thread level. Using parts of the string like 'THREAD', adding levels separator '.'/'[.]' (depending on Quick/Posix Form) or end of line '$' can solve these ambiguities.

Finally, an example is given to illustrate the existence of Posix Form regex without a compact translation to Quick Form. That happens due to the redefinition of iterative metacharacters {'*','?','+'}, changing their meaning from repetition of preceeding expressions to repetition of any numeric or alphanumeric, more general and handy but less detailed.

Examples:

<<