Troubleshooting macOS: Observation and the log

For my sins, on a good day I get asked only two or three questions about problems Mac users are experiencing. When things get busy – usually when there’s just been a macOS update and I’m frantically trying to both update and discover what’s inside it – that can rise to twenty or more. There are few common factors in those questions, apart from two which recur in almost every one: observation and the log.

Observe carefully

Some questions are as generic and vague as “why does my Mac keep crashing?” These are often the start of a long exchange of messages in which I try to elicit observations which can narrow the list of causes from millions to less than a dozen. They usually reveal that, apart from noticing that something serious has gone wrong, and keeps doing so, the user hasn’t observed what’s actually happening. A “crash” can be anything from an app which suddenly quits when you weren’t expecting it to, to the Mac shutting down and playing dead. There’s a world of difference between those, and careful observation is essential.

Spotting when your Mac has suffered a kernel panic is a basic skill for all. Unlike an app ‘crashing’, which leaves your Mac still running, a kernel panic is now followed by a forced restart or shutdown. When your Mac does start up again, it should present you with a dialog containing details of what happened in a panic log. If you don’t immediately copy and paste its contents into a text file (TextEdit should be fine), it’ll be lost and gone forever, and you’ll be very lucky to discover the cause.

Panic logs aren’t that difficult to interpret, and I and others are always happy to help you understand what happened, and what you can do about it. Sadly, letting the dialog send the report to Apple doesn’t provide any support in itself: Apple does analyse them, but not in any way that’s likely to bring you a response, even if you’ve got AppleCare.

Jumping to conclusions

Sometimes observations are detailed but incomplete, and users jump to the wrong conclusions. My best example of this comes not from computing, but a nasty diving accident that occurred many years ago in Hong Kong Harbour. A local took to diving alone from a small inflatable containing an air compressor – an almost suicidal way of life, but somehow he managed to keep it going until one day, when he was at depth, his compressor stopped working, and his air supply stopped.

His only choice was to crash to the surface, and hope that his bends wouldn’t kill him. That day, he was in luck, sort of, in that a passing junk found him afloat and still breathing, although rather the worse for wear and his crash decompression. One of the crew of that junk had done some first-aid training, and observed the diver’s vital signs: he was going blue, suffering a major fit (from his bends), and his jaw was clamped very firmly shut. Good observations, but the conclusions were wrong. The first-aider decided that the diver’s airway was being obstructed by his teeth, so, using a handy pair of pliers, he extracted them all, one by one.

The other day, I noticed a tweet from someone very skilled at analysing and reversing Mac software. He’s seen Time Machine backing up to APFS (TMA), and noticed long periods during which the Time Machine icon was spinning in Finder’s sidebar, which are accompanied by significant CPU usage. He had drilled down and found the process that appeared responsible for the spinner, and apparently taking that CPU time. He tweaked a property list or two, and the wasteful spinner was gone.

I simply asked whether this was Spotlight building its indexes of backups, something which several of us have observed with TMA. He told me that occurred while backups are being made (it doesn’t in TMA), and that this spinning cursor appeared when no backup was being made. I recognised that this was likely to have coincided with the indexing process, and asked him whether he’d checked what was going on in the log at the time. He hadn’t.

Using the log for diagnosis

For all the incessant prattle that gets written to the Unified Log, it contains crucial information about almost everything that happens in, on and to your Mac. Checking in the log is one of the most important things you must do whenever you’re trying to diagnose a problem on your Mac. If you fail to study the log, your observations will always be incomplete, and your conclusions usually flawed. The exception to this is a kernel panic: most times, the effect of that is so severe that the log entries stop long before the panic, and no useful information can be gleaned from them, hence the importance of the panic log.

In the case of the spinning Time Machine icon that coincided with indexing, the investigator would have seen TMA’s backups being mounted one at a time for indexing to take place. Although that doesn’t prove that indexing was the cause of this behaviour, it at least shows you where to look next to arrive at a sound conclusion.

Few users now dare to look in the log, and I can sympathise with that fear, given the tool provided in macOS to attempt this. Console isn’t an app designed for making quick checks on what has recently happened in the log, but for viewing its live stream. It can be used to browse past log records, but it’s a clumsy tool for doing that: you have to create a logarchive containing your current log, and browse that. The supplied alternative, the log show command, is far less attractive unless you’re a Terminal wizard, and even then you may struggle composing suitable predicates to filter entries.

It’s no secret that I have a whole suite of log browsers and tools, of which I’ll draw particular attention to two:

  • Mints, which is a collection of various small tools for working with macOS. This includes pre-configured log browsers for iCloud, privacy (TCC), Time Machine, DAS scheduling, and Spotlight search.
  • Ulbow, which is my new log browser and can get pretty well anything you want from the log.

Both are available from their Product Page, where you’ll find a whole compendium of introductory and advanced articles, and other links. As with all my other tools, these are completely free, and I don’t even nag you for donations or foist ads on you.

Before the Unified Log was introduced in Sierra, it was common for most advanced users to be familiar with both Console and the log. There’s no reason now for that to be a dying art. The log is today more accessible than it has been since late 2016, and the clues it can give when you’re trying to diagnose a problem are unavailable from anywhere else.