Name

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

Synopsis

sample [-h] [-o FILENAME] [-s PERIOD] [-l BYTES [,BYTES...]] [-n] [-d DELAY]
[-t DURATION] [-f] [-c COUNT]
[-b RUNTIME] [-q QUALITY] [--safe-stack] [--preallocation SIZE]
[--use-target-stderr] [--unsupported-attach] [--tmpdir DIR]
[ { --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 | -w STRING | -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.

-o FILENAME

Sample file name, sample.smp by default.

-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.

-d DELAY

Start sampling after DELAY seconds.

-t DURATION

Detach after sampling for DURATION seconds.

-f

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

-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.

--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.

--tmpdir DIR

Use the directory DIR for large temporary files. Note that some small temporary files may still be created in /tmp.

--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.

-w STRING

Wait for a process with the specified string as a part of its name to start and then sample it.

-r BINARY [ARGUMENT...]

Start BINARY with ARGUMENTs.

Examples

Example 1. Starting an application in the sampler

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

$ sample -r ls -l


Example 2. 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 3. Waiting for a process and sampling for a fixed time

Wait for process with a certain name to start, then attach to it and acquire fingerprints for 5 seconds. After this period, detach and leave the target process running:

$ sample -w simulation -t 5


Example 4. 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


Exit Status

0

Successful program execution.

1

Usage error.

2

Sampling failed.

3

Sample file post processing failed.

Environment

ACUMEM_LICENSE_FILE

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

Files

$HOME/.acumem/license

User specific license file. Used if no system wide license file can be found.

/etc/acumem/license

System wide license file.