TAU Instrumentation API


Introduction

  • C++

    The C++ API is a set of macros that can be inserted in the C++ source code. An extension of the same API is available to instrument C and Fortran sources.

    At the beginning of each instrumented source file, include the following header

    #include <TAU.h>
    	
  • C

    The API for instrumenting C source code is similar to the C++ API. The primary difference is that the TAU_PROFILE() macro is not available for identifying an entire block of code or function. Instead, routine transitions are explicitly specified using TAU_PROFILE_TIMER() macro with TAU_PROFILE_START() and TAU_PROFILE_STOP() macros to indicate the entry and exit from a routine. Note that, TAU_TYPE_STRING() and CT() macros are not applicable for C. It is important to declare the TAU_PROFILE_TIMER() macro after all the variables have been declared in the function and before the execution of the first C statement.

    Example:

    
    #include <TAU.h>
    
    int main (int argc, char **argv) {
      int ret;
      pthread_attr_t  attr;
      pthread_t       tid;
      TAU_PROFILE_TIMER(tautimer,"main()", "int (int, char **)",
                        TAU_DEFAULT);
      TAU_PROFILE_START(tautimer);
      TAU_PROFILE_INIT(argc, argv);
      TAU_PROFILE_SET_NODE(0);
      pthread_attr_init(&attr);
      printf("Started Main...\n");
      // other statements
      TAU_PROFILE_STOP(tautimer);
      return 0;
    }
          
  • Fortran 77/90/95

    The Fortran90 TAU API allows source code written in Fortran to be instrumented for TAU. This API is comprised of Fortran routines. As explained in Chapter 2, the instrumentation can be disabled in the program by using the TAU stub makefile variable TAU_DISABLE on the link command line. This points to a library that contains empty TAU instrumentation routines.

Timers

  • Static timers

    These are commonly used in most profilers where all invocations of a routine are recorded. The name and group registration takes place when the timer is created (typically the first time a routine is entered). A given timer is started and stopped at routine entry and exit points. A user defined timer can also measure the time spent in a group of statements. Timers may be nested but they may not overlap. The performance data generated can typically answer questions such as: what is the total time spent in MPI_Send() across all invocations?

  • Dynamic timers

    To record the execution of each invocation of a routine, TAU provides dynamic timers where a unique name may be constructed for a dynamic timer for each iteration by embedding the iteration count in it. It uses the start/stop calls around the code to be examined, similar to static timers. The performance data generated can typically answer questions such as:what is the time spent in the routine foo() in iterations 24, 25, and 40?

  • Static phases

    An application typically goes through several phases in its execution. To track the performance of the application based on phases, TAU provides static and dynamic phase profiling. A profile based on phases highlights the context in which a routine is called. An application has a default phase within which other routines and phases are invoked. A phase based profile shows the time spent in a routine when it was in a given phase. So, if a set of instrumented routines are called directly or indirectly by a phase, we'd see the time spent in each of those routines under the given phase. Since phases may be nested, a routine may belong to only one phase. When more than one phase is active for a given routine, the closest ancestor phase of a routine along its callstack is its phase for that invocation. The performance data generated can answer questions such as: what is the total time spent in MPI_Send() when it was invoked in all invocations of the IO (IO => MPI_Send()) phase?

  • Dynamic phases

    Dynamic phases borrow from dynamic timers and static phases to create performance data for all routines that are invoked in a given invocation of a phase. If we instrument a routine as a dynamic phase, creating a unique name for each of its invocations (by embedding the invocation count in the name), we can examine the time spent in all routines and child phases invoked directly or indirectly from the given phase. The performance data generated can typically answer questions such as: what is the total time spent in MPI_Send() when it was invoked directly or indirectly in iteration 24? Dynamic phases are useful for tracking per-iteration profiles for an adaptive computation where iterations may differ in their execution times.

  • Callpaths

    In phase-based profiles, we see the relationship between routines and parent phases. Phase profiles do not show the calling structure between different routines as is represented in a callgraph. To do so, TAU provides callpath profiling capabilities where the time spent in a routine along an edge of a callgraph is captured. Callpath profiles present the full flat profiles of routines (or nodes in the callgraph), as well as routines along a callpath. A callpath is represented syntactically as a list of routines separated by a delimiter. The maximum depth of a callpath is controlled by an environment variable.

  • User-defined Events

    Besides timers and phases that measure the time spent between a pair of start and stop calls in the code, TAU also provides support for user-defined atomic events. After an event is registered with a name, it may be triggered with a value at a given point in the source code. At the application level, we can use user-defined events to track the progress of the simulation by keeping track of application specific parameters that explain program dynamics, for example, the number of iterations required for convergence of a solver at each time step, or the number of cells in each iteration of an adaptive mesh refinement application.

