Provided by: tau_2.16.4-1.5_amd64 bug

NAME

       tau_reduce - generates selective instrumentation rules based on profile data

SYNOPSIS

       tau_reduce {-f filename} [-n] [-r filename] [-o filename] [-v] [-p]

DESCRIPTION

       tau_reduce is an application that will apply a set of user-defined rules to a pprof dump
       file (pprof -d) in order to create a select file that will include an exclude list for
       selective implementation for TAU. The user must specify the name of the pprof dump file
       that this application will use. This is done with the -f filename flag. If no rule file is
       specified, then a single default rule will be applied to the file. This rule is: numcalls
       > 1000000 & usecs/call < 2, which will exclude all routines that are called at least
       1,000,000 times and average less then two microseconds per call. If a rule file is
       specified, then this rule is not applied. If no output file is specified, then the results
       will be printed out to the screen.

RULES

       Users can specify a set of rules for tau_reduce to apply. The rules should be specified in
       a separate file, one rule per line, and the file name should be specifed with the
       appropriate option on the command line. The grammar for a rule is: [GROUPNAME:]FIELD
       OPERATOR NUMBER. The GROUPNAME followed by the colon (:) is optional. If included, the
       rule will only be applied to routines that are a member of the group specified. Only one
       group name can be applied to each rule, and a rule must follow a groupname. If only a
       groupname is given, then an unrecognized field error will be returned. If the desired
       effect is to exclude all routines that belong to a certain group, then a trivial rule,
       such as GROUP:numcalls > -1 may be applied. If a groupnameis given, but the data does not
       contain any groupname data, then then an error message will be given, but the rule will
       still be applied to the date ignoring the groupname specification. A FIELD is any of the
       routine attributes listed in the following table:

       ATTRIBUTE NAME     MEANING
       numcalls           Number of times the routine is called
       numsubrs           Number of subroutines that the routine contains
       percent            Percent of total implementation time
       usec               Exclusive routine running time, in microseconds
       cumusec            Inclusive routine running time, in microseconds
       count              Exclusive hardware count
       totalcount         Inclusive hardware count
       stddev             Standard deviation
       usecs/call         Microseconds per call
       counts/call        Hardware counts per call

       Some FIELDS are only available for certain files. If hardware counters are used, then
       usec, cumusec, usecs/per call are not applicable and a error is reported. The opposite is
       true if timing data is used rather than hardware counters. Also, stddev is only available
       for certain files that contain that data.

       An OPERATOR is any of the following: < (less than), > (greater than), or = (equals).

       A NUMBER is any number.

       A compound rule may be formed by using the & (and) symbol in between two simple rules.
       There is no "OR" because there is an implied or between two separate simple rules, each on
       a separate line. (ie the compound rule usec < 1000 OR numcalls = 1 is the same as the two
       simple rules "usec < 1000" and "numcalls = 1").

RULE EXAMPLES

       #exclude all routines that are members of TAU_USER and have less than
       #1000 microseconds
       TAU_USER:usec < 1000

       #exclude all routines that have less than 1000 microseconds and are
       #called only once.
       usec < 1000 & numcalls = 1

       #exclude all routines that have less than 1000 usecs per call OR have a percent
       #less than 5
       usecs/call < 1000
       percent < 5

       NOTE: Any line in the rule file that begins with a # is a comment line. For clarity, blank
       lines may be inserted in between rules and will also be ignored.

OPTIONS

       -f filename specify filename of pprof dump file

       -p print out all functions with their attributes

       -o filename specify filename for select file output (default: print to screen

       -r filename specify filename for rule file

       -v verbose mode (for each rule, print out rule and all functions that it excludes)

EXAMPLES

       To print to the screen the selective instrumentation list for the paraprof dump file
       app.prf with default selection rules use:

       tau_reduce -f app.prf

       To create a selection file, app.sel, from the paraprof dump file app.prf using rules
       specified in foo.rlf use:

       tau_reduce -f app.prf -r foo.rlf -o app.sel

SEE ALSO

                                            12/22/2005                              TAU_REDUCE(1)