For many years, I believed what the log command told me, that log entries could contain any of the 26 or more fields available, although they didn’t. It was only as I was developing utilities like LogUI that I discovered that log entries come in (at least) four types, each with its own format and set of fields. This article is a guide to those, and how they are displayed in LogUI.

Entry fields

Those available in the OSLog API are fewer in number than appear in log command output, and include some of limited interest. Those not exposed in LogUI include:

• store category, which is invariably disk storage here.
• format string, that used to format the contents of messages. This was introduced following serious security leaks in High Sierra.
• components, linking in with the format string. LogUI displays each entry using the same order of fields and colour-coding. Although they can’t all be seen together in any single log entry, the overall sequence is:

Standard levels are given as text, and chosen from one of the following: fault, error, notice, info, debug, undefined. These are only used with Regular log entries, not other types. LogUI always includes debug level entries when they’re available.

The four types of entry are:

1. Regular
2. Activity
3. Boundary
4. Signpost.

Regular entries

These are normally by far the most common, and are seen throughout the processes and subsystems writing log entries. They normally contain up to the following fields: datestamp, [1], activity ID, category, level, sender, process, process ID, subsystem, thread ID, message

These examples include: datestamp, 1, activity ID, category, level, sender, process, process ID, subsystem, thread ID, message which is fairly normal.

Activities

These mark specific activities, and vary according to the process and subsystem. Some are valuable waypoints, and all are recognisably shorter than most regular entries, containing only the following fields: datestamp, [2], activity ID, parent activity ID, sender, process, process ID, thread ID, message

These are examples of one of the most valuable activities reported, indicating a mouse-click or tap. They’re also complete, as they consist of: datestamp, 2, activity ID, parent activity ID, sender, process, process ID, thread ID, message

Boundaries

These are rare but instantly recognisable because of their brevity. They consist of just three fields: datestamp,[3], message

Two of the most important are the announcement of the start of kernel boot:

and adjustment of the internal clock:

These are also easy to search for, as their message contains the distinctive === string.

Signposts

By default, LogUI extracts omit Signposts, but if you tick the Show Signposts box before loading log entries, they will also be displayed. In parts, they can outnumber regular entries, and are unlikely to provide you with meaningful information unless you know internal details of their process. Each Signpost adds three type-specific fields, shown after the process ID: datestamp, [4], activity ID, category, sender, process, process ID, signpost ID, signpost name, signpost type, subsystem, thread ID

These examples come from the most prolific user of Signposts, SkyLight for WindowServer, and contain datestamp, 4, activity ID, category, sender, process, process ID, signpost ID, signpost name, signpost type, subsystem, thread ID Note there’s no message field, as their meaning is determined by the signpost fields.

Datestamps and times

The OSLog API doesn’t currently give access to Mach times, only to opaque Date variables. From those, LogUI’s datestamps give: year–month–day hour:minute:second.microsecond+timezone

All times and time zones given are those current when LogUI obtains that extract, not when that entry was written. This can become extremely confusing when clocks change to and from daylight savings time, and when passing through time zones, and great care is required when reading logs containing such corrections. LogUI tries to make this easier, but care is still required.

If you have used the log command, you may be aware that can return Mach times as ticks, offering precision down to the nanosecond. This currently isn’t possible when using the OSLog API, but given the relatively slow clock of Apple silicon Macs, it’s no longer as useful as it used to be with Intel’s nanosecond Mach ticks.

Censorship

By default, all data in message fields is censored to protect the privacy of the user. This replaces chunks of text with the dreaded <private>, and can render many entries devoid of any useful information. In recent versions of macOS log privacy can be removed by installing a profile. However, that doesn’t apply retrospectively, only to log entries collected after the profile has been installed.

Removing privacy also increases the size in storage of log entries, and may reveal sensitive information. As soon as you have completed acquisition of the logs you need with privacy removed, you should therefore remove the profile, to allow normal censorship to resume.

A suitably signed profile is here: enablelogprivatedata

To install the profile, unzip the archive into a convenient folder and double-click it. You’ll be informed by a notification that you need to review the profile to install it. Open System Settings and select Device Management in its View menu, or search for it. Follow the instructions given there to install and activate it.

Sadly, this doesn’t cover all censorship. Some systems require additional configuration changes, for example CFNetwork diagnostic logging. Jeff Johnson explained how to enable that, but Apple has since blocked that, and I don’t know of a practical alternative. In some cases, additional detail can be obtained by adjusting log settings.

Summary

A short practical summary of LogUI’s log entries is provided in its Help book.