Chapter 5. Dialogs

Apart from the Settings Dialog boxes of each chart, there are a number of other dialog boxes in the Intel® Trace Analyzer. All dialog boxes have the same semantics regarding the buttons OK, Cancel and Apply.

In case the current settings of the dialog boxes are inconsistent or out of bounds, the OK and Apply buttons are both disabled.

5.1. The Filtering Dialog

The filtering dialog box is accessed through the Advanced Menu (Views Menu->Advanced->Filtering) This dialog box allows specifying filter expressions that describe which function events, messages and collective operations are to be analyzed and shown. The two radio buttons in the group Definition of Filter Expression at the top switch between two fundamental modes: Using GUI Interface is chosen by default and allows generating the filter expression via a graphical interface, while Manually allows to type in the filter expression directly. Building the expression with the graphical interface is a lot easier and recommended for beginners or infrequent use.

An expression is built using either the point and click interface or using the manual mode. Either way the resulting expression is parsed upon each change.

If the current expression can not be converted into a proper filter definition then the dialog shows a red warning at the bottom which indicates the reason.

If the expression makes use of filter attributes that require to bypass the in-memory trace cache and to process detailed data from the trace file then a warning message is shown. In this case it can be expected that the analysis using this filter expression will need considerably more time than usual.

5.1.1. Building Filter Expressions Using the Graphical Interface

The Filtering dialog box allows specifying filter expressions separately for function events, messages and collective operations via three separate tabs. It provides a fourth tab labeled Processes to additionally restrict the events to only a subset of processes.

