sample — sample the memory access pattern of a process and generate a sample file
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
...] }
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.
-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'.
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.
The normal accuracy level, which is default, provides a good compromise between accuracy and performance.
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.
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
Successful program execution.
Usage error.
Sampling failed.
Sample file post processing failed.