TAU Reference Guide

Updated November 9th, 2012, for use with version 2.22 or greater.

Copyright © 1997-2012 Department of Computer and Information Science, University of Oregon Advanced Computing Laboratory, LANL, NM Research Centre Julich, ZAM, Germany

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of University of Oregon (UO) Research Centre Julich, (ZAM) and Los Alamos National Laboratory (LANL) not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. The University of Oregon, ZAM and LANL make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

UO, ZAM AND LANL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE UNIVERSITY OF OREGON, ZAM OR LANL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

TAU can be found on the web at: http://www.cs.uoregon.edu/research/tau


Table of Contents

1. Installation
1.1. Installing TAU
1.1.1. Know what options you will need
1.1.2. Common configuration options
1.1.3. Configuring with external packages
1.1.4. More configuration options
1.1.5. tau_setup
1.1.6. installtau script
1.1.7. upgradetau
1.1.8. tau_validate
1.2. Platforms Supported
1.3. Software Requirements
2. TAU Instrumentation Options
2.1. Selective Instrumentation Options
2.2. Running an application using DynInstAPI
2.3. Rewriting Binaries
2.3.1. Using MAQAO
2.3.2. Using PEBIL
2.4. Profiling each call to a function
2.5. Profiling with Hardware counters
2.6. Using Hardware Performance Counters
2.7. Profiling with PerfLib
2.8. Running a Python application with TAU
2.9. pprof
2.10. Running a JAVA application with TAU
2.11. Using a tau.conf File
2.12. Using Score-P with TAU
2.13. Using UPC with TAU
3. Tracing
3.1. How to configure tracing
4. TAU Memory Profiling Tutorial
4.1. TAU's memory API options
4.2. Using tau_exec
4.3. Evaluating Memory Utilization
4.3.1. TAU_TRACK_MEMORY
4.3.2. TAU_TRACK_MEMORY_HERE
4.3.3. -PROFILEMEMORY
4.4. Evaluating Memory Headroom
4.4.1. TAU_TRACK_MEMORY_HEADROOM()
4.4.2. TAU_TRACK_MEMORY_HEADROOM_HERE()
4.4.3. -PROFILEHEADROOM
4.5. DetectingMemoryLeaks
4.6. Memory Tracking In Fortran
5. Eclipse Tau Java System
5.1. Installation
5.2. Instrumentation
5.3. Uninstrumentation
5.4. Running Java with TAU
5.5. Options
6. Eclipse PTP / CDT plug-in System
6.1. Installation
6.2. Creating a Tau Launch Configuration
6.3. Selective Instrumentation
6.4. Launching a Program and Collecting Data
7. Tools
tau_compiler.sh - Instrumenting source files.
vtf2profile - Generate a TAU profile set from a vampir trace file
tau2vtf - convert TAU tracefiles to vampir tracefiles
trace2profile - convert TAU tracefiles to TAU profile files
tau2elg - convert TAU tracefiles to Epilog tracefiles
tau2slog2 - convert TAU tracefiles to SLOG2 tracefiles
tau2otf - convert TAU tracefiles to OTF tracefiles for Vampir/VNG
tau2otf2 - convert TAU tracefiles to OTF2 tracefiles for Vampir/VNG
perf2tau - converts PerfLib profiles to TAU profile files
tau_merge - combine multiple node and or thread TAU tracefiles into a merged tracefile
tau_treemerge.pl - combine multiple node and or thread TAU tracefiles into a merged tracefile
tau_convert - convert TAU tracefiles into various alternative trace formats
tau_reduce - generates selective instrumentation rules based on profile data
tau_ompcheck - Completes uncompleted do/for/parallel omp directives
tau_poe - Instruments a MPI application while it is being executed with poe.
tau_validate - Validates a TAU installation by performing various tests on each TAU stub Makefile
tauex - Allows you to choose a tau configuration at runtime
tau_exec - TAU execution wrapping script
tau_timecorrect - Corrects and reorders the records of tau trace files.
tau_throttle.sh - This tool generates a selective instrumentation file (called throttle.tau) from a program output that has "Disabling" messages.
tau_portal.py - This tool is design to interact with the TAU web portal (http://tau.nic.uoregon.edu). There are commands for uploading or downloading packed profile files form the TAU portal.
perfdmf_configure - Configuration program for a PerfDMF database.
perfdmf_createapp - Command line tool to create a application in the perfdmf database.
perfdmf_createexp - Command line tool to create a experiment in the perfdmf database.
perfdmf_loadtrial - Command line tool to load a trial into the perfdmf database.
perfexplorer - Launches TAU's Performance Data Mining Analyzer.
perfexplorer_configure - Configures a perfdmf database for use with perfexplorer.
taucc - C compiler wrapper for TAU
tauupc - UPC wrapper for TAU
taucxx - C++ compiler wrapper for TAU
tauf90 - Fortran compiler wrapper for TAU
paraprof - Launches TAU's Java-based performance data viewer.
pprof - Quickly diplays profile data.
tau_instrumentor - automaticly instruments a source basied on information provided by pdt.
vtfconverter -
tau_setup - Launches GUI interface to configure TAU.
tau_wrap - Instruments an external library with TAU without needing to recompile
tau_gen_wrapper - Generates a wrapper library that can intercept at link time or at runtime routines specified in a header file
tau_pin - Instruments application at run time using Intel's PIN library
tau_java - Instruments java applications at runtime using JVMTI
tau_cupti_avail - Detects the available CUPTI counters on the a each GPU device.
tau_run - Instruments and executes binaries to generate performance data. (DyninstAPI based instrumentor)
tau_rewrite - Rewrites binaries using Maqao if Tau is configured using PDT 3.17+ at the routine level. If it doesn't find the Maqao package from PDT 3.17, it reverts to tau_run (DyninstAPI based instrumentor).
3. Windows
3.1. TAU on Windows
3.1.1. Installation
3.1.2. Instrumenting an application with Visual Studio C/C++
3.1.3. Using MINGW with TAU
I. TAU Instrumentation API
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_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_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_MEMORY - Initializes memory tracking system
TAU_TRACK_MEMORY_HERE - Triggers memory 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.
II. TAU Mapping API
TAU_MAPPING - Encapsulates a C++ statement for profiling
TAU_MAPPING_CREATE - Creates a mapping
TAU_MAPPING_LINK - Creates a mapping link
TAU_MAPPING_OBJECT - Declares a mapping object
TAU_MAPPING_PROFILE - Profiles a block based on a mapping
TAU_MAPPING_PROFILE_START - Starts a mapping timer
TAU_MAPPING_PROFILE_STOP - Stops a mapping timer
TAU_MAPPING_PROFILE_TIMER - Declares a mapping timer
A. Environment Variables