sample(1) System General Commands Manual sample(1)
NAME
sample - Profile a process during a time interval
SYNOPSIS
sample pid/partialName duration samplingInterval [-mayDie] [-wait]
[-file filename] [-subst oldBinary newBinary]
DESCRIPTION
sample is a command-line tool for gathering data about the running behav-
ior of a process. It stops the process at user-defined intervals, usu-
ally every 10-100 milliseconds. It records the current function being
executed by the process, and checks the stack to find how the current
function was called. It then lets the application continue.
At the end of a sampling session, sample produces a report showing which
functions were executing during the sampling. The data is condensed into
a call tree, showing the functions seen on the stack and how they were
called. (This tree is a subset of the actual call tree for the execu-
tion, since some functions may not have been executing during any of the
sampling events.) The tree is displayed textually, with called functions
indented one level to the right of the callee.
The user of sample specifies process (either by process id, or by name),
a sampling rate (in milliseconds), and the duration of the sampling run
(in seconds). The sampling rate should usually be between 10 msec and
100 msec, though it will capture data at sampling intervals of 2 msec.
Faster sampling rates provide more samples and a better chance to capture
all the functions that are executing; however extremely fast sampling
rates might cause multiple samples to be taken when the process is
stopped. Longer sampling durations ensures better data.
The [-mayDie] flag tells sample to immediately grab the location of sym-
bols from the application, on the assumption that the application may
crash at any point during the sampling. This ensures that sample can
give information about the call stacks even if the process no longer
exists.
The [-wait] flag tells sample to wait for the process specified (usually
as a partial name or hint) to exist, then start sampling that process.
This option allows you to sample from an application's launch.
The [-file] flag names where the output should be written. If this flag
is not specified, results are written to a file in /tmp called <applica-
tion name>_<processid>.sample.txt.
[-subst] allows the caller to specify the full path to the executable.
If the application was not run with the full path, or sampler is not run
with the -subst flag, sample cannot get symbol table information from the
executable. This flag thus lets you tell sample where to get the infor-
mation needed to gather symbol information. The first argument after
-subst is the name of the binary to be replaced, and the second is the
name of the binary that will instead be searched for symbolic informa-
tion.
The analysis done by sample is called ``sampling'' because it only checks
the state of the program at the sampling points. The analysis may miss
execution of some functions that are not executing during one of the sam-
ples, but sample still can provide useful data about commonly executing
functions.
sample is similar to gprof. gprof also performs statistical sampling at
10ms intervals to identify the currently executing function, but instru-
ments the program to gather a complete call graph for the program.
Like profiling, sample gathers runtime data. However, because it only
checks at intervals, it only sees some of the functions that are running.
Longer durations or shorter sampling times can improve coverage.
SEE ALSO
gprof(1)
Sampler.app is a similar graphical application for sampling program
behavior. Sampler.app better visualizes the data, but sample is faster
for quick-and-dirty "what is my program doing" sorts of questions.
BSD April 26, 2000 BSD