Table A.1. TAU Environment Variables
| VARIABLE NAME | DESCRIPTION |
|---|---|
| TAU_PROFILE | Set to 1 to have TAU profile your code |
| TAU_TRACE | Set to 1 to have TAU trace your code |
| TAU_METRICS | Colon delimited list of TAU/PAPI metrics to profile |
| PAPI_EVENT | Sets the hardware counter to use when TAU is configured with -PAPI. See Section 2.6, “Using Hardware Performance Counters” |
| PCL_EVENT | Sets the hardware counter to use when TAU is configured with -PCL. See Section 2.6, “Using Hardware Performance Counters” |
| PROFILEDIR | Selectively measure groups of routines and statements. Use with -profile command line option. See Section 1.4, “Selectively Profiling an Application” |
| TAU_CALLPATH | When set to 1 TAU will generate call-path data. Use with TAU_CALLPATH_DEPTH. |
| TAU_CALLPATH_DEPTH | Sets the depth of the callpath profiling. Use with TAU_CALLPATH environment variable. |
| TAU_CALLSITE | When set to 1 TAU will provide call site information for events in profile and trace output. Configure TAU with -bfd=download and -useropt="-g" . |
| TAU_TRACK_MESSAGE | Track MPI message statistics (profiling), messages lines (tracing). |
| TAU_COMM_MATRIX | Generate MPI communication matrix data. |
| TAU_COMPENSATE | Attempt to compensate for profiling overhead in profiles. |
| TAU_COMPENSATE_ITERATIONS | Set the number of iterations TAU uses to estimate the measurement overhead. A larger number of iteration will increases profiling precision (default 1000). |
| TAU_KEEP_TRACEFILES | Retains the intermediate trace files. Use with -TRACE TAU configuration option. See Section 3.1, “Generating Event Traces” |
| TAU_MUSE_PACKAGE | Sets the MAGNET/MUSE package name. Use with the -muse TAU configuration option. See Section 2.4, “Using Hardware Counters for Measurement” |
| TAU_THROTTLE | Enables the runtime throttling of events that are lightweight. See Section 1.4, “Selectively Profiling an Application” |
| TAU_THROTTLE_NUMCALLS | Set the maximum number of calls that will be profiled for any function when TAU_THROTTLE is enabled. See Section 1.4, “Selectively Profiling an Application” |
| TAU_THROTTLE_PERCALL | Set the minimum inclusive time (in milliseconds) a function has to have to be instrumented when TAU_THROTTLE is enabled. See Section 1.4, “Selectively Profiling an Application” |
| TAU_TRACEFILE | Specifies the name of Vampir trace file. Use with -TRACE TAU configuration option. See Section 3.1, “Generating Event Traces” |
| TRACEDIR | Specifies the directory where trace file are to be stored. See Section 3.1, “Generating Event Traces” |
| TAU_SELECT_FILE | When set to the location of a valid selective instrumentation file TAU will include/exclude the specified source at runtime. |
| TAU_COMPILER_SELECT_FILE | When set to the location of a valid selective instrumentation file the TAU LLVM plugin will include/exclude the specified source. |
| TAU_COMPILER_MIN_INSTRUCTION_COUNT | Excludes functions from instrumentation if their instruction count is below the set value, Defaults to 50. Set to 1 to include all functions. |
| TAU_VERBOSE | When set TAU will print out information about the its configuration when running a instrumented application. |
| TAU_PROFILE_FORMAT | When set to snapshot TAU will
generate condensed snapshot profiles (they merge together different
metrics so there is only one file per node.) Instead of the default
kind. When set to merged, TAU will pre-compute mean
and std. dev. at the end of execution.
|
| TAU_TRACK_MEMORY_FOOTPRINT | When set TAU will track resident set size (VmRSS) and peak memory usage (VmHWM) or the high water mark of resident set size, the same values provided by the 'top' command. |
| TAU_TRACK_POWER | Enables tracking of power consumption via periodic interrupt. |
| TAU_SYNCHRONIZE_CLOCKS | When set TAU will correct for any time discrepancies between nodes because of their CPU clock lag. This should produce more reliable trace data. |
| TAU_SAMPLING |
Default value is 0 (off). When TAU_SAMPLING is set, we collect additional profile or trace information (depending on whether TAU_PROFILE or TAU_TRACE is set respectively) via periodic sampling at runtime. Metrics collected and sampling period is controlled by TAU_EBS_SOURCE and TAU_EBS_PERIOD variables respectively. The TAU_EBS_UNWIND variable determines if callstack unwinding is enabled at each sample. For TAU_PROFILE, in addition to regular TAU instrumented profile output, samples will show up as additional events prefixed by [SAMPLE] for each unique function, file and source line number combination. These events are grouped under [INTERMEDIATE] event nodes for the instrumented TAU context where the samples occured. In addition, if TAU_EBS_UNWIND is active, [UNWIND] event nodes may be generated for each discovered callstack entry found by the callstack unwinder. TAU_SAMPLING is dependent on the availability of BFD as determined by the -bfd configuration option when building TAU. Its ability to resolve sample addresses into function, file name and source line number information may be limited or missing if BFD is missing or is installed with limited functionality. If in doubt, please try building TAU with "-bfd=download". Any one of function, file name and source line number may be missing. In the event all three are, the event is marked as "UNRESOLVED". The TAU_EBS_KEEP_UNRESOLVED_ADDR variable enables addresses to be retained for unresolved results. |
| TAU_EBS_SOURCE | Default value is "itimer". This variable sets the metric that determines the period of sampling. If the value is "itimer" (default), it represents the number of microseconds between samples (as determined by TAU_EBS_PERIOD). If the value is a PAPI metric (eg. PAPI_FP_INS), then it represents the number of counts of that metric between samples (eg. every 10,000 floating-point instructions if PAPI_FP_INS is used). For "itimer", the samples occur as a result of system timer interrupts while for PAPI they occur in response to PAPI counter overflow interrupts set to the value of the TAU_EBS_PERIOD. |
| TAU_EBS_PERIOD | Default value is 1,000. This variable sets the period between samples. The semantics of this value is discussed in the section above on TAU_EBS_SOURCE. |
| TAU_EBS_UNWIND | Default value is 0 (off). This enables callstack unwinding for each sample using the callstack unwinder specified at TAU configuration time. As of this writing, only the libunwind tool is supported. Support for other callstack unwinders like StackwalkerAPI will be included. The TAU_EBS_UNWIND_DEPTH variable is used to control how many times the TAU sampling framework will be allowed to unwind the callstack. |
| TAU_EBS_UNWIND_DEPTH | Default value is 10. This controls how many layers of the callstack TAU should unwind before attaching the result to the appropriate TAU event context. |
| TAU_EBS_KEEP_UNRESOLVED_ADDR | Default value is 0 (off). When set, this variable allows sample addresses that fail to be resolved by BFD to be recorded as "UNRESOLVED <modulename> ADDR <addr> instead of "UNRESOLVED <modulename>". This provides nominally more information than the default scenario in light of missing BFD information. |
| TAU_EBS_RESOLUTION | Can be set to file, function or line. Is line by default. Event based sampling will resolve to the selected level of granularity. |
| TAU_TRACK_SIGNALS | Set this variables to 1 to capture callstack as metadata at point of failure. |
| TAU_SUMMARY | Set this variables to 1 to generate just min/max/stddev/mean statistics instead of per-node data. Use paraprof -dumpsummary and then pprof -f profile.Max/Min to see the data. |
| TAU_IBM_BG_HWP_COUNTERS | Set this variable to 1 to include IBM's UPC Hardware Performance counters in the metadata for process 0. Requires the use of MPI. |
| TAU_CUPTI_API | Default: runtime, options:
runtime,driver,both.
Controls which layer of CUDA is tracked within the CUPTI
measurement system. See for example: tau_exec -T
serial,cupti -cupti ./matmult. Option should be set
basied on which layer the CUDA program
uses—runtime when the program uses the
CUDA runtime API, driver when the program
uses the driver API. NOTE: Both the PGI accelerator and the HMPP
compilers use the driver API.
|
| TAU_TRACK_MPI_T_PVARS | Set this variable to 1 to enable collection of MPI_T PVAR values |
| TAU_MPI_T_CVAR_METRICS | Set this to the MPI_T variable(s) you want to control, in conjunction with the values set in TAU_MPI_T_CVAR_VALUES
|
| TAU_MPI_T_CVAR_VALUES | Set this to the value(s) you want assigned to the variable(s) specified in TAU_MPI_T_CVAR_METRICS
|
| TAU_SET_NODE | Set this to 0 to allow MPI configurations of TAU to work correctly with serial codes. |