Table of Contents

TAU_START - Starts a timer.
TAU_STOP - Stops a timer.
TAU_PROFILE - Profile a C++ function
TAU_DYNAMIC_PROFILE - dynamic_profile a c++ function
TAU_PROFILE_CREATE_DYNAMIC - Creates a dynamic timer
TAU_CREATE_DYNAMIC_AUTO - Creates a dynamic timer for C/C++
TAU_PROFILE_DYNAMIC_ITER - Creates a dynamic timer in Fortran.
TAU_PHASE_DYNAMIC_ITER - Creates a dynamic phase in Fortran.
TAU_PROFILE_TIMER - Defines a static timer.
TAU_PROFILE_START - Starts a timer.
TAU_PROFILE_STOP - Stops a timer.
TAU_STATIC_TIMER_START - Starts a timer.
TAU_STATIC_TIMER_STOP - Starts a timer.
TAU_DYNAMIC_TIMER_START - Starts a dynamic timer.
TAU_DYNAMIC_TIMER_STOP - Starts a dynamic timer.
TAU_PROFILE_TIMER_DYNAMIC - Defines a dynamic timer.
TAU_PROFILE_DECLARE_TIMER - Declares a timer for C
TAU_PROFILE_CREATE_TIMER - Creates a timer for C
TAU_GLOBAL_TIMER - Declares a global timer
TAU_GLOBAL_TIMER_EXTERNAL - Declares a global timer from an external compilation unit
TAU_GLOBAL_TIMER_START - Starts a global timer
TAU_GLOBAL_TIMER_STOP - Stops a global timer
TAU_PHASE - Profile a C++ function as a phase
TAU_DYNAMIC_PHASE - Defines a dynamic phase.
TAU_PHASE_CREATE_DYNAMIC - Defines a dynamic phase.
TAU_PHASE_CREATE_STATIC - Defines a static phase.
TAU_PHASE_START - Enters a phase.
TAU_PHASE_STOP - Exits a phase.
TAU_DYNAMIC_PHASE_START - Enters a DYNAMIC_PHASE.
TAU_DYNAMIC_PHASE_STOP - Enters a DYNAMIC_PHASE.
TAU_STATIC_PHASE_START - Enters a STATIC_PHASE.
TAU_STATIC_PHASE_STOP - Enters a STATIC_PHASE.
TAU_GLOBAL_PHASE - Declares a global phase
TAU_GLOBAL_PHASE_EXTERNAL - Declares a global phase from an external compilation unit
TAU_GLOBAL_PHASE_START - Starts a global phase
TAU_GLOBAL_PHASE_STOP - Stops a global phase
TAU_PROFILE_EXIT - Alerts the profiling system to an exit call
TAU_REGISTER_THREAD - Register a thread with the profiling system
TAU_PROFILE_GET_NODE - Returns the measurement system's node id
TAU_PROFILE_GET_CONTEXT - Gives the measurement system's context id
TAU_PROFILE_SET_THREAD - Informs the measurement system of the THREAD id
TAU_PROFILE_GET_THREAD - Gives the measurement system's thread id
TAU_PROFILE_SET_NODE - Informs the measurement system of the node id
TAU_PROFILE_SET_CONTEXT - Informs the measurement system of the context id
TAU_REGISTER_FORK - Informs the measurement system that a fork has taken place
TAU_REGISTER_EVENT - Registers a user event
TAU_PROFILER_REGISTER_EVENT - Registers a user event
TAU_EVENT - Triggers a user event
TAU_EVENT - Triggers a user event
TAU_EVENT - Triggers a user event
TAU_EVENT_THREAD - Triggers a user event on a given thread
TAU_REGISTER_CONTEXT_EVENT - Registers a context event
TAU_CONTEXT_EVENT - Triggers a context event
TAU_TRIGGER_CONTEXT_EVENT - Triggers a context event
TAU_EVENT - Triggers a context user event
TAU_ENABLE_CONTEXT_EVENT - Enable a context event
TAU_DISABLE_CONTEXT_EVENT - Disable a context event
TAU_EVENT_SET_NAME - Sets the name of an event
TAU_EVENT_DISABLE_MAX - Disables tracking of maximum statistic for a given event
TAU_EVENT_DISABLE_MEAN - Disables tracking of mean statistic for a given event
TAU_EVENT_DISABLE_MIN - Disables tracking of minimum statistic for a given event
TAU_EVENT_DISABLE_STDDEV - Disables tracking of standard deviation statistic for a given event
TAU_REPORT_STATISTICS - Outputs statistics
TAU_REPORT_THREAD_STATISTICS - Outputs statistics, plus thread statistics
TAU_ENABLE_INSTRUMENTATION - Enables instrumentation
TAU_DISABLE_INSTRUMENTATION - Disables instrumentation
TAU_ENABLE_GROUP - Enables tracking of a given group
TAU_DISABLE_GROUP - Disables tracking of a given group
TAU_PROFILE_TIMER_SET_GROUP - Change the group of a timer
TAU_PROFILE_TIMER_SET_GROUP_NAME - Changes the group name for a timer
TAU_PROFILE_TIMER_SET_NAME - Changes the name of a timer
TAU_PROFILE_TIMER_SET_TYPE - Changes the type of a timer
TAU_PROFILE_SET_GROUP_NAME - Changes the group name of a profiled section
TAU_INIT - Processes command-line arguments for selective instrumentation
TAU_PROFILE_INIT - Processes command-line arguments for selective instrumentation
TAU_GET_PROFILE_GROUP - Creates groups based on names
TAU_ENABLE_GROUP_NAME - Enables a group based on name
TAU_DISABLE_GROUP_NAME - Disables a group based on name
TAU_ENABLE_ALL_GROUPS - Enables instrumentation in all groups
TAU_DISABLE_ALL_GROUPS - Disables instrumentation in all groups
TAU_GET_EVENT_NAMES - Gets the registered user events.
TAU_GET_EVENT_VALS - Gets user event data for given user events.
TAU_GET_COUNTER_NAMES - Gets the counter names
TAU_GET_FUNC_NAMES - Gets the function names
TAU_GET_FUNC_VALS - Gets detailed performance data for given functions
TAU_ENABLE_TRACKING_MEMORY - Enables memory tracking
TAU_DISABLE_TRACKING_MEMORY - Disables memory tracking
TAU_TRACK_POWER - Initializes POWER tracking system
TAU_TRACK_POWER_HERE - Triggers power tracking at a given execution point
TAU_ENABLE_TRACKING_POWER - Enables power headroom tracking
TAU_DISABLE_TRACKING_POWER - Disables power headroom tracking
TAU_TRACK_MEMORY - Initializes memory tracking system
TAU_TRACK_MEMORY_HERE - Triggers memory tracking at a given execution point
TAU_TRACK_MEMORY_FOOTPRINT - Initializes memory footprint tracking system
TAU_TRACK_MEMORY_FOOTPRINT_HERE - Triggers memory footprint tracking at a given execution point
TAU_ENABLE_TRACKING_MEMORY_HEADROOM - Enables memory headroom tracking
TAU_DISABLE_TRACKING_MEMORY_HEADROOM - Disables memory headroom tracking
TAU_TRACK_MEMORY_HEADROOM - Track the headroom (amount of memory for a process to grow) by periodically interrupting the program
TAU_TRACK_MEMORY_HEADROOM_HERE - Takes a sample of the amount of memory available at a given point.
TAU_SET_INTERRUPT_INTERVAL - Change the inter-interrupt interval for tracking memory and headroom
CT - Returns the type information for a variable
TAU_TYPE_STRING - Creates a type string
TAU_DB_DUMP - Dumps the profile database to disk
TAU_DB_MERGED_DUMP - Dumps the profile database to disk
TAU_DB_DUMP_INCR - Dumps profile database into timestamped profiles on disk
TAU_DB_DUMP_PREFIX - Dumps the profile database into profile files with a given prefix
TAU_DB_DUMP_PREFIX_TASK - Dumps the profile database into profile files with a given task
TAU_DB_PURGE - Purges the performance data.
TAU_DUMP_FUNC_NAMES - Dumps function names to disk
TAU_DUMP_FUNC_VALS - Dumps performance data for given functions to disk.
TAU_DUMP_FUNC_VALS_INCR - Dumps function values with a timestamp
TAU_PROFILE_STMT - Executes a statement only when TAU is used.
TAU_PROFILE_CALLSTACK - Generates a callstack trace at a given location.
TAU_TRACE_RECVMSG - Traces a receive operation
TAU_TRACE_SENDMSG - Traces a receive operation
TAU_PROFILE_PARAM1L - Creates a snapshot of the current apllication profile
TAU_PROFILE_SNAPSHOT - Creates a snapshot of the current apllication profile
TAU_PROFILE_SNAPSHOT_1L - Creates a snapshot of the current apllication profile
TAU_PROFILER_CREATE - Creates a profiler object referenced as a standard pointer
TAU_CREATE_TASK - Creates a task id.
TAU_PROFILER_START - starts a profiler object created by
TAU_PROFILER_START_TASK - Starts a profiler object created by on a given task.
TAU_PROFILER_STOP - stops a profiler object created by
TAU_PROFILER_STOP_TASK - Stops a profiler object on a task
TAU_PROFILER_GET_CALLS - Gets the number of times this timer, created by , is started.
TAU_PROFILER_GET_CALLS_TASK - Gets the number of times this timer, created by , is started on a given task.
TAU_PROFILER_GET_CHILD_CALLS - Gets the number of calls made while this timer was running
TAU_PROFILER_GET_CHILD_CALLS_TASK - Gets the number of child call for this timer, created by , is started on a task.
TAU_PROFILER_GET_INCLUSIVE_VALUES - Returns the inclusive amount of a metric spend by this timer.
TAU_PROFILER_GET_INCLUSIVE_VALUES_TASK - Returns the inclusive amount of a metric spend by this timer on a given task.
TAU_PROFILER_GET_EXCLUSIVE_VALUES - Returns the exclusive amount of a metric spend by this timer.
TAU_PROFILER_GET_EXCLUSIVE_VALUES_TASK - Returns the exclusive amount of a metric spend by this timer on a given task.
TAU_PROFILER_GET_COUNTER_INFO - Returns information about all the timers created.
TAU_PROFILER_GET_COUNTER_INFO_TASK - Returns information about all the timers created on a task.
TAU_QUERY_DECLARE_EVENT - Returns a event handle.
TAU_QUERY_GET_CURRENT_EVENT - set event to be the current TAU event.
TAU_QUERY_GET_EVENT_NAME - Gets the name of a given event.
TAU_QUERY_GET_PARENT_EVENT - gets the parent of the current event.