Some of the text fields in the filter dialog box can take triplets that are of the form start:stop:incr or the short form start:stop if the increment is one. Such a triplet describes all numbers greater than or equal to start and smaller than or equal to stop and that are of the form start+incr*n. The stop value is optional, too. When stop is omitted, all numbers beginning from start match.

  • Processes Tab

    This tab specifies the processes that may pass the filter. It has effects on all three sub-expressions.

    The Show Processes text field defines the processes that are filtered according to the settings of the other three tabs. Processes not listed in the text field are filtered out completely unless the text field is empty: this is the default and indicates that the Processes tab has no effect. The text field can take a comma-separated list of process ids, process group ids, triplets thereof, unquoted or double-quoted names of threads, processes or process groups. Names given match all equally named processes/groups.

    The button labeled ... opens the dialog box Process Group Selection where one or more processes or process groups are selected (see below). The Invert check box swaps the selection. For example, if all processes except one pass the filter, select the process to be filtered out and use the check box Invert.

    Checking Invert means to let only events pass that do not match this predicate. It is a logical NOT and shown as a exclamation mark before the predicate in the filter expression.

    Below the filter clauses, the resulting filter expression is shown. To reuse the expression elsewhere, select and copy the expression in the manual mode of the filtering dialog box. The selection is done using the mouse. The context menu of the filter expression contains a Copy (Ctrl+C) entry and a Select All (Ctrl+A) entry.

  • Functions

    In the Functions tab, the mode of filtering is selected by means of radio buttons - All, None and Custom.

    Again, on selecting the Custom radio button, the filter clause tab is enabled. This consists of the following entries:

    Functions: The text field can take a comma-separated list of functions or function group ids, triplets thereof, unquoted or double-quoted names of functions or function groups that describe functions passing the filter. Names given match all equally named functions/groups. The button ... opens the Function Group Selection subdialog which allows choosing the function names from a list. In addition, the subdialog provides a checkbox Add Function Id: if checked, not only is the name of a selected function written into the text field, but also its Id. This is useful to resolve ambiguities of function/group names: if only the name is written into the text field, all functions with this name pass the filter; if the name is replaced by an id, only the function with this id passes the filter, not other functions with the same name.

    Processes: The text field can take a comma-separated list of process ids, process group ids, triplets thereof, unquoted or double-quoted thread, process or process group names that describe processes and threads in the functions passing the filter. Names given match all equally named processes/groups. The button ... allows choosing from a list. The corresponding Process Group Selection subdialog provides a checkbox Add Process Id which is similar to the above Function Group Selection subdialog.

    Figure 5-1. Function group selection opened via the filter dialog box

    The button Add New Clause specifies another filter clause. To remove an existing filter clause tab, use the Remove Current Clause button. Clauses are connected by a logical OR, while attributes from the same tab are connected by a logical AND; they form a so-called And Clause.

  • Messages

    On selecting the Custom radio button (see Figure 5-1), the filter clause tab in the Messages tab is enabled. It has the following entries:

    Communicator: The text field can take a comma-separated list of communicator ids, unquoted communicator names or communicator names in double quotes that pass the filter. The button ... allows choosing from a list.

    Tag: The text field can take a comma-separated list of non-negative integers and triplets that describe tag values that pass the filter.

    Message Size: The text field can take a comma-separated list of non-negative integers and triplets that describe message sizes (in bytes) that pass the filter.

    Sender: The text field can take a comma-separated list of process ids, process group ids, triplets thereof, unquoted or double-quoted names of threads, processes or process groups that describe processes and threads in the message sender that make the message pass the filter. Names given match all equally named processes/groups. The button ... allows choosing from a list.

    Receiver: Analogous to Sender.

    Processes: Makes a message pass the filter if either the sender or the receiver matches. Analogous to the logical OR of Sender and Receiver.

    Ranks of Sender: The text field can take a comma-separated list of non-negative integers and triplets that describe sender ranks (in the MPI communicator) that can pass the filter.

    Ranks of Receiver: Analogous to Rank of Sender.

    Ranks: Makes a message pass if either the sender or the receiver matches. Analogous to the logical OR of Rank of Sender and Rank of Receiver.

    Sending Function: The text field can take a comma-separated list of functions or function group ids, triplets thereof, unquoted or double-quoted names of functions or function groups that describe functions from which the message was sent. Names given match all equally named functions/groups. The button ... allows choosing from a list.

    Receiving Function: The text field can take a comma-separated list of functions or function group ids, triplets thereof, unquoted or double-quoted names of functions or function groups that describe functions which received the sent message. Names given match all equally named functions/groups. The button ... allows choosing from a list.

    Start Time: The text field can take a comma-separated list of non-negative integers and triplets that describe start time (in ticks) of the message that make the operation pass the filter. The button ... allows to enter/edit the time in ticks or seconds (default depending on the View's current time unit).

    End Time: Analogous to Start Time.

    Duration: The text field can take a comma-separated list of non-negative integers and triplets that describe the duration (in ticks) of the message that make the operation pass the filter. The button ... allows to enter/edit the duration (shown as a time interval) in ticks or seconds (default depending on the View's current time unit).

    Figure 5-2. The filtering dialog box showing the Messages tab

  • Collective Operations

    On selecting the Custom radio button the filter clause tab in the Messages tab is enabled. It has the following entries:

    Communicator: The text field can take a comma-separated list of communicator ids, unquoted communicator names or communicator names in double quotes that pass the filter. The button ... allows choosing from a list.

    Collective Operation: The text field can take a comma-separated list of unquoted or double-quoted names of collective operations like "MPI_Allreduce" that pass the filter. The button ... allows choosing from a list.

    Transferred Volume: The text field can take a comma-separated list of non-negative integers and triplets that describe all volumes (in total bytes per operation) that make a collective operation make pass the filter.

    Processes: The text field can take a comma-separated list of process ids, process group ids, triplets thereof, unquoted or double-quoted names of threads, processes or process groups that describe processes and threads participating in the operation that make the operation pass the filter. Names given match all equally named processes/groups. The button ... allows choosing from a list.

    Root: The text field can take a comma-separated list of process ids, process group ids, triplets thereof, unquoted or double-quoted names of threads, processes or process groups that describe processes and threads serving as Root in the operation that make the operation pass the filter. Names given match all equally named processes/groups. The button ... allows choosing from a list.

    Rank of Root: The text field can take a comma-separated list of non-negative integers and triplets that describe root ranks of the operation that make the operation pass the filter.

    Start Time: The text field can take a comma-separated list of non-negative integers and triplets that describe start time (in ticks) of the operation that make the operation pass the filter. The button ... allows to enter/edit the time in ticks or seconds (default depending on the View's current time unit).

    End Time: Analogous to Start Time.

    Duration: The text field can take a comma-separated list of non-negative integers and triplets that describe the duration (in ticks) of the operation that make the operation pass the filter. The button ... allows to enter/edit the duration (shown as a time interval) in ticks or seconds (default depending on the View's current time unit).

5.1.2. Building Filter Expressions Manually

Manual mode allows constructing any filter expression that is valid as described by the expression grammar in Section 5.1.3.

Note that for convenience there are context menu entries that allow to select processes, functions, communicators and collective operations from a dialog box in the same way as from the point and click interface and to insert them into the expression at the current cursor position.

The percentage sign (%) inserts single line comments and there are context menu entries to comment out (or in) selected text blocks.

There is no operator precedence in the Intel Trace Analyzer; the expressions are evaluated from left to right. However, you can use parentheses if needed.

Figure 5-3. The Filtering dialog box in manual mode showing its context menu

5.1.3. The Filter Expression Grammar

The filter expression grammar creates a filter, which a set of function (funcfilter), message (p2pfilter), and collective operation (collfilter) filters, each defining a filter for its respective kind of data. These sub-filter specifications are separated by a # and come in any order. Each filter class is specified once, more than once (in which case a Boolean AND is created from all subfilters for a given class), or not specified at all. An example where three classes of filters are specified is the expression generated by the graphical interface.

Each filter class specifier (funcfilter, p2pfilter, or collfilter) is followed by an expression put in parentheses. That expression can consist of any number of predicates that are different for each filter class and correspond to the entries described in Section 5.1.1. (See a formal description of the grammar in Section 5.1.3.1.) These predicates are joined by using Boolean AND (&&) and OR (||) operators. Boolean expressions are parenthesized as needed. Also, a Boolean NOT (!) operator in front of any predicate or parenthesized expression negates the predicate/expression.

A filter class allows defining a special expression for a filter that lets all or no data of that kind pass through it. For example, p2pfilter(NONE) filters out all messages, while collfilter(ALL) lets all collective operations pass. When the keywords ALL or NONE are used, ensure that it is the only argument to funcfilter, p2pfilter, or collfilter.

Keyword specification in the filter expression grammar is case-insensitive. Specifying names (for functions, processes and communicators, amongst others), however, is case-sensitive. Double quotes are needed for names that consist of several words or do not start with a letter or an underscore character (for example, "Major Function Groups"). Use double quotes for single word names (for example, MPI) if necessary. White space (space and tab characters, as well as newlines) is ignored, unless it is part of a quoted name. If a process/group or function/group name is ambiguous then it is evaluated as if all matching groups were given.

5.1.3.1. A Formal Description of the Grammar

Here is a formal description of the filter expression grammar:


# The filter itself

FILTER ::= AFILTER
      | FILTER # AFILTER

AFILTER ::= funcfilter ( FUNCFILTARG )
       | collfilter ( COLLFILTARG )
       | p2pfilter ( P2PFILTARG )

# Specifying functions

FUNCFILTARG ::= FUNCEXPR
           | all
           | none

FUNCEXPR ::= FUNCATOM
        | FUNCEXPR && FUNCATOM
        | FUNCEXPR || FUNCATOM

FUNCATOM ::= TG
        | FG
        | STARTTIME
        | ( FUNCEXPR )
        | ! FUNCATOM

# Specifying messages

P2PFILTARG ::= P2PEXPR
          | all
          | none

P2PEXPR ::= P2PATOM
       | P2PEXPR && P2PATOM
       | P2PEXPR || P2PATOM

P2PATOM ::= DURATION
       | COMM
       | TAG
       | P2PVOLUME
       | TGSENDER
       | TGRECEIVER
       | COMMSENDER
       | COMMRECEIVER
       | TGSRPAIR
       | COMMSRPAIR
       | TG
       | COMMSR
       | STARTTIME
       | ENDTIME
       | SENDER_FG
       | RECEIVER_FG
       | ( P2PEXPR )
       | ! P2PATOM

# Specifying collective operations

COLLFILTARG ::= COLLEXPR
           | all
           | none

COLLEXPR ::= COLLATOM
        | COLLEXPR && COLLATOM
        | COLLEXPR || COLLATOM

COLLATOM ::= DURATION
        | COMM
        | COLLOPTYPE
        | COLLVOLUME
        | TGROOT
        | COMMROOT
        | TG
        | STARTTIME
        | ENDTIME
        | ( COLLEXPR )
        | ! COLLATOM

# Specifying times

STARTTIME ::= start ( TRIPLETS ; INTEGER )
         | start ( TRIPLETS )

ENDTIME ::= end ( TRIPLETS ; INTEGER )
       | end ( TRIPLETS )

DURATION ::= duration ( TRIPLETS )

# Specifying TGroups and FGroups

TG ::= tg ( NAMES )

FG ::= fg ( NAMES )

SENDER_FG ::= send_fg ( NAMES )

RECEIVER_FG ::= recv_fg ( NAMES )

# Specifying collective operation and message properties

COMM ::= comm ( TRIPLETS )

TAG ::= tag ( TRIPLETS )

COLLOPTYPE ::= type ( COLLNAMES )

COLLVOLUME ::= volume ( TRIPLETS )

P2PVOLUME ::= volume ( TRIPLETS )

# Specifying root, sender, or receiver, either by a TGroup name
# or by position in the communicator. If the operation has no
# root, then root() is always false.

TGROOT ::= root ( NAMES )

TGSENDER ::= sender ( NAMES )

TGRECEIVER ::= receiver ( NAMES )

# The predicate sr specifies both sender and receiver, separated by a semicolon.

TGSRPAIR ::= sr ( NAMES ; NAMES )

COMMROOT ::= root@ ( TRIPLETS )

COMMSENDER ::= sender@ ( TRIPLETS )

COMMRECEIVER ::= receiver@ ( TRIPLETS )

# The predicate sr@ specifies both sender and receiver ranks, separated by a semicolon.

COMMSRPAIR ::= sr@ ( TRIPLETS ; TRIPLETS )

COMMSR ::= tg@ ( TRIPLETS )

# Names containing fancy characters have to be double-quoted.
# Names map to TGroup and thread names, FGroup and function
# names, or collective operation types, depending on the context.

NAMES ::= NAME
     | TRIPLET
     | NAMES , NAME
     | NAMES , TRIPLET

COLLNAMES ::= COLLNAMELIST
         | TRIPLETS

COLLNAMELIST ::= NAME
            | COLLNAMELIST , NAME

NAME ::= [_a-zA-Z][_a-zA-Z0-9.]*
    | \"[^\"]*\"

# Specifying triplets and numbers

TRIPLETS ::= TRIPLET
        | TRIPLETS , TRIPLET

TRIPLET ::= INTEGER
       | INTEGER :
       | INTEGER : INTEGER
       | INTEGER : INTEGER : INTEGER

INTEGER ::= [0-9]+

5.1.3.2. Examples of Advanced Usage of the Grammar

This section includes several examples of manually using the filter expression grammar and how it provides advanced capabilities in filtering trace data and speeding up the process of selecting exactly what the user would like to be analyzed.

For the first example, consider a parenthesized structure that can not be built by the point and click interface as easily (messages sent by process 0 and starting or ending between 70000 and 80000 ticks):

p2pfilter( sender( 0 ) && ( start( 70000:80000 ) || end( 70000:80000 ) ) )

The following example uses the predicate sr, which is not available in the point and click interface, to efficiently filter out all messages between processes 0 and 1:

p2pfilter( ! sr( 0:1; 0:1 ) )

Finally, consider the following scenario. With the point and click interface, a complicated filter is specified for a certain filter class with a large number of predicates and Boolean operators (both AND and OR, the latter added by using the Add New Clause button). Now, to negate everything that has been specified so far (that is, to get exactly the trace data that was previously being filtered out), use ! in front of the whole expression when in the manual mode. For example, the filter below specifies MPI_Barrier collective operations that last no longer than 2000 ticks, plus all collective operations with process 0 as the root:

collfilter( type( MPI_Barrier ) && duration( 0:2000 ) || root( 0 ) )

while this filter specifies all the collective operations that do not match the description above:

collfilter( ! ( type( MPI_Barrier ) && duration( 0:2000 ) || root( 0 ) ) )

5.1.4. Filter Expressions in Comparison Mode

In Comparison mode (see Chapter 6) the dialog is extended by a label and a combo box that allows to apply the chosen filter expression to the other trace file shown in the View. Choosing the option "If expression is valid in other file." will check if the resulting expression is valid in the name space of the other file and if so then apply the expression as if you had manually typed it in the other file's filter dialog. Any previous input in the target dialog will be overwritten.