Manual Pages for UNIX Darwin command on man sample

sample(1) BSD General Commands Manual sample(1)

NAME

ssaammppllee - Profile a process during a time interval

SYNOPSIS

ssaammppllee pid | partial-executable-name [duration [samplingInterval]]

[-mmaayyDDiiee] [-wwaaiitt] [-ffiillee filename] [-ssuubbsstt oldBinary newBinary]

DESCRIPTION

ssaammppllee 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 1-20 milliseconds. It records the current function being exe-

cuted by the process, and checks the stack to find how the current func-

tion was called. It then lets the application continue. At the end of a sampling session, ssaammppllee 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 a target process (either by process id, or

by name), the duration of the sampling run (in seconds), and a sampling rate (in milliseconds). The sampling rate should usually be between 1

msec and 20 msec. Faster sampling rates provide more samples and a bet-

ter 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. If the sampling rate is not specified, a default of 1 millisecond is used, as of Mac OS X 10.5. (On earlier releases the default rate was 10 milliseconds.) If the sampling duration is not specified, a default of 10 seconds is used.

The [-mmaayyDDiiee] 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 [-wwaaiitt] 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 [-ffiillee] flag names where the output should be written. If this flag

is not specified, results are written to a file in /tmp called

tion name>..sample.txt, where each 'X' is replaced by

a random alphanumeric character.

[-ssuubbsstt] 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, ssaammppllee 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 ssaammppllee 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 ssaammppllee still can provide useful data about commonly executing functions. ssaammppllee is similar to gprof. ggpprrooff 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.