The unified log in macOS Mojave: Signposts and Instruments

macOS 10.14 Mojave does bring changes to the unified log after all: this article is a short summary of information released by Apple so far, mainly in Session 405 at WWDC 2018.

Before Apple introduced the unified log in macOS 10.12 Sierra in 2016, system logs were widely used by system engineers, developers, system administrators, and advanced users for a whole range of different purposes, from security to checking backups.

The unified log may have been a great benefit to Apple’s engineers, but most other log users found themselves at sea without a liferaft. The new logs are full of thousands of messages, the vast majority of which are of little interest to anyone other than the systems engineer, and the tools provided – Console and the log command – didn’t (and still don’t) help access.

Established practices in earlier versions of macOS, like scrolling through startup looking for signs of conflicts and problems, became impossible when the first minute often contained more than 10,000 log entries. Checking for attempts to log in became futile, as the few log entries which might have indicated attempts were drowned in thousands or even millions of irrelevant entries. Most advanced users have, as a result, abandoned browsing the log, and tried to solve problems without its benefit.

High Sierra brought no signs of any change. The unified log continues to collect its torrent of messages, and the Console app has improved very little, still only giving access to live streamed entries or huge logarchives. Apple’s stated purpose of unified logging is that “it’s our way of getting debugging information out of the system”, and to hell with anyone else.

Mojave is set to offer no respite or solution for the system administrator or advanced user. Console and the log command may have gained a few tweaks, but there are no signs of their being any more capable. However, Apple is introducing new features which should be very helpful to developers, particularly when optimising and tuning their products. As with WWDC 2018 as a whole, Mojave’s log is now about ‘doubling down’ on performance.


Prior to Mojave, developers had standard access to the unified log, but nothing to help optimise a product. Code could write to the log using something along the lines of
let logHandle = OSLog(subsystem: "com.myco.testapp", category: "Mark")
os_log("Entry point %{public}@", log: logHandle, type: .info, entryName)

which might write the eventMessage Entry point here with the subsystem com.myco.testapp and the category Mark, i.e. com.myco.testapp.Mark.

Using this to analyse performance has not been easy, though, with Apple’s standard tools. Consolation has been able to export log extracts to CSV format, from which they can be analysed in spreadsheets and elsewhere, but until now, Apple hasn’t provided developers with anything comparable. Mojave addresses this with a system of Signposts and Points of Interest, which are automatically picked up and analysed using Xcode 10’s Instruments.

The following code gives an idea of their use:
let refreshLog = OSLog(subsystem: "com.myco.testapp", category: "Refresh")
let spidForRefresh = OSSignpostID(log: refreshLog)
os_signpost(.begin, log: refreshLog, name: "Fetch", signpostID: spidForRefresh)
// do something
os_signpost(.end, log: refreshLog, name: "Fetch", signpostID: spidForRefresh)

which writes a begin and end signpost named Fetch for the category Refresh (i.e. com.myco.testapp.Refresh) with the matching Signpost ID of spidForRefresh. Signposts can have ‘metadata’ attached, which are roughly comparable to the contents of a normal eventMessage in os_log. Signposts additionally support an .event type as well as .begin and .end.

Points of Interest allow the developer to track where in the app a user is at a given moment, using the category .pointsOfInterest.

Apple has an ingenious single switch which saves the developer from having to phrase this all in conditional code. An example of its use is:
let refreshLog: OSLog
if ProcessInfo.processInfo.environment.keys.contains("SIGNPOSTS") {
refreshLog = OSLog(subsystem: "com.myco.testapp", category: "Refresh")
} else {
refreshLog = .disabled

When the build key SIGNPOSTS is not defined, this effectively makes all signpost code null operations.


With your source code suitably instrumented using Signposts and Points of Interest, those can be monitored and analysed using Xcode 10’s Instruments. Demonstrations of this were very impressive, although it’s not yet clear how much effort is needed to transform demonstration Instruments for your own purposes. Apple’s Chad Woolf referred in passing to an Instrument consisting of over a hundred lines of XML, which suggests that they are not trivial.

Apple has not stated how Signposts work with respect to the unified log. Already there are two main routes of access: stored logs are accessed via the log show command, and a live stream by log stream and the Console app. Signposts may be part of the live stream and never make it into storage, or they may be a second live stream to which the log command has no access.

For developers, particularly teams, Signposts and Points of Interest should make performance tuning much easier, and the unified log of greater use. Smaller teams and singletons will have to hope that custom Instruments are not too difficult to create.

Signposts already have support from Swift and C, and should be straightforward for other compiled languages within the Xcode environment, provided that they can use the required Instruments. For scripters working in a shell or AppleScript, even if they were able to generate Signposts, it seems unlikely that they will be able to perform any useful analysis, and tools like Blowhole are likely to remain their best course. I will, of course, be looking at Signposts to see whether they can be used successfully from other development environments.

Mojave’s unified log will at least help developers tune their software and ‘double down on performance’, with the powerful new tools of Signposts and Xcode Instruments. However, there is no sign of any change which might help system administrators or advanced users – not from Apple, at least.