Chapter 2. TAU Instrumentation Options

2.1. Selective Instrumentation Options

Selective Instrumentation File Specification. The selective instrumentation file has the following sections, each preceded and followed by:

BEGIN_EXCLUDE_LIST / END_EXCLUDE_LIST or BEGIN_INCLUDE_LIST / END_INCLUDE_LIST

exclude/include list of routines and/or files for instrumentation. The list of routines to be excluded from instrumentation is specified, one per line, enclosed by BEGIN_EXCLUDE_LIST and END_EXCLUDE_LIST. Instead of specifying which routines should be excluded, the user can specify the list of routines that are to be instrumented using the include list, one routine name per line, enclosed by BEGIN_INCLUDE_LIST and END_INCLUDE_LIST.

BEGIN_FILE_EXCLUDE_LIST / END_FILE_EXCLUDE_LIST or BEGIN_FILE_INCLUDE_LIST / END_FILE_INCLUDE_LIST

Similarly, files can be included or excluded with the BEGIN_FILE_EXCLUDE_LIST, END_FILE_EXCLUDE_LIST, BEGIN_FILE_INCLUDE_LIST, and END_FILE_INCLUDE_LIST lines.

BEGIN_INSTRUMENT_SECTION / END_INSTRUMENT_SECTION

Manually editing the selective instrumentation file gives you more options. These tags allow you to control the type of instrumentation performed in certain portions of your application.

  • Static and Dynamic timers can be set by specifying either a range of line numbers or a routine.

    static timer name="foo_bar" file="foo.c" line=17 to line=18
    dynamic timer routine="int foo1(int)
                  
  • Static and Dynamic phases can be set by specifying either a range of line numbers or a routine. If you do not configure TAU with -PROFILEPHASE these phases will be converted to regular timers.

    static phase routine="int foo(int)
    dynamic phase name="foo1_bar" file="foo.c" line=26 to line=27
                  
  • Loops in the source code can be profiled by specifying a routine in which all loop should be profiled, like:

    loops file="loop_test.cpp" routine="multiply"
                  
  • With Memory Profiling the following events are tracked: memory allocation, memory deallocation, and memory leaks.

    memory file="foo.f90" routine="INIT"
                  
  • IO Events track the size, in bytes of read, write, and print statements.

    io file="foo.f90" routine="RINB"
                  

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

Selective instrumention can be set at compile time by setting -tau_options=-optTauSelectFile=<file> in the TAU_OPTIONS environment variable when compiling with the TAU compiler wrapper scripts. Alternatively an application can be selectively instrumented at runtime by setting the TAU_SELECT_FILE environment variable to the selective instrumentation file's location in the application's execution environment.

[Note] Note

Due to the limitations of the some compilers (IBM xlf, PGI pgf90, GNU gfortran), the size of the memory reported for a Fortran Array is not the number of bytes but rather the number of elements.