sysdiagnose(1) BSD General Commands Manual sysdiagnose(1)NAME
sysdiagnose -- gathers system-wide diagnostic information helpful in investigating system performance issues.
SYNOPSIS
sysdiagnose -h
sysdiagnose [-f results_directory] [-t] [-q] [-b] [process_name | pid]
DESCRIPTION
sysdiagnose tool gathers system diagnostic information helpful in investigating system performance issues. A great deal of information is
harvested, spanning system state and configuration. sysdiagnose needs to be run as root. sysdiagnose can be triggered upon pressing a spe-
cial key chord; this is currently Control-Option-Command-Shift-Period.
What sysdiagnose Collects:
o A spindump of the system
o Several seconds of fs_usage ouput
o Several seconds of top output
o Data about kernel zones
o Status of loaded kernel extensions
o Resident memory usage of user processes
o All system logs, kernel logs, opendirectory log, windowserver log, and log of power management events
o A System Profiler report
o All spin and crash reports
o Disk usage information
o I/O Kit registry information
o Network status
o If a specific process is supplied as an argument: list of malloc-allocated buffers in the process's heap is collected
o If a specific process is supplied as an argument: data about unreferenced malloc buffers in the process's memory is collected
o If a specific process is supplied as an argument: data about the virtual memory regions allocated in the process
OPTIONS -h Print full usage.
-f results_directory
Specify the directory where the results will be stored. The default results directory is /var/tmp.
-q Skips calling footprint.
-t Enable "Thorough Mode". See below.
-b Do not show the resulting archive in a Finder window upon completion.
process_name | pid
If a single process appears to be slowing down the system, passing in the process name or ID as the argument gathers additional
process-specific diagnostic data.
THOROUGH MODE
sysdiagnose can be run in a "Thorough Mode" in which standard data is gathered as well as a kernel trace. Enabling "Thorough Mode" for the
command-line sysdiagnose and key-chord sysdiagnose are independent and are performed as follows:
For "Thorough Mode" in the command-line sysdiagnose use the "-t" flag.
To enable "Thorough Mode" for special key-chord launches of sysdiagnose execute "touch /var/tmp/.thoroughsysdiagnose"
To disable "Thorough Mode" for special key-chord launches of sysdiagnose execute "rm /var/tmp/.thoroughsysdiagnose"
Note:
Gathering the kernel trace can increase the size of sysdiagnose output by hundreds of MB as well as increase the time for sysdiagnose to com-
plete.
EXIT STATUS
sysdiagnose exits with status 0 if there were no internal errors encountered during the diagnostic, or >0 when an error unrelated to external
state occurs or unusable input is provided by the user.
Darwin June 2, 2019 Darwin
Check Out this Related Man Page
stackshot(1) BSD General Commands Manual stackshot(1)NAME
stackshot -- capture user and kernel space stack traces, using a kernel stack trace facility
SYNOPSIS
stackshot [-D] [-i] [-f path] [-n number] [-p pid] [-B size]
DESCRIPTION
The stackshot daemon is a diagnostic facility used to capture stack traces for each thread on the system, including both user space and ker-
nel stacks. The resulting view of the system is internally consistent. This facility, especially when coupled with sysdiagnose(1) (described
below) can be used to obtain an overview of the state of the system under abnormal conditions, such as hangs and UI unresponsiveness, with a
few keystrokes.
The stack snapshot is triggered upon pressing a special key chord. Two key chords are available: Control-Option-Command-Shift-Period triggers
stackshot as well as sysdiagnose(1) in the default configuration. An alternate keychord, Control-Option-Command-Shift-Comma invokes stackshot
and its stack symbolication facility alone.
The daemon also triggers a stack snapshot upon reception of the SIGINFO signal.
Stack pages that are paged out are not captured--this caveat does not apply to kernel space stacks, which are wired.
The following options are available:
-D Turn on debugging.
-i Do an immediate snapshot, and exit. Useful when invoked from the command line.
-f path Output the log information to the specified path. This supercedes any preference configuration (see below).
-n number
Limit the number of snapshots taken; the default is 1.
-p pid Log the stack information for the specified process-ID only.
-B size Specify the size of the trace buffer; the default is 52 kilobytes.
-t Attempt to invoke sysdiagnose(1) This will also cause the stackshot logfile to be symbolicated, with the symbolicated tracefile
appended to /Library/Logs/stackshot-syms.log.
-u Attempt symbolication. Currently, this starts up a separate symbolicator thread, and signals that thread to begin symbolication
using atos(1) when a snapshot is triggered. The current implementation may take several seconds to perform the address-symbol trans-
lations, depending on the state of the system. The symbolicated trace file is appended to: /Library/Logs/stackshot-syms.log.
SYMBOLICATION
Symbolication (as with the -t or -u options, or the symstacks.rb script described below) is performed against the currently executing process
images, which may have been either fully or partially stripped of debugging symbols. Additionally, kernel stacks are symbolicated against
/mach_kernel, which typically has all local and debugging symbols stripped (as with "strip -S -x"). In either case, symbol matching may not
always be accurate. If in doubt, you may run the unstripped executable images, or symbolicate the trace file directly against the unstripped
images using an alternate mechanism, such as gdb. The symstacks.rb script (see below) can take a "-k" argument, which specifies the location
of an alternate kernel image to symbolicate with--this can be an unstripped kernel image. When filing bug reports, it is best to include both
the trace file ("stackshot.log") and the symbolicated trace ("stackshot-syms.log").
NOTES
The stackshot daemon is intended to be run by the launchd(8) super-daemon. The system may not be configured with stackshot enabled by
default. launchctl(1) can be used to enable and disable this daemon. stackshot reads configuration information from
~root/Library/Preferences/com.apple.stackshot.plist. It examines the following keys
Trace File Specifies the file to use. The default is /Library/Logs/stackshot.log.
Trace Server A dictionary containing ``Host'' (as a string) and ``Port'' (as an integer) keys, for a server. If both a file and server are
specified, stackshot will attempt to use both. The server is expected to do nothing other than accept a connection, accept a
stream of data, and write it to a file of its choosing.
Buffer Size Specifies the size of the trace buffer.
FILES
/usr/libexec/stackshot The stackshot binary.
~root/Library/Preferences/com.apple.stackshot.plist
Preference file used for configuration information.
/System/Library/LaunchDaemons/com.apple.stackshot.plist
Configuration file used by launchd(8).
/usr/sbin/symstacks.rb ruby(1) script to process the output of stackshot and turn symbol addresses into symbol names. It reads a stackshot
trace file from standard input or a file specified with "-f" , and writes the symbolicated version to standard out-
put, or to a file specified with "-w". See caveats above regarding accuracy of symbolication against stripped images.
The "-k" argument to the script can specify the location of a kernel image, which will be used for symbolication. The
"-s" argument forces the script to symbolicate kernel stacks alone, which can be useful in conjunction with the "-k"
argument to symbolicate kernel stacks on systems which differ from the one which generated the trace file. Note that
symbolication is performed against currently running process images, so the script must be executed on the same (or
identical) system for accuracy, and any processes of interest must be currently executing.
SEE ALSO launchd(8)BUGS
Certain types of deadlocks (especially driver/kernel level deadlocks) may prevent triggering stackshot when the hot-key combination is
pressed.
Depending upon the type of deadlock, there may be issues accessing the filesystem and/or network, preventing publication of the data once the
traces are gathered.
The daemon makes a minimal effort to ensure that the log file has space allocated, and does no processing afterwards. The aforementioned
ruby(1) script can be used to translate addresses to symbols. It is up to the user to examine the file (and perhaps send it off to someone
for debugging) afterwards.
The symbolication is not perfect, and may benefit from human scrutiny or post-processing.
Darwin May 31, 2019 Darwin