How do you get system diagnostic files from macOS?

I am trying to debug a crashed (or hanging) app. How do I get the diagnostic files from the crash?

Individual crash reports are stored in /Library/Logs/CrashReporter but there is a system wide log collection tool called sysdiagnose.

Once you start experiencing the issue, hold down the 4 modifier keys and then press the period "." key. shift+control+option+command+.

You should see the screen flash white. After about 15 seconds, a Finder window will open with a sysdiagnose file highlighted.

This keyboard shortcut simply executes the sysdiagnose command, so if you are familiar with Terminal and want to pass in a process ID, you can get enhanced debugging information about that specific program. The key shortcut calls the tool with no arguments and captures the basic report only.

Apple sysdiagnose

This shell script(on 10.8 and lower) and executable program by the same name on 10.9:

• gathers system-wide diagnostic information
• is integral to OS X Lion and greater
• is not available as a separate download
• is not open source (I have asked Apple to make it so).

Preparing for the keyboard-only approach to sysdiagnose

In Terminal, run the following command.

sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.stackshot.plist

• if prompted for a password, enter your admin password for the operating system
• that's a one-off, no need to repeat the command.

Take a written note of the following key chord, you'll need it later:

Control-Option-Command-Shift-.

Diagnosis by the system

When an issue occurs:

1. use the key chord
2. for at least ten seconds, touch nothing
3. allow maybe five or ten minutes for all parts of the sysdiagnose routine to complete – simply wait as long as you can (there'll be no on-screen indication of progress)
4. Finder should open a window to the end result.

Exceptionally

In rare cases, an issue may prevent sysdiagnose from completing (I have made improvement suggestions to Apple). If this happens – if you're sure that you have waited long enough – it may be sensible to restart the Mac. Then:

1. in Finder, go to /private/var/tmp
2. seek a file or folder with a name beginning sysdiagnose_
3. if that file or folder exists, move it to a convenient place – your desktop, maybe.

Hints

Without the key chord, you can run sysdiagnose from the command line (see below, Apple manual page). But it's often more useful, or necessary, to use the chord – so be prepared.

Whilst I don't encourage carelessness, you can be a little careless with Control-Option-Command-Shift-. … if you struggle to avoid the fn key on your laptop, don't worry; including it by accident should not prevent the run of sysdiagnose.

Human analysis of diagnosis by the system

Hint: someone might like to ask a separate question about analysing the results of sysdiagnose – a more generalised answer could be useful.

If sysdiagnose_… from the /tmp area is a file

Presence of a sysdiagnose_….tar.gz file indicates that all parts of the sysdiagnose routine completed, and that the results were archived. If you wish, open the archive – its contents will appear as a folder.

If sysdiagnose_… from the /tmp area is a folder

Presence of a sysdiagnose_… folder (not a .tar.gz file) indicates that either:

• the routine was interrupted before completion; or
• some part of the routine could not complete.

Within the archive/folder

Some files are human-readable and may help to troubleshoot an issue.

Other files are more developer-oriented.

Related:

• How does 'stuck' (in results of 'top') relate to 'not responding' (in Activity Monitor), 'spin' or 'hang'?

For an incomplete run of sysdiagnose it may be useful to focus some attention on files that are abnormally empty …

Technical and other notes

stackshot(1) OS X Manual Page

sysdiagnose(1) OS X Manual Page

Some of what's above is a more generic edition of an accepted answer that appears elsewhere.

Diagnostic and usage information, other files of interest

Be guided by the log list in Console:

Expect to find files at the following paths:

• ~/Library/Logs/DiagnosticReports
• /Library/Logs/DiagnosticReports
• ~/Library/Logs
• /Library/Logs
• /private/var/log

Console

To find existing diagnostic or crash files, open Console app and find the files in User Reports (located at ~/Library/Logs/DiagnosticReports) in or System Reports (located at /Library/Logs/DiagnosticReports) sections. See: Where can I find my crash logs?

sysdiagnose

As per official sysdiagnose instructions for macOS, you can trigger a sysdiagnose either by:

^{Note: To access above link, you need to log-in to Developer Apple site first.}

• Briefly press the following keys simultaneously:

  Command-Option-Shift-Control-Period (.)

  and wait. The sysdiagnose process can take 10 minutes to complete. Once finished, Finder should automatically appear showing the generated file in /private/var/tmp/ (e.g. sysdiagnose_2017.mm.dd_hh-mm-ss-0000_12345.tar.gz).

• Trigger a sysdiagnose from Terminal by entering this command:

  sudo sysdiagnose
  

core dumps

To generate crash core dumps, see: How to generate core dumps on macOS?