Intel® Trace Collector Filtering

Filtering in the Intel® Trace Collector will apply specified filters to the trace collection process.  This directly reduces the amount of data collected.  The filter rules can be applied either via command line arguments or in a configuration file (specified by the environment variable VT_CONFIG).  Filters are evaluated in the order they are listed.

Filter Specification

Filters consist of three components, type, pattern, and body.  The basic filter is of type STATE.  The other types, SYMBOL and ACTIVITY, apply pattern replacements, but are otherwise identical to STATE.

Patterns are specified by class name and symbol name, separate by a colon.  Certain wildcards may be used.  The pattern matching is case-insensitive.

The patterns for SYMBOL and ACTIVITY type filters are modified as shown:

The filter body defines what to do with the entities specified.  This uses the following format:

<SCLRANGE> = on | off | <trace level> | <skip level>:<trace level>

The <trace level> value defines how far up the call stack will be traced.  The <skip level> value defines how many levels to skip while going up the call stack.  This is useful if a function is called within a library, and the library stack can be ignored.  Specifying ON will turn on tracing with a <trace level> of 1 and a <skip level> of 0 for the entities, and OFF will turn off tracing completely (this is NOT equivalent to 0:0).

Examples

Filter out all MPI calls except the various MPI send routines:

ACTIVITY MPI OFF

STATE MPI:*send ON

Trace all MPI functions (this is the default), but show 3 levels of the call tree for MPI_Bcast functions

SYMBOL MPI_Bcast 3

Command Line Equivalents

These filter options are available on the command line by using equivalent command line options

Filtering by Process Ranks

To filter by process ranks, add the following line to the configuration file

PROCESS <TRIPLET>[,<TRIPLET>,...] on | off

<TRIPLET> = <LOWER BOUND>[:<UPPER BOUND>[:<INCREMEMT>] ]

The default value of <UPPER BOUND> is the size of MPI_COMM_WORLD and the default value of INCREMENT is 1.  By default, all processes are enabled.  The rank number corresponds to the MPI_COMM_WORLD communicator.

Additional Filtering Control

Finer-level filtering control may be available if the platform supports it.  These are entered in the body of the filter line.  Multiple rules can be entered as a comma-separated list in the body section, but each type of rule may only appear once in a section.

<RULEENTRY> = <SCLRANGE> | <ENTRYTRIGGER> | <EXITTRIGGER> | <COUNTERSTATE> | <FOLDING> | <CALLER>

<ENTRYTRIGGER> = entry <TRIGGER>

<EXITTRIGGER> = exit <TRIGGER>

Activate <TRIGGER> on entry/exit for the matching pattern.

<TRIGGER> = [<TRIPLET>] <ACTION> [<ACTION>]

Triggers define a set of actions over a set of processes.

<ACTION> = traceon | traceoff | restore | none | begin_scope <SCOPE_NAME> | end_scope <SCOPE_NAME>

The action defines what happens to tracing.  Using traceon or traceoff will turn tracing on or off respectively.  begin_scope and end_scope will start or end the named scope.

<SCOPE_NAME> = [<class name as string>:]<scope name as string>

A scope is a user-defined region in the program.  Scopes can overlap each other.

<COUNTERSTATE> = counteron | counteroff

The counterstate turns on or off sampling for the matching pattern.  By default all enabled counters are sampled at every state change.  There is no method for controlling which counters are sampled.

<FOLDING> = fold | unfold

Enabling folding for a function will disable tracing of any functions called by that function.  By default, all functions are unfolded.

<CALLER> = caller <PATTERN>

Caller is used to provide additional criteria for function matching.  The specified body rule will only be applied if the caller matches the specified <PATTERN>.