Tuning and Analysis Utilities

TAU allow the users to select which functions to profile within a single application. One way the user can selectively instrument an application is by specifying rules which govern which functions should be profiled.

TAU's automatically throttles short running functions in an effort to reduce the amount of overhead associated with profile such functions. This feature may be turned off by setting the environment variable TAU_THROTTLE to 0. The default rules TAU uses to determine which functions to throttle is: numcalls > 100000 && usecs/call < 10 which means that if a function executes more than 100000 times and has an inclusive time per call of less than 10 microseconds, then profiling of that function will be disabled after that threshold is reached. To change the values of numcalls and usecs/call the user may optionally set environment variables:

% setenv TAU_THROTTLE_NUMCALLS 2000000
% setenv TAU_THROTTLE_PERCALL  5
  

to change the values to 2 million and 5 microseconds per call.

For more control over selective instrumentation use the tool "tau_reduce". See tau_reduce. or Section 16.3, “Selective Instrumentation File Generator”

TAU allows you to customize the instrumentation of a program by using a selective instrumentation file. This instrumentation file is used to manually control which parts of the application are profiled and how they are profiled. If you are using tau_compiler.sh to instrument your application you can use the -optTauSelectFile=<file> option to enable selective instrumentation.

Both Memory and IO events are represented along with their call-stack, the length of which can the set with environment variable TAU_CALLPATH_DEPTH.

There are wildcards (#, *, ?) that can be used when specifying a file or routine.For file names * character can be used to specify any number of character, thus foo* matches foobar, foo2, etc. also for file names ? can match a single character, ie. foo? matches foo2, fooZ, but not foobar. You can use # as a wildcard for routines, ie. b# matches bar, b2z etc. Example:

#Tell tau to not profile these functions
BEGIN_EXCLUDE_LIST

void quicksort(int *, int, int)
# The next line excludes all functions beginning with "sort_" and having arguments
# "int *"
void sort_#(int *)
void interchange(int *, int *)

END_EXCLUDE_LIST

#Exclude these files from profiling
BEGIN_FILE_EXCLUDE_LIST

*.so

END_FILE_EXCLUDE_LIST

Within the BEGIN_INSTRUMENT_SECTION / END_INSTRUMENT_SECTION tags you can also insert code fragment within the source code by specifying the file and line number, for example:

file = "line_test.cpp" line = 9 code = "printf(\"i=%d: \", i);"
			

You may want to add code at the entry and exit of a particular routine, for example:

exit routine ="int foo()" code = "cout <<\"exiting foo\"<<endl;"
entry routine ="int foo()" code = "cout <<\"entering foo\"<<endl;"
			

You can also insert code at initialization (at the beginning of main for C/C++ and at the start of program for Fortran.) You can also insert code before a function's first statement is executed. For example:

init code="int i = 0;" lang="C"
decl file="bar.C" routine="foo" code="int j;" lang="C++"
			

Furthermore you can use the following substitutions: