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 callstacks for
every process in the system. Spindump supports two display formats for
callstacks, 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, callstacks
are sorted by count and each unique callstack 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,
callstacks are sorted so that the leaf frames in the call tree are presented
in chronological order. Each frame includes a time range of consecutive
callstacks 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
callstack were not consecutive, the callstack 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 information spindump reports includes thread QoS, darwinbg, importance inheritance boost, suppression for App Nap, latency QoS (timers), I/O throttling tier, and cpu priority.
Leaf frames will indicate whether the thread was running/runnable or suspended.
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 specifying 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
file located at path rather than sampling the live
system. Supported file formats are:
* Spindump text files containing a spindump binary format
* Spindump text files without a spindump binaty format written in timeline
mode (with limited options, and only callstacks will be updated; summary
information will not change)
* Tailspin files
* Concatenated kcdata stackshots
* Concatenated microstackshots
-o 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 created inside that directory with the name following the format
<appname>_<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.
-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 callstacks by count
(default)
-timeline Sort callstacks
chronologically
-wait Wait for the process to exist before
sampling. If the process already exists, spindump will begin sampling
immediately.
-onlyRunnable Only display runnable
callstacks
-onlyBlocked Only display non-runnable
callstacks
-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 (in
addition to writing to a file)
-noFile Do not output to a file. Implies
-stdout and will include the binary format in the stdout output
-noBinary Do not include the spindump
binary format at the bottom of the report (the file will not be able to be
re-parsed)
-noText Do not include the textual report,
only include the binary format
-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 textual report (by default they are omitted)
-aggregateCallTreesByThread Group call
trees by thread ID rather than by dispatch queue
-aggregateCallTreesByProcess Each process
gets one call tree for all threads
-omitFramesBelowSampleCount
c Omit frames with count below
c
MICROSTACKSHOTS
Microstackshots are gathered by the kernel to provide extremely lightweight sampling of single threads at a time. They can be viewed in spindump 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 sampling 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
textual 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 information 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
-useridleonly Only include microstackshots
taken while the user was idle
-useractiveonly Only include
microstackshots taken while the user was active