Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.




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 behavior 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 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 execution, since some
     functions may not have been executing during any of the sampling events.)  The tree is displayed textu-ally, textually,
     ally, with called functions indented one level to the right of the callee.

     In the call tree, if a function calls more than one function then a vertical line is printed to visu-ally visually
     ally connect those separate children functions, 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 per-forms performs
     forms 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 partial 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 assump-tion assumption
     tion that the application may exit or 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.

     -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 sampling 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>.sam-ple.txt, name>_<date>_<time>.<XXXX>.sample.txt,
     ple.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 application that can give information
     similar to that provided by sample. The Time Profiler instrument graphically displays dynamic, real-time realtime
     time CPU sampling information.

BSD                              Mar. 16, 2013                             BSD

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback