• 2019 Update 3
  • 03/07/2019
  • Public Content
  • Download as PDF
Contents

Filtering by Specific Functions

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
mpirun
/
mpiexec
options are also available.
In the following discussion, items within angle brackets (
<
and
>
) are placeholders for actual values, optional items are put within square brackets (
[
and
]
), and alternatives are separated by a vertical bar
|
.
Filtering by Collective and P2P Operations
Use the following
mpirun
/
mpiexec
options at runtime:
  • -trace-collectives
    – to collect information only about collective operations
  • -trace-pt2pt
    – to collect information only about point-to-point operations
Note
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
VT_CONFIG
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.

Basic Function Filtering

Function filtering is accomplished by defining the
STATE
,
SYMBOL
and
ACTIVITY
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
STATE
, while
SYMBOL
and
ACTIVITY
are its replacers:
  • SYMBOL
    filters functions by their names, regardless of the class. The following definitions are considered equal:
    SYMBOL <PATTERN> <RULE> STATE **:<PATTERN> <RULE>
  • ACTIVITY
    filters functions by their class names. The following definitions are considered equal:
    ACTIVITY <PATTERN> <RULE> STATE <PATTERN>:* <RULE>
  • STATE
    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:
Wildcard
Description
*
Any number of characters, excluding ":"
**
Any number of characters, including ":"
?
A single character
[ ]
A list of characters
For example the following definition will filter out all functions containing the word
send
, 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>
The
<trace level>
value defines how far up the call stack is 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
turns on tracing with a
<trace level>
of
1
and a
<skip level>
of
0
, and
OFF
turns off tracing completely (this is
not
equivalent to
0: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:

Filtering by Ranks

Besides filtering by functions, you can also filter the trace data by ranks in
MPI_COMM_WORLD
using the
PROCESS
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
<UPPER-BOUND>
is the size of
MPI_COMM_WORLD
(
N
) and the default value for
<INCREMENT>
is
1
.
For example, to trace only even ranks and rank 1 use the following triplets:
0:N:2,1:1:1
, where
N
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
CLUSTER
option to filter for particular SMP nodes.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804