TAU Guides

University of Oregon

Version 2.33.1

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

February 12, 2024


Table of Contents

TAU User Guide
TAU preface
I. Tau User Guide
1. Tau Instrumentation
1.1. Types of Instrumenation
1.2. Dynamic instrumentation through library pre-loading
1.3. TAU scripted compilation
1.3.1. Instrumenation
1.3.2. Compiler Based Instrumentation
1.3.3. Source Based Instrumentation
1.3.4. Options to TAU compiler scripts
1.4. Selectively Profiling an Application
1.4.1. Custom Profiling
2. Profiling
2.1. Running the Application
2.2. Reducing Performance Overhead with TAU_THROTTLE
2.3. Profiling each event callpath
2.4. Using Hardware Counters for Measurement
3. Tracing
3.1. Generating Event Traces
4. Analyzing Parallel Applications
4.1. Text summary
4.2. ParaProf
4.3. Jumpshot
5. Quick Reference
6. Some Common Application Scenario
6.1. Q. What routines account for the most time? How much?
6.2. Q. What loops account for the most time? How much?
6.3. Q. What MFlops am I getting in all loops?
6.4. Q. Who calls MPI_Barrier() Where?
6.5. Q. How do I instrument Python Code?
6.6. Q. What happens in my code at a given time?
6.7. Q. How does my application scale?
II. ParaProf - User's Manual
7. Introduction
7.1. Using ParaProf from the command line
7.2. Supported Formats
7.3. Command line options
8. Views and Sub-Views
8.1. To Create a (Sub-)Views
9. Profile Data Management
9.1. ParaProf Manager Window
9.2. Loading Profiles
9.3. Database Interaction
9.4. Creating Derived Metrics
9.5. Main Data Window
10. 3-D Visualization
10.1. Triangle Mesh Plot
10.2. 3-D Bar Plot
10.3. 3-D Scatter Plot
10.4. 3-D Topology Plot
10.5. 3-D Commication Matrix
11. Thread Based Displays
11.1. Thread Bar Graph
11.2. Thread Statistics Text Window
11.3. Thread Statistics Table
11.4. Call Graph Window
11.5. Thread Call Path Relations Window
11.6. User Event Statistics Window
11.7. User Event Thread Bar Chart
12. Function Based Displays
12.1. Function Bar Graph
12.2. Function Histogram
13. Phase Based Displays
13.1. Using Phase Based Displays
14. Comparative Analysis
14.1. Using Comparitive Analysis
15. Miscellaneous Displays
15.1. User Event Bar Graph
15.2. Ledgers
15.2.1. Function Ledger
15.2.2. Group Ledger
15.2.3. User Event Ledger
15.3. Selective Instrumentation File Generator
16. Preferences
16.1. Preferences Window
16.2. Default Colors
16.3. Color Map
III. PerfExplorer - User's Manual
17. Introduction
18. Installation and Configuration
19. Running PerfExplorer
20. Cluster Analysis
20.1. Dimension Reduction
20.2. Max Number of Clusters
20.3. Performing Cluster Analysis
21. Correlation Analysis
21.1. Dimension Reduction
21.2. Performing Correlation Analysis
22. Charts
22.1. Setting Parameters
22.1.1. Group of Interest
22.1.2. Metric of Interest
22.1.3. Event of Interest
22.1.4. Total Number of Timesteps
22.2. Standard Chart Types
22.2.1. Timesteps Per Second
22.2.2. Relative Efficiency
22.2.3. Relative Efficiency by Event
22.2.4. Relative Efficiency for One Event
22.2.5. Relative Speedup
22.2.6. Relative Speedup by Event
22.2.7. Relative Speedup for One Event
22.2.8. Group % of Total Runtime
22.2.9. Runtime Breakdown
22.3. Phase Chart Types
22.3.1. Relative Efficiency per Phase
22.3.2. Relative Speedup per Phase
22.3.3. Phase Fraction of Total Runtime
23. Custom Charts
24. Visualization
24.1. 3D Visualization
24.2. Data Summary
24.3. Creating a Boxchart
24.4. Creating a Histogram
24.5. Creating a Normal Probability Chart
25. Views
25.1. Creating Views
25.2. Creating Subviews
26. Running PerfExplorer Scripts
26.1. Analysis Components
26.2. Scripting Interface
26.3. Example Script
27. Derived Metrics
27.1. CreatingExpressions
27.2. Selecting Expressions
27.3. Expression Files
IV. TAUdb
28. Introduction
28.1. Prerequisites
28.2. Installation
29. Using TAUdb
29.1. perfdmf_createapp (deprecated - only supported for older PerfDMF databases)
29.2. perfdmf_createexp (deprecated - only supported for older PerfDMF databases)
29.3. taudb_loadtrial
29.4. TAUdb Views
30. Database Schema
30.1. SQL for TAUdb
31. TAUdb C API
31.1. TAUdb C API Overview
31.2. TAUdb C Structures
31.3. TAUdb C API
31.4. TAUdb C API Examples
31.4.1. Creating a trial and inserting into the database
31.4.2. Querying a trial from the database
TAU Install Guide
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
TAU Reference Guide
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. TAU_TRACK_MEMORY_FOOTPRINT
4.3.4. TAU_TRACK_MEMORY_FOOTPRINT_HERE
4.3.5. -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
tau_trace2json - convert TAU tracefiles to json tracefiles for Chrome tracing or other viewers
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.
taudb_configure - Configuration program for a PerfDMF database.
perfdmf_createapp - Deprecated Command line tool to create a application in the perfdmf database. (Deprecated)
perfdmf_createexp - Deprecated Command line tool to create a experiment in the perfdmf database. (Deprecated)
taudb_loadtrial - Command line tool to load a trial into the TAUdb database.
perfexplorer - Launches TAU's Performance Data Mining Analyzer.
perfexplorer_configure - Configures a TAUdb database for use with perfexplorer, and installs necessary JAR files.
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).
tau_spark-submit - Launches PySpark applications with TAU instrumentation
I. TAUdb
8. Introduction
8.1. Prerequisites
8.2. Installation
9. Using TAUdb
9.1. perfdmf_createapp (deprecated - only supported for older PerfDMF databases)
9.2. perfdmf_createexp (deprecated - only supported for older PerfDMF databases)
9.3. taudb_loadtrial
9.4. TAUdb Views
10. Database Schema
10.1. SQL for TAUdb
11. TAUdb C API
11.1. TAUdb C API Overview
11.2. TAUdb C Structures
11.3. TAUdb C API
11.4. TAUdb C API Examples
11.4.1. Creating a trial and inserting into the database
11.4.2. Querying a trial from the database
12. Windows
12.1. TAU on Windows
12.1.1. Installation
12.1.2. Instrumenting an application with Visual Studio C/C++
12.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 - 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.
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