Filtering in Intel® Trace Collector applies specified filters to the trace collection process. This directly reduces the amount of data collected. The filter rules can be defined in a configuration file, in the environment variables or as command line arguments (see Configuring Intel® Trace Collector
for details). Filters are evaluated in the order they are listed, and all matching is case-insensitive. For filtering by collective and point-to-point MPI operations the corresponding
options are also available.
In the following discussion, items within angle brackets (
) are placeholders for actual values, optional items are put within square brackets (
), and alternatives are separated by a vertical bar
Filtering by Collective and P2P Operations
Use the following
options at runtime:
– to collect information only about collective operations
– to collect information only about point-to-point operations
These options are mutually exclusive, use only one option at a time.
An example command line for tracing collective operations may look as follows:
$ mpirun -trace -n 4 -trace-collectives ./myApp
These options are special cases of filtering by specific functions discussed below. They use predefined configuration files to collect the appropriate operation types. The options override the
environment variable, so you cannot use your own configuration files when using them. If you need to set additional filters, you can set them through individual environment variables.
Filtering by Specific Functions
Function filtering is accomplished by defining the
options. Each option accepts the pattern matching the filtered function, and the filtering rule. The formal definition is as follows:
STATE|SYMBOL|ACTIVITY <PATTERN> <RULE>
The general option is
are its replacers:
filters functions by their names, regardless of the class. The following definitions are considered equal:
SYMBOL <PATTERN> <RULE>
STATE **:<PATTERN> <RULE>
filters functions by their class names. The following definitions are considered equal:
ACTIVITY <PATTERN> <RULE>
STATE <PATTERN>:* <RULE>
can filter functions both by names and their class names.
Pattern should match the name of the function for filtering. You can use the following wildcards:
Any number of characters, excluding ":"
Any number of characters, including ":"
For example the following definition will filter out all functions containing the word
, regardless of the class:
STATE **send* OFF
The basic filter rule should contain one of the following entries:
<RULE> = ON | OFF | <trace level> | <skip level>:<trace level>
value defines how far up the call stack is traced. The
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
turns on tracing with a
turns off tracing completely (this is
In the example below the following events will be traced: all functions in the class
, all MPI
, and all
functions. All other MPI functions will not be traced.
# disable all MPI functions
ACTIVITY MPI OFF
# enable all send functions in MPI
STATE MPI:*send ON
# except MPI_Bsend
SYMBOL MPI_bsend OFF
# enable receive functions
SYMBOL MPI_recv ON
# and all test functions
SYMBOL MPI_test* ON
# and all wait functions, tracing four call levels
SYMBOL MPI_wait* 4
# enable all functions within the Application class
ACTIVITY Application 0
Advanced Function Filtering
For function filtering a finer control is also available. Here is a list of additional filter rule entries, which can be used along with the basic rule in any combination:
<ENTRYTRIGGER> | <EXITTRIGGER> | <COUNTERSTATE> | <FOLDING> | <CALLER>
Here is the specification for each filter entry available:
<ENTRYTRIGGER> = entry <TRIGGER>
<EXITTRIGGER> = exit <TRIGGER>
Activate a trigger on entry/exit for the matching pattern.
<TRIGGER> = [<TRIPLET>] <ACTION> [<ACTION>]
Triggers define a set of actions over a set of processes (triplets, see
Filtering by Ranks
below for definition).
<ACTION> = traceon | traceoff | restore | none | begin_scope <SCOPE_NAME> | end_scope <SCOPE_NAME>
The action defines what happens to tracing. Using
turns tracing on or off, respectively.
start or end the named scope.
<SCOPE_NAME> = [<class name as string>:]<scope name as string>
<COUNTERSTATE> = counteron | counteroff
Counter state 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 disables tracing of any functions called by that function. By default, all functions are unfolded.
<CALLER> = caller <PATTERN>
Specifying the caller enables tracing only for functions called by the functions matching the pattern.
Besides filtering by functions, you can also filter the trace data by ranks in
configuration option. Its value is a comma separated list of Fortran 90-style triplets. The formal definition is as follows:
PROCESS <TRIPLET>[,<TRIPLET>,...] on | off
Triplet definition is as follows:
<TRIPLET> = <LOWER-BOUND>[:<UPPER-BOUND>[:<INCREMENT>] ]
The default value for
is the size of
) and the default value for
For example, to trace only even ranks and rank 1 use the following triplets:
is the total number of processes. All processes are enabled by default, so you have to disable all of them first (
PROCESS 0:N OFF
) before enabling a certain subset again. For SMP clusters, you can also use the
option to filter for particular SMP nodes.