| TAU Documentation

Runtime Environment Variables

Table 1. Performance Data Output
VARIABLE NAME	DESCRIPTION
TAU_PROFILE	Set to 1 to have TAU profile your code (on by default unless tracing is enabled)
TAU_TRACE	Set to 1 to have TAU trace your code
PROFILEDIR	Specifies the directory where profile files are to be stored (defaults to current directory). See Selective Profiling
TRACEDIR	Specifies the directory where trace file are to be stored (defaults to current directory). See Generating Event Traces
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_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_TRACE_FORMAT	Set to `otf2` or `perfetto` to output those trace formats instead of TAU’s default. TAU must be configured with support for those formats.
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_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_TRACEFILE	Specifies the name of Vampir trace file. Use with -TRACE TAU configuration option. See Generating Event Traces
TAU_KEEP_TRACEFILES	Retains the intermediate trace files when TAU_TRACEFILE is used to generate Vampir trace output. Use with -TRACE TAU configuration option. See Generating Event Traces

Table 2. Performance Data Metrics and Measurement Behavior
VARIABLE NAME	DESCRIPTION
TAU_METRICS	Colon delimited list of TAU/PAPI/LIQWID,etc metrics to profile
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_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_TRACK_SIGNALS	Set this variables to 1 to capture callstack as metadata at point of failure.
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_VERBOSE	When set TAU will print out information about the its configuration when running a instrumented application.
TAU_MUSE_PACKAGE	Sets the MAGNET/MUSE package name. Use with the -muse TAU configuration option. See Using Hardware Counters for Measurement
PAPI_EVENT	Sets the hardware counter to use when TAU is configured with -PAPI. See Using Hardware Performance Counters
PCL_EVENT	Sets the hardware counter to use when TAU is configured with -PCL. See Using Hardware Performance Counters

Table 3. Event Based Sampling
VARIABLE NAME	DESCRIPTION
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.

Table 4. Selective Instrumentation and Measurement Throttling
VARIABLE NAME	DESCRIPTION
TAU_THROTTLE	Enables the runtime throttling of events that are lightweight. See Selective Profiling
TAU_THROTTLE_NUMCALLS	Set the maximum number of calls that will be profiled for any function when TAU_THROTTLE is enabled. See Selective Profiling
TAU_THROTTLE_PERCALL	Set the minimum inclusive time (in milliseconds) a function has to have to be instrumented when TAU_THROTTLE is enabled. See Selective Profiling
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.

Table 5. MPI
VARIABLE NAME	DESCRIPTION
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.
TAU_TRACK_MESSAGE	Track MPI message statistics (profiling), messages lines (tracing).
TAU_COMM_MATRIX	Generate MPI communication matrix 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.

Table 6. GPU
VARIABLE NAME	DESCRIPTION
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_THREAD_PER_GPU_STREAM	Set this to 1 to report each GPU stream as a distinct TAU thread. Currently supports CUPTI only.
TAU_ROCM_PCS_CUS	Set this to 1 to report each ROCm PC sample according to the device id and the computational unit that triggered the event.
TAU_CUPTI_PC_HWB	Set to the hardware buffer size (in MBytes) to use with cupti PC sampling (activated with the -cupti_pc option to tau_exec)
TAU_CUPTI_PC_PERIOD	Set to the sampling period to use with cupti PC sampling (activated with the -cupti_pc option to tau_exec)
L0_METRICGROUP	Specify Intel GPU Metrics. Check available metrics with unitrace `--metric-list` or examples/gpu/oneapi/l0_check_metrics`
TAU_L0_SAMPLING_INTERVAL	Set to the sampling period to use with L0 PC Sampling (activated with the -l0_pc option to tau_exec and the unit is usecond)
TAU_OMPT_DISABLE_OFFLOAD	Set to disable OMPT callbacks for device-side offload events.
TAU_CUPTI_PC_HWB	Set to change the size (in MB) of the buffer for CUPTI PC sampling.
TAU_CUPTI_PC_PERIOD	Set to change the sampling perior(in cycles) for CUPTI PC sampling.
TAU_USE_ROCSDK_SAMPLING_STOC	Force TAU to configure ROCm PC sampling in stochastic mode (enables stall events).
TAU_USE_ROCSDK_SAMPLING_HOST	Force TAU to configure ROCm PC sampling in host-trap mode.