sample

sample
	Command Reference

Name

sample — sample the memory access pattern of a process and generate a sample file

Synopsis

sample [-h] [--version] [-o FILENAME] [-s PERIOD] [-l BYTES [,BYTES...]] [-n] [-f] [-d DELAY]
[-t DURATION] [-c COUNT]
[-b RUNTIME] [-q QUALITY] [--safe-stack] [--tmpdir TMPDIR] [--preallocation SIZE]
[--use-target-stderr] [--unsupported-attach] [-g GENERATION]
[ { --start-at-function FUNCTION | --start-at-address ADDRESS } [--start-at-ignore COUNT] ]
[ { --stop-at-function FUNCTION | --stop-at-address ADDRESS } [--stop-at-ignore COUNT] ]
{ -p PID | -r BINARY [ARGUMENT...] }

Description

sample is the tool that starts and monitors the fingerprinting operation of the target application. It can either start a new target process, or it can attach to an already running process. After the execution is complete, or after the sample tool has detached from the target process, it will post-process the fingerprint information and optionally reduce the fingerprint volume to a standard size.

Options

-h

Show help message and exit.

--version

Print version information.

-o FILENAME

Sample file name, sample.smp by default.

FILENAME can contain certain substitution sequences, which are useful to automatically derive unique filenames. This feature is particularly useful when sampling parallel jobs (e.g., MPI) to create unique filenames based on properties of each node.

The following table lists the special sequences that Freja recognizes:

Table 9. Filename substitutions

Sequence	Substitution
%r	If executed in an MPI environment this is replaced with the MPI rank number, if known. On other systems it is equivalent to %h-%p (see below). Example: x-%r.smp becomes x-17.smp (MPI), or x-myhost-123.smp (otherwise)
%h	Replaced with the current hostname of the machine. Example: x-%h.smp becomes x-myhost.smp
%p	Replaced with a unique number within the current host. Note: It is not related to the Pid of the target process. Example: x-%p.smp becomes x-123.smp
%u	Expands to ".`number`" in such a way that the resulting filename becomes unique. Numbers are tried sequentially, starting with 0. As a special case, the number ".0" is elided. Example: x%u.smp becomes x.smp (first file), x.1.smp (next file) etc.
%U	Expands to ".`number`" in such a way that the resulting filename becomes unique. Numbers are tried sequentially until a unique number is found. Example: x%U.smp becomes x.0.smp (first file), x.1.smp (next file), etc.
%{`ENV`}	Replaced with the content of the environment variable `ENV` Example: x-%{USER}.smp becomes x-demo.smp
%%	Replaced with a single %. This is sometimes useful on Windows when encoding commands in a batch file. Example: x%%.smp becomes x%.smp

The following table lists the environment variables that Freja tries in sequence to figure out the MPI rank number for the %r substitution.

Table 10. %r substitutions

Environment variable^[a]	Used for MPI type:
PMI_RANK	MPICH 2 and derivatives
OMPI_COMM_WORLD_RANK	OpenMPI 1.3
OMPI_MCA_ns_nds_vpid	OpenMPI 1.2 and derivatives
PMI_ID	SLURM PMI
SLURM_PROCID	SLURM
LAMRANK	LAM
MPI_RANKID	HP MPI for Linux
MP_CHILD	IBM PE
MP_RANK	Sun CT
MPIRUN_RANK	MVAPICH 1.1
^[a] The inclusion of an environment variable in this list does not automatically imply that Freja is certified for that platform.

-s PERIOD

Sample period in number of memory accesses, default 100.

-l BYTES [,BYTES...]

Line sizes to sample in bytes. Default is 64 byte line size.

-n

Don't decimate the sample file.

-f

Use fixed sample period. Default is to use automatic sample period adjustment.

-d DELAY

Start sampling after DELAY seconds.

-t DURATION

Detach after sampling for DURATION seconds.

-c COUNT

Collect COUNT samples. Default is 50000.

-b RUNTIME

Enable burst sampling. RUNTIME should be the estimated run time of the application in minutes.

-q QUALITY

Adjusts the quality parameter for bursting. Default quality level is 'normal'.

fast

Decreases sampling overhead by sacrificing accuracy. Accuracy should normally be good for caches of 8 MB or smaller, and is generally acceptable for 16 MB caches.

normal

The normal accuracy level, which is default, provides a good compromise between accuracy and performance.

detailed

Increases sampling overhead by roughly a factor 2. Improves accuracy particularly when analyzing applications with small fetch ratios running on systems with large caches (32 MB or larger).

This setting also allows more long range blocking and fusion opportunities to be found.

--safe-stack

Disable the sampler's use of the application stack. May be needed for applications with non-standard stack handling.

--tmpdir TMPDIR

Name the directory where all temporary files will be stored.

This directory can alternatively be specified by environment variables THREADSPOTTER_TMPDIR or TMPDIR on Linux or TMP on Windows. The command line option takes precendence over the environment variables.

--preallocation SIZE

Reduces the amount of virtual address space reserved to the sampler to SIZE megabytes. This is only applicable to 64-bit installations and only needed on systems enforcing virtual memory limits. Minimum preallocation size is 128 MB, default is 2048 MB.

--use-target-stderr

Allow the sampler to log warnings and errors on the target application's stderr. Such messages are normally shown on the sampler control application's console instead.

--unsupported-attach

Relaxes the sampler permission checks to allow attaching to other users' processes when running as root. Use of this option may cause security issues, particularly on systems with multiple simultaneous users, and is not recommended.

-g GENERATION

Whether to sample the invoked process (=0, default) or its children (=1) etc. In some MPI environments, like SGI and Cray, the target application is bootstrapped using an intermediate process which should not be sampled.

--start-at-function FUNCTION

Start sampling when the execution reaches the specified function.

--start-at-address ADDRESS

Start sampling when the execution reaches the specified address.

--start-at-ignore COUNT

Ignore the first COUNT times the sampling start location (set with --start-at-function or --start-at-address) is reached.

--stop-at-function FUNCTION

Stop sampling when the execution reaches the specified function.

--stop-at-address ADDRESS

Stop sampling when the execution reaches the specified address.

--stop-at-ignore COUNT

Ignore the first COUNT times the sampling stop location (set with --stop-at-function or --stop-at-address) is reached.

-p PID

Sample the already running process with the specified pid.

-r BINARY [ARGUMENT...]

Start BINARY with ARGUMENTs.

Examples

Example 4. Starting an application in the sampler

Acquire fingerprint information from target process 'ls', run with '-l' command line parameter:

$ sample -r ls -l

Example 5. Attaching to a running process

Acquire fingerprint information from target process with pid 3344 and naming the output file:

$ sample -p 3344 -o fingerprint.smp

Example 6. Burst sampling a long running application

Long running applications generally benefit from burst sampling. The following example will burst sample a hypothetical benchmark that is normally expected to run for 15 minutes:

$ sample -b 15 -r ./benchmark

Example 7. Using a template name for output file

Sampling in an MPI environment requires that sample file names are unique. The following example will launch a number of instances of the sampler across an MPI environment, assigning a unique name to each sample file.

$ mpirun -np 16 sample -o experiment1/file-%r.smp -r ./my-mpi-application

Exit Status

0: Successful program execution.
1: Usage error.
2: Sampling failed.
3: Sample file post processing failed.

Environment

RW_LICENSE_FILE: Environment variable pointing to the license file. Should only be used to override default license locations.

Files

$HOME/.threadspotter/license: Directory containing per-user license files. Freja looks for license files here if no system wide license file can be found.


internal		report