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

NAME
     sample -- Profile a process during a time interval

SYNOPSIS
     sample pid | partial-executable-name [duration [samplingInterval]]
            [-wait] [-mayDie] [-fullPaths] [-e] [-file filename]

DESCRIPTION
     sample is a command-line tool for gathering data about the running behav-
     ior of a process.  It suspends the process at specified intervals (by
     default, every 1 millisecond), records the call stacks of all threads in
     the process at that time, then resumes the process.  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 samples, but sample
     still provides useful data about commonly executing functions.

     At the end of the sampling duration, sample produces a report showing
     which functions were executing during the sampling.  The data is con-
     densed 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
     execution, since some functions may not have been executing during any of
     the sampling events.)  The tree is displayed textually, with called func-
     tions indented one level to the right of the callee.

     In the call tree, if a function calls more than one function then a ver-
     tical line is printed to visually connect those separate children func-
     tions, making it easier to see which functions are at the same level.
     The characters used to draw those lines, such as + | : ! are arbitrary
     and have no specific meaning.

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

     If the sampling duration is not specified, a default of 10 seconds is
     used.  Longer sampling durations provide better data by collecting more
     samples, but could also be confusing if the target process performs many
     different types of operations during that period.

     The default sampling rate is 1 millisecond.  Fast sampling rates provide
     more samples and a better chance to capture all the functions that are
     executing.

     -wait tells sample to wait for the process specified (usually as a par-
     tial name or hint) to exist, then start sampling that process.  This
     option allows you to sample from an application's launch.

     -mayDie tells sample to immediately grab the location of symbols from the
     application, on the assumption that the application may exit or crash at
     any point during the sampling.  This ensures that sample can give infor-
     mation about the call stacks even if the process no longer exists.

     -fullPaths tells sample to show the full path to the source code (rather
     than just the file name) for any symbol in a binary image for which debug
     information is available.  The full path was the path to the source code
     when the binary image was built.

     -e tells sample to open the output in TextEdit automatically when sam-
     pling completes.

     -file filename tells sample the full path to where the output should be
     written.  If this flag is not specified, results are written to a file in
     /tmp called <application name>_<date>_<time>.<XXXX>.sample.txt, where
     each 'X' is replaced by a random alphanumeric character.

     If neither the -e nor -file flags are given, the output gets written to
     stdout as well as saved to the file in /tmp.

SEE ALSO
     filtercalltree(1), spindump(8)

     The Xcode developer tools also include Instruments, a graphical applica-
     tion that can give information similar to that provided by sample. The
     Time Profiler instrument graphically displays dynamic, real-time CPU sam-
     pling information.

BSD                              Mar. 16, 2013                             BSD