mdoc warning: Empty input line #154

spindump(8)               BSD System Manager's Manual              spindump(8)

NAME
     spindump -- Profile entire system during a time interval

SYNOPSIS
     spindump [pid | partial-name [duration [interval]]] [<options>]

DESCRIPTION
     spindump is used by various system components to create reports when an
     unresponsive application is force quit. Reports are stored at:

     /Library/Logs/DiagnosticReports/

     For normal application force quits spindump will display a dialog to
     offer the choice to view more details and/or send a report to Apple.

     -------------------------------------

     When run manually, spindump samples user and kernel stacks for every
     process in the system. Spindump supports two display formats for stacks,
     heavy and timeline, and includes a binary representation of its data at
     the end of reports for re-reporting with different options (see -i ).
     Spindump can also parse reports in timeline format even without a binary
     representation to re-report them in heavy format.

     When displayed in heavy format, stacks are sorted by count and each
     unique stack is displayed once. In this snippet:

     84  __CFRunLoopRun + 1161 (CoreFoundation + 460665) [0x7fff8d662779]

     Address 0x7fff8d662779 was sampled 84 times in total, not necessarily
     consecutively. The address corresponds __CFRunLoopRun in CoreFoundation.

     When displayed in timeline format, samples are sorted so that the leaf
     frames in the sample tree are presented in chronological order. Each
     frame includes a time range of consecutive samples in which the frame was
     seen, which can be compared with the range of other frames to determine
     concurrency. If multiple samples of the same stack were not consecutive,
     the stack will be displayed multiple times. In this snippet:

     23  __CFRunLoopRun + 1161 (CoreFoundation + 460665) [0x7fff8d662779]
     50-72

     Address 0x7fff8d662779 was sampled 23 times consecutively from the 50th
     to 72nd sample.

     In timeline format, spindump notes state changes for threads, e.g.:

     <darwinbg, timers coalesced>

     which indicates the change in state for the samples that follow. Any
     state not mentioned is unchanged from previous samples. The state infor-
     mation spindump reports includes thread QoS, darwinbg, importance inheri-
     tance boost, suppression for App Nap, latency QoS (timers), I/O throt-
     tling tier, and cpu priority.

     Leaf frames will indicate whether the thread was running/runnable or sus-
     pended.

     A leading star (*) indicates a kernel frame or library.

ARGUMENTS
     pid or partial-name the process to be sorted topmost in the report.
     "-notarget" may be used to avoid providing a target process when specify-
     ing a duration and interval.

     duration the duration of the sampling in seconds. If not specified, the
     default of 10 seconds is used.

     interval the number of miliseconds between samples. If not specified, the
     default of 10 miliseconds is used.

     -i path Read in the binary format stored in the spindump file at path and
     re-report that data rather than sampling the live system. Spindump can
     also parse the stacks of a timeline formatted report without a binary
     format in order to re-report them in heavy format, in which case only
     stacks will be updated; summary information will not change.

     -indexRange s-e Only include samples in the given range

     -startIndex s Omit frames before sample number s

     -endIndex e Omit frames after sample number e

     -heavy Sort stacks by count (default)

     -timeline Sort stacks chronologically

     -file path Specifies where the report should be written. If path is a
     file, it will be overwritten. If path is a directory, a file will be cre-
     ated inside that directory with the name following the format <app-
     name>_<pid>.spindump.txt. If a file by that name already exists, spindump
     will add a unique number to the filename. If not specified, spindump will
     output reports to files inside /tmp.

     -wait Wait for the process to exist before sampling. If the process
     already exists, spindump will begin sampling immediately.

     -onlyrunnable Only display runnable stacks

     -onlyblocked Only display non-runnable stacks

     -onlytarget Only sample the target process (allows faster sampling rates)

     -proc -<proc> If onlytarget is provided, sample proc as well. This option
     may be specified multiple times

     -sampleWithoutTarget Keep sampling for the entire sampling duration even
     if the target process exits

     -timelimit t Exit after t seconds even if the report hasn't been saved

     -stdout Print the report to stdout

     -nofile Do not output to a file. Implies -stdout and will include the
     binary format in the stdout output

     -open appname Specifies an app in which to open the resulting report

     -reveal Reveal the resulting report in Finder

     -siginfo After sampling, wait for SIGINFO before generating the report

     -delayonsignal d Stop sampling d seconds after receiving a signal to stop
     sampling instead of stopping immediately

     -threadprioritythreshold t Filter out any threads that have a priority
     below the given threshold. Pass a negative number to filter out threads
     that have a priority above the given threshold's absolute value

     -nothrottle Do not throttle sampling rate on excessive memory growth

     -noProcessingWhileSampling Do not parse stackshots until done sampling

     -displayIdleWorkQueueThreads Display idle work queue threads in the tex-
     tual report (by default they are omitted)

     -aggregateStacksByThread Group stacks by thread ID rather than by dis-
     patch queue

     -aggregateStacksByProcess Each process gets one stack for all threads

MICROSTACKSHOTS
     Microstackshots are gathered by the kernel to provide extremely light-
     weight sampling of single threads at a time. They can be viewed in spin-
     dump via the microstackshot command line options:

     -microstackshots Report on interrupt microstackshots, which provide a
     sampling of where cpu time is spent. This is the default mode if
     -microstackshots_io is not provided

     -microstackshots_io Report on I/O microstackshots, which provide a sam-
     pling of where file backed memory is dirtied

     -microstackshots_datastore path When reporting microstackshots, read from
     this location rather than using the live system's microstackshots. When
     saving with -microstackshots_save, write to this location

     -microstackshots_save Save microstackshot from the live system to the
     path specified by -microstackshots_datastore instead of generating a tex-
     tual report

     -microstackshots_starttime date Only report microstackshots after this
     time. The date can be a string like "11/14/12 12:00am" or a single number
     representing a unix timestamp in seconds

     -microstackshots_endtime date Only report microstackshots before this
     time. The date can be a string like "11/14/12 12:00am" or a single number
     representing a unix timestamp in seconds

     -microstackshots_pid pid Only report microstackshots for the given
     process id

     -microstackshots_threadid thread_id Only report microstackshots for the
     given thread id

     -microstackshots_dsc_path path Path to a directory containing dyld shared
     cache layout files. If not specified, spindump uses the historical infor-
     mation for the current machine

     -batteryonly Only include microstackshots taken while the machine was
     running on battery power

     -aconly Only include microstackshots taken while the machine was running
     on AC power

SEE ALSO
     SubmitDiagInfo(8), sample(1)

Darwin                          April 19, 2016                          Darwin