MAP and Performance Reports variables

This table provides a reference to environment variables you can use for Linaro MAP and Linaro Performance Reports, with guidance on requirements and best practices for using them.

FORGE_SAMPLER_INTERVAL

Takes a sample in each 20ms period, which gives a default sampling rate of 50Hz. The 50Hz sampling rate automatically decreases as the run proceeds to ensure a constant number of samples are taken.

For more information, see FORGE_SAMPLER_NUM_SAMPLES.

If your program runs for a very short period of time, you might benefit by decreasing the initial sampling interval. For example, FORGE_SAMPLER_INTERVAL=1 sets an initial sampling rate of 1000Hz, or once per millisecond. Higher sampling rates are not supported.

Linaro recommends that you avoid increasing the sampling frequency from the default if there are many threads or very deep stacks in the target program. Increasing the sampling frequency might not allow enough time to complete one sample before the next sample starts.

Note

Custom values for FORGE_SAMPLER_INTERVAL can be overwritten by values set from the combination of FORGE_SAMPLER_INTERVAL_PER_THREAD and the expected number of threads (from OMP_NUM_THREADS). For more information, see FORGE_SAMPLER_INTERVAL_PER_THREAD.

FORGE_SAMPLER_INTERVAL_PER_THREAD

To keep overhead low, this imposes a minimum sampling interval based on the number of threads. By default, this is 2 milliseconds per thread. For 11 or more threads, the initial sampling interval increases to more than 20ms.

To adjust the minimum per-thread sample time, set FORGE_SAMPLER_INTERVAL_PER_THREAD in milliseconds.

Linaro recommends that you avoid lowering this value from the default if there are many threads. Lowering this value might not allow enough time to complete one sample before the next sample starts.

Note

Whether OpenMP is enabled or disabled, the final script or scheduler values set for OMP_NUM_THREADS are used to calculate the sampling interval per thread (FORGE_SAMPLER_INTERVAL_PER_THREAD). When you configure your job for submission, check whether the final submission script, scheduler, or the Linaro MAP user interface has a default value for OMP_NUM_THREADS.
Custom values for FORGE_SAMPLER_INTERVAL are overwritten by values set from the combination of FORGE_SAMPLER_INTERVAL_PER_THREAD and the expected number of threads (from OMP_NUM_THREADS).

FORGE_MPI_WRAPPER

To use a specific pregenerated MPI wrapper library, set FORGE_MPI_WRAPPER=<path of shared object>.

Linaro MAP and Linaro Performance Reports include several precompiled wrappers for common MPI implementations. If your MPI is supported, Linaro Forge will automatically select and use the appropriate wrapper. If no precompiled wrapper is found a MPI wrapper library will be silently compiled and used instead. FORGE_MPI_WRAPPER only needs to be used if neither the prepackaged MPI wrapper library or just-in-time compilation of a wrapper work.

To manually compile a wrapper specifically for your system, set FORGE_WRAPPER_COMPILE=1 and MPICC, then run <MAP-installation-directory>/map/wrapper/build_wrapper. Running build_wrapper generates the wrapper library ~/.allinea/wrapper/libmap_sampler_pmpi_<hostname>.so with symlinks.

Symlinks are generated for these files:

~/.allinea/wrapper/libmap-_sampler-_pmpi-_<_hostname>_.so.1
~/.allinea/wrapper/libmap-_sampler-_pmpi-_<_hostname>_.so.1.0
~/.allinea/wrapper/libmap-_sampler-_pmpi-_<_hostname>_.so.1.0.0

Warning

To prevent unauthorized users modifying sensitive files and directories, and introducing unsafe code into your environment, ensure that you assign only the minimum permissions that are required, and avoid group or world-writable permissions.

FORGE_WRAPPER_COMPILE

To instruct Linaro MAP and Linaro Performance Reports to fall back to create and compile a just-in-time wrapper, set FORGE_WRAPPER_COMPILE=1.

To generate a just-in-time wrapper, an appropriate compiler must be available on the machine where Linaro Forge is running, or on the remote host when using remote connect.

Linaro MAP and Linaro Performance Reports attempt to auto detect your MPI compiler. However, Linaro recommends that you set the MPICC environment variable to the path to the correct compiler.

FORGE_MPIRUN

The path of mpirun, mpiexec, or equivalent.

If set, FORGE_MPIRUN has higher priority than the path set in the user interface and the mpirun found in PATH.

FORGE_SAMPLER_NUM_SAMPLES

By default, Linaro MAP and Linaro Performance Reports collect 1000 samples per process. To avoid generating too much data on long runs, the sampling rate automatically decreases as the run progresses, to ensure that only 1000 evenly spaced samples are stored.

To adjust the sampling rate, set FORGE_SAMPLER_NUM_SAMPLES=<positive integer>.

Note

Linaro recommends that you leave this value at the default setting. Higher values are not generally beneficial, and add extra memory overheads while running your code. Consider that with 512 processes, the default setting already collects half a million samples over the job, and the effective sampling rate can be very high indeed.

FORGE_KEEP_OUTPUT_LINES

Specifies the number of lines of program output to record in .map files. Setting to 0 removes the line limit restriction.

However, Linaro recommends that you avoid setting FORGE_KEEP_OUTPUT_LINES=0 because it can result in very large .map files if the profiled program produces a lot of output.

To learn more, see Restrict Output.

FORGE_KEEP_OUTPUT_LINE_LENGTH

The maximum line length for program output that is recorded in .map files. Lines that contain more characters than the line length limit are truncated. Setting this to 0 removes the line length restriction.

However, Linaro recommends that you avoid setting FORGE_KEEP_OUTPUT_LINE_LENGTH=0 because it can result in very large .map files if the profiled program produces a lot of output per line.

To learn more, see Restrict Output.

FORGE_PRESERVE_WRAPPER

To gather data from MPI calls, Linaro MAP generates a wrapper to the chosen MPI implementation. See Prepare a program for profiling.

By default, the generated code and shared objects are deleted when Linaro MAP no longer needs them.

To prevent Linaro MAP and Linaro Performance Reports from deleting these files, set FORGE_PRESERVE_WRAPPER=1.

Note

If you use remote launch, this variable must be exported in the remote script. See Remote connections dialog.

FORGE_SAMPLER_NO_TIME_MPI_CALLS: Set this to prevent Linaro MAP and Linaro Performance Reports from timing the time spent in MPI calls.

FORGE_SAMPLER_TRY_USE_SMAPS: To allow Linaro MAP and Linaro Performance Reports to use /proc/[pid]/smaps to gather memory usage data, set FORGE_SAMPLER_TRY_USE_SMAPS.

Note

FORGE_SAMPLER_TRY_USE_SMAPS significantly slows down sampling.

MPICC

If a prepackaged MPI wrapper library is not available for your MPI Linaro MAP and Linaro Performance Reports will attempt to compile one as and when it is required. The MPICC variable will be the first MPI compiler used to attempt to compile the just-in-time MPI wrapper library.

If using MPICC fails, Linaro MAP and Linaro Performance Reports search for a suitable MPI compiler command in PATH.

If the MPI compiler used to compile the target binary is not in PATH (or if there are multiple MPI compilers in PATH), set MPICC to the appropriate MPI compiler to use.