Sysdiagnose for Mac Issues

When an app on your Mac freezes, or otherwise something problematic happens before force quitting the app or working to remedy the problem you can first collect diagnostic data. This can then be used later to try and figure out more information about what may have happened. You can do this using the built-in sysdiagnose tool. This is something that is included in macOS for developers, and is part of Apple’s bug reporter infrastructure that developers use to submit bugs to Apple.

It can also be used by anyone at any time. Running sysdiagnose in the middle of your Mac misbehaving may collect useful information that can shed light on what is going wrong.

Running Sysdiagnose

Open the Terminal application. The fastest way to do so is to start typing “Terminal” into Spotlight, and press return when the app appears in the results.

If you’re not an Administrative user type

login <your admin user’s short username>

and press return, then when promoted type in your admin user’s password. Note that the text you enter for the password will not show up at all when typing it in, for security. This will log you in to your admin user in Terminal, which is necessary for sysdiagnose since it has to be run from an admin account.

Run

sudo sysdiagnose

You will be asked for your admin password again (as before, for security the password won’t be visible at all as you type it in), and then follow the on-screen prompts to start diagnostic gathering. This process will take a few minutes.

When complete a Finder window will open and reveal the file of gathered diagnostic information. You can close Terminal when the Finder window comes up. If you logged in as an admin user, don’t worry about the additional termination warning Terminal gives, it is just fine to close the window. Alternatively, you can run

logout

first to log yourself out of your admin account. Doing so will put you back in Terminal as your own user, where you can close Terminal without the warning.

I recommend copying the file to some other folder on your Mac for safekeeping if you intend to examine it later. Sysdiagnose saves the file to a temporary folder that usually gets erased at reboot, so to keep the file around for the long term and examine its contents later copy it elsewhere. Be aware that each diagnostic file is generally no smaller than 1/4 GB (and almost a full GB when unarchived), so you probably don’t want to be saving the file anywhere that is synced via cloud services (iCloud Drive, Google Drive, Dropbox, etc.). Finder will ask for admin credentials to complete the copy. You can save to an external drive if imminently worried about your Mac, but usually just saving to your Documents folder is fine.

Once you have saved the sysdiagnose file you can force quit the problematic app or otherwise remedy the problem your Mac is experiencing. At this point you have collected diagnostic data from your Mac during the time it was misbehaving and so can examine the state it was in later, and should do whatever it takes to get back to work as normal.

Remotely Running Sysdiagnose

From time to time our Macs can get stuck in such a way where nothing appears to be functioning. You cannot move the cursor, nor does any key on the keyboard appear to be responsive. In these cases the usual troubleshooting step is to hold the power button down until the screen goes black, forcing the Mac to shut down. Then if all goes well the Mac will start up normally when you next press the power button. But when the Mac is in this state it may still be mostly functional, and in these cases you can, in fact, still run sysdiagnose, and even shut down the Mac without the forced shut down that basically just cuts power to the machine.

This uses the ssh command at the command line. In order for your Mac to be available for ssh you need to first turn on the Remote Login option under Sharing in System Preferences (access via the Apple menu, then choose the Sharing option from the main screen of System Preferences). Simply ensure that the appropriate option is checked in the preference pane:

I recommend that you limit the users that can access the Mac via ssh. Generally just admins and others who would really need access, but certainly not kids or visitors. Having Remote Login on is something I consider a bit of a safety feature for my Mac, precisely because it allows me to tap in to it even if the standard interactions don’t work to run troubleshooting and at the very least shut down cleanly. Take note of what the computer name of your Mac is, as it is labeled in the small print below the field (my Mac’s is Quad.local).

To log in to your Mac from another Mac open Terminal and type (as an example)

ssh apple@Quad.local

where you use the appropriate admin user and Mac names. When prompted for the password type it in.

From there you can run sysdiagnose as normal:

sudo sysdiagnose

You can then copy the resulting file from the command line. First you need to navigate to the directory where the sysdiagnose was saved:

cd /private/var/tmp

Then you can list the contents of that directory to determine the filename of the saved sysdiagnose:

ls

From there you can copy the file. For example:

sudo cp sysdiagnose.gzip /Users/Shared

I’m using sudo (which forces the task to be done as the Root user) since the file is owned by that user, which is why Finder requires admin credentials to copy it.

You can then run

sudo shutdown -r now

to tell your Mac to restart appropriately. Unlike holding the power button down, this will be a clean shut down where apps all close up as if you selected Shut Down or Restart from the Apple menu. Depending on the nature of your Mac’s problems, though, you may not see any visual feedback that the Msc is shutting down, at least until the screen goes black (which if that never happens wait a few minutes to ensure the Mac should have shut down normally, then proceed with holding down the power button).

If you don’t have an extra Mac around any UNIX-based computer will have command-line access you can use. There are also numerous apps on the App Store that allow you to access remote computers via ssh, for example I use Terminus, but there are dozens out there.

Examining a Sysdiagnose

Now that you have saved a sysdiagnose you may eventually want to explore what it holds. Now, grant you, saving them can also just be additional evidence for Apple Geniuses when you bring your Mac in, but you may want to explore yourself. To do so just double click the file and it will be unarchived into a folder. Here are a few things that are in a sysdiagnose folder I recommend looking at:

• top.txt shows the most active processes. Especially look for any that are using abnormal amounts of CPU, abnormal amounts of memory, or that are in the stuck state.
• system.log in the logs folder is the system log of the time around when the problem happened. It may shed some light on what was causing the problem.
• The crashes_and_spins folder will contain logs of processes that have crashed.

That is just a start, even I have not explored a sysdiagnose fully, and cannot claim to understand what every bit of data means. What I can say is that it is way more information than we’d ever normally need or want to know. But even just saving these as evidence for a genius is a decent idea, as they will be able to paint a better picture of your Mac’s problem then you can. If the issue is intermittent then these may also be the only real way to “show” a genius the problem your Mac is having.

Conclusion

This post gives you instructions on how to go about saving diagnostic data on your computer using the sysdiagnose tool. It gives you a method of remotely saving this data if your Mac is unresponsive. Lastly, this post gives you a starting point for examining the collected data. While this is admittedly not something that everyone will want to do, and it isn’t something we’ll be doing every time necessarily, it is a technique worth adding to your toolbox of Mac troubleshooting methods. I mention sharing these with geniuses, but to be fair, sysdiagnose is intended for developers to share data with Apple’s engineers, so it is possible that Apple Geniuses haven’t had a ton of exposure to this knd of data. Still, it is a wealth of information on a Mac during a problem, so it is a helpful step in recording what is going on, and hopefully shedding light on the problem.