All good log browsers provide tools to narrow down the log entries they display. Without those, it would be easy to waste all day wandering through tens of thousands of entries. One common tool provided by macOS, directly and in the log command tool, is filtering using predicates. Although LogUI provides easy access to simple predicates, to get the best from them, it’s worth digging a little deeper, as I do here.

Instant predicates

LogUI’s instant predicates filter log entries according to any of four basic predicate types:

• subsystem, such as com.apple.sharing, the field shown in yellow in log extracts;
• eventMessage, the text message listed in white/black at the end of each entry;
• processImagePath, such as mediaanalysisd, shown in blue, the name of the process making that entry;
• senderImagePath, such as libxpc.dylib, shown in red, the name of the process sending that entry.

These are quick to enter in the text box to the right of the popup menu in the window’s toolbar, but in many circumstances can prove too broad, and need narrowing down further. In other situations, you want to browse entries from two subsystems, or using a combination of criteria. The best way to do that is to write a short predicate. For single use, you can do that in the one-off predicate editor using the Set button.

When you want to reuse that, you can add it to the predicate popup menu using Settings Predicate (currently a bit kludgy).

Predicates

macOS can use predicates in other situations, most commonly for Spotlight search. If you’re interested in those, see Apple’s Predicate Programming Guide. Here I’ll describe predicates as they’re more commonly used to filter log entries, as they’re usually much simpler.

Each simple predicate consist of three parts:

• the name of one of the fields in a log entry, such as subsystem or eventMessage. This sets where the filter looks in each entry;
• an operator, which might be == for ‘equals’ exactly, or for text is commonly CONTAINS[c] for case-insensitive contains;
• text or a numeric value to look for, such as “error” or 513. Only those entries equalling or containing (or whatever the operator means) this in the specified field will then be returned from the log and displayed.

Here are some basic examples.

eventMessage CONTAINS[c] "error"
entries will only be those with the text error in their message field.

subsystem == "com.apple.duetactivityscheduler"
entries will all have that text, ignoring case, but only that text, as the name of their subsystem.

subsystem CONTAINS[c] "com.apple.xpc"
entries will have any subsystem containing that text, which also includes com.apple.xpc.activity.

Fields

Although you can use any of the fields shown in LogUI (and some that aren’t), the most commonly used are, in order as they are shown in LogUI’s window:

• eventType (red) – matches the type of event, such as logEvent (1024), traceEvent (768), activityCreateEvent (513), or activityTransitionEvent (514). Can be given as characters (case-sensitive) without quotation marks, or using the digits given in parentheses. Use these only with the operators == or !=, as they are treated as numbers rather than text.
• category (green) – this matches the category, and varies according to subsystem. This is given as text in quotation marks, and is normally lower-case.
• messageType (white/black) – matches the type of message for logEvent and traceEvent, and includes default (0), release (0), info (1), debug (2), error (16), and fault (17). Can be given as characters (case-sensitive) without quotation marks, or digits as shown in parentheses. Use these only with the operators == or !=, as they are treated as numbers rather than text.
• senderImagePath (red) – this matches the text pattern in the name of the sender, which might be the name of a library, extension, or executable.
• processImagePath (blue) – this matches the text pattern in the name of the process that originated the event.
• subsystem (yellow) – this matches the subsystem specifier, e.g. com.apple.TimeMachine, given as text in quotation marks. You may find it best to use CONTAINS[c] rather than ==, to allow for differences in case and extended subsystem specifiers.
• eventMessage (white/black) – for this, you specify a text pattern, or text, within the message, given as text in quotation marks.

Operators

The following comparisons and other operators are available:

• == (two equals signs) for equality
• != or <> for inequality
• >= or => for greater than or equal to
• <= or =< for less than or equal to
• > for greater than
• < for less than
• AND or && for logical and
• OR or || for logical or
• NOT or ! for logical not
• BEGINSWITH, CONTAINS, ENDSWITH, LIKE, MATCHES for string comparisons, using regex expressions when desired; strings can be compared with case insensitivity and diacritic insensitivity by appending [cd] to the operator, e.g. CONTAINS[c] means case-insensitive comparison
• FALSE, TRUE, NULL have their expected literal meanings.

There are others as well, but you’ll seldom use them to filter log entries.

Building complex predicates

To see the scheduling and dispatch of background activities by DAS-CTS, you need to look at log extracts showing both their entries. Use the predicate
subsystem == "com.apple.duetactivityscheduler" OR subsystem CONTAINS "com.apple.xpc"
to do that. The first part of it includes those entries from DAS, and the second includes those for XPC and its relatives that run CTS. Using an OR between the two parts combines both sets of entries in the one extract.

To see the reports posted by XProtect Remediator, you need to look at those entries made by its subsystem that have the right category, using the predicate
subsystem == "com.apple.XProtectFramework.PluginAPI" AND category == "XPEvent.structured"
Using the AND operator ensures that the only entries shown come from that one subsystem, and they are given just that category.

Time Machine involves a combination of different subsystems and messages. To get a good overview of relevant entries, you can use
subsystem == "com.apple.TimeMachine" OR
(subsystem == "com.apple.duetactivityscheduler" AND eventMessage CONTAINS[c] "Rescoring all") OR
(subsystem == "com.apple.xpc.activity" AND eventMessage CONTAINS[c] "com.apple.backupd-auto") OR
eventMessage CONTAINS[c] "backup" OR
eventMessage CONTAINS[c] "Time Machine" OR eventMessage CONTAINS[c] "TimeMachine"
I’ve broken this down into separate lines, but you shouldn’t do that in the predicate. Taking it line by line it becomes simpler to understand. Use parentheses () to group each part of the predicate carefully as shown.

You can see other examples in the Help book for my free utility Mints: the Further Information pages towards the end give each of the predicates that Mints uses for its log extracts.

Quick summary

• [field name] [operator] [text or numeric value]
• common field names: senderImagePath, processImagePath, subsystem, eventMessage
• common operators: ==, CONTAINS[c]
• filter info: “text”
• combine filters using AND, OR.

This week’s new features in my lightweight log browser LogUI tackle two important areas: initial checks to confirm that the app can access the log, and improving the filtering of log entries using predicates.

LogUI has three key requirements:

• that the Mac is running macOS 14.6 or later, as enforced by macOS;
• that it’s run from an admin account, as that has the privileges required to access the log;
• that there are log records it can access in the path /var/db/diagnostics, as without those it hasn’t got anything to work with.

LogUI 1.0 build 31 now contains code to check the latter two, run soon after launch. If either fails, you’ll see an informative alert, and the app will quit when you click to dismiss that.

LogUI now has internal features to support a wide range of filters that can be applied when fetching log entries. These are an essential means of reducing the number of entries displayed, and of focussing your attention on what’s important.

This is reflected in its Settings, which now refer to Text rather than a Subsystem. The window toolbar now has a Predicate popup menu, and its text box is labelled text rather than Subsystem.

This menu offers the following options:

• none, which applies no filtering and displays all log entries;
• subsystem, which uses the text entered as the name of the subsystem whose entries are to be displayed, as in the previous builds;
• eventMessage, which shows only those log entries whose message contains the text entered;
• processImagePath, which shows only entries whose process name (or path) contains the text entered;
• [Edit], which in future will open an on-the-fly predicate editor, but currently doesn’t filter;
• TimeMachineBasic to blowhole, which use set predicates to display log entries for those features. The first two are different levels of detail for Time Machine backups, error finds entries with that word in their message, kernel finds entries with the kernel as their process, and blowhole finds entries made by my command tool for writing entries in the log.

Text entered is not case-sensitive.

Although it’s currently possible to change and extend those, that involves delicate surgery to LogUI’s preferences Property List, and I don’t intend you to hack that just yet. The next features will provide a proper editor in LogUI’s Settings, and the on-the-fly editor accessed through this menu.

Otherwise LogUI should work just the same as the last build. These new features are documented in its Help book, a separate copy of which is supplied in its Zip archive.

LogUI 1.0 build 31 is now available from here: logui131
and I will shortly be giving it an entry in my log browser Product Page, to make it easier to access. I’m also looking at building an auto-update mechanism into it.

Please let me know how you get on with this, and whether it proves useful to you. Enjoy!

If you ever need to understand what’s going on in your Mac, reading its log is essential. However much you might stare at Activity Monitor, read source code or disassemble components of macOS, what you can see in the log tells you what has really happened. Whether it’s a bug or an unexpected event, it’s the only way to look back and discover what went on.

For most, Console isn’t the right tool. It only offers the options of viewing its live stream, or making an archive of the whole log and wading through that when you need to look at an event in the past. Although my log browser Ulbow gives much better access, for many it’s still a daunting task. I’ve now switched almost entirely to using my new lightweight log browser, LogUI, and here explain how you can use it. Although it’s currently an early release with limited features, you should find it ideal for getting started.

LogUI 1.0 build 27 is available from here: logui127

This comes as a Zip archive, so unZip it, and move the LogUI app to another folder before running it for the first time; your main Applications folder is fine, and almost anywhere will do nicely. Alongside it is a copy of the PDF Help file that’s also inside the app, so you can refer to it when you’re not running LogUI. As the two are identical, you can trash the separate copy if you’re happy to use that inside the app.

Before opening LogUI, generate an event that you can examine in the log. One starter might be launching an app. Try to do this when your Mac is otherwise quiet and unoccupied: if Activity Monitor shows it’s busy with lots of background tasks, then the log could be filling with noise, when what you want most is peace. For the sake of simplicity, time this on an even minute, and make a mental note of that time to the second.

As soon as you’ve done that, open LogUI and you’ll be greeted by its window, with its toolbar ready for you to set up and get your first log extract. That should be set as follows:

• Start to the current date, hour and minutes. As those are set to the time you open the window, they should already be close to the time of the event. Just after the stepper control is the seconds setting. If the event occurred a moment after the seconds changed to 00, that makes a convenient time to start your log extract.
• Period set to around 5 seconds. This value can be floating point decimal, so might be 2.5 seconds for a smaller log extract.
• Max entries set to 1000 to start with.
• Show Signposts not ticked.
• Full Fields ticked.
• Subsystem empty.

Then click on Get Log to see the log extract for that period.

In my case, a five second period overfilled the 1000 I had set in Max entries. Scrolling to the foot of the extract showed that had been reached in less than two seconds, so I increased Max entries to 10000 and clicked Get Log again.

There are now over 5,000 entries in the extract, but they scroll smoothly enough to let me look around them.

The best way of reducing the number of entries to make them more understandable is to add a Subsystem as a filter. In this case, as I’ve launched an app, I can get most useful information from LaunchServices, by entering
com.apple.launchservices
into Subsystem. I also reduce the number of fields shown by unticking the Full Fields box, letting me concentrate on the messages. You can toggle Full Fields without having to get log entries again, as it only affects the fields within those entries that are shown in the window. Then click on Get Log again.

Scrolling down through the 358 entries remaining, I quickly reach one with a message field reading
LAUNCH: translocate to <private> from <private>
Although we could do without the privacy censorship here, it’s easy to work out that the app I just launched underwent app translocation, and that’s confirmed a little further down when LaunchServices gives its full path.

If you want a copy of the text from one or more selected entries, use the Copy command (Command-C), then paste it into any text editor. That doesn’t copy all the fields, only those you’re most likely to need elsewhere. For a full copy of that log extract, with colours indicating the fields, click on the Save as RTF button. As with LogUI’s window title, saved files are given default file names containing the start time of that log extract to help you keep them in good order.

This is the same log extract seen in my rich text editor DelightEd.

Finally, open LogUI’s Settings to enter the defaults you want its windows to open with. These match controls in its toolbar. The last of those, Light Mode, enables you to run the whole app in Light Mode if you prefer. For that to work, your Mac will also need to be in Light Mode, and you should tick that box, close the Settings window and quit the app. When you next open it, it should operate in Light Mode. Other changes made to Settings don’t need you to quit the app for them to take effect.

Enjoy!

I have just replaced LogUI 1.0 build 25 with build 27. This:

• completes support for Signposts by including them in RTF files,
• changes the Settings dialog to use Full Fields for consistency,
• updates technical info with a link to original source code.

You can now download build 27 from here: logui127
or from the link in the original article.

Last week I introduced my new prototype log browser, LogUI, which seems to have been popular with many. As I now use it in preference to its predecessor Ulbow, I’ve spent a little time adding some new and improved features to bring you version 1.0 build 25. Changes include:

• support for discontinuous selection of log entries,
• support for copying text from selected log entries,
• subsystem names are now case-insensitive,
• support for Signposts,
• window names change to include the start time of each log excerpt,
• RTF saved file names change to reflect the start of each log excerpt.

Settings

These now let you set app defaults for displaying full log entries, and for fetching and displaying Signposts.

Browser controls

The only addition to these is the option to Show Signposts. When that’s ticked, Get Log also fetches all Signposts during the set period, and displays them inline with regular log entries.

LogUI now supports all types of log entry:

• regular log entries,
• Activities, events such as clicks/taps and others,
• Boundaries, markers such as the start of the boot process,
• Signposts, used to record significant steps and assess performance.

Signposts have their own custom fields, including signpost ID, name, and type, which are displayed when Full Fields are enabled. The only caution with Signposts is that they can outnumber regular log entries, so if you don’t need to see them, it’s better to leave them turned off.

I’m grateful to Joe for asking for the subsystem to be case-insensitive. This means that you can enter com.apple.TimeMachine or com.apple.timemachine as the subsystem and LogUI will display entries with a subsystem name of com.apple.TimeMachine for both. No longer will case trip you up.

Log entries

The biggest changes are in the selection and copying of log entries. You can now select log entries in a browser window. Selections can be multiple continuous using the Shift key modifier, and discontinuous using the Command key modifier. When one or more entries have been selected, you can then copy their text contents using the Copy command or Command-C. Copied text can then be pasted into an app that supports handling of text items in the Clipboard.

Because there are many different fields possible in each entry, copied text consists of a standard set:
date level sender process subsystem message
each separated by a Tab character.

If you want more fields with colour, save the log excerpt in RTF, open it in an RTF editor and copy from that.

If you’re a developer and are wondering how I have implemented this copy feature for a SwiftUI List, let me know and I’ll explain how I managed to pin this tail on the donkey while I was blindfolded, or how persistent guessing overcame the absence of documentation or example code.

Naming

To distinguish between windows and saved RTF files, LogUI now automatically names and renames its windows and the default file names suggested when saving files. Names are based on the Start date and time of the current log excerpt in that window. To begin with, when there’s no log extract, each new window is named LogUI. When it gains its first extract, the date and time are appended to that, e.g. LogUI 2025_03_03_08-14-00, and a similar default file name is offered. When you obtain a new log excerpt in the same window, those names are updated to reflect the changed Start date and time.

Help book

This has been updated to include all these changes.

LogUI 1.0 build 27 is now available from here: logui127
It still requires a minimum macOS version of 14.6, I’m afraid, because of the SwiftUI features it has to rely on.

Enjoy!

Postscript

I have replaced build 25 with 27. This completes support for Signposts, by including them in saved RTF files. I’ve also taken the opportunity to make a small correction in the Settings dialog, and to add a link to the technical info to the log access source code.

Although I often use my free log browser Ulbow daily, and it serves its purpose well, it’s time to move on with changing macOS and its APIs, and do better. Ulbow still relies on the log command tool to get its log extracts, and its front end is thoroughly AppKit.

Apple introduced the Unified log in macOS Sierra back in 2016, and at that time the only way to access it was using the log command tool, which isn’t among those for which it has provided source code. It wasn’t until Catalina in 2019 that Apple provided an API allowing developers to obtain log entries direct. As that wasn’t retro-fitted, the few apps that access the log couldn’t use that on Macs running Mojave or earlier, limiting its usefulness until relatively recently. When I developed Consolation in 2017, and its successor Ulbow two years later in 2019, I therefore continued to rely on the log command tool to obtain log extracts.

By a curious coincidence, SwiftUI was also first released for macOS in 2019, although it has taken an extraordinarily long time to approach maturity. Over the last couple of years it has improved to the point where some outstanding apps like OmniFocus have now abandoned the older AppKit API in favour of SwiftUI.

Last summer I had a first go at writing a potential replacement for Ulbow using the combination of OSLog to give direct access to log entries, and SwiftUI for its interface. At that time I reached an impasse largely as a result of excessive memory use and a memory leak that I was unable to resolve, and concluded that “Ulbow already performs better than LogUI ever could.”

More recently I have returned to that project and accepted that trying to support older versions of macOS before Sonoma is too great an impediment. Calling on some newer features in SwiftUI I have made better progress and, although not entirely continent in its use of memory, I now have an experimental version that I’m using daily. It appears robust and stable, and shouldn’t run away with all your Mac’s memory. Although it currently lacks key features like Find/Search and the ability to copy text from its browser window, it can store log extracts in rich text format.

Its Settings establish defaults common to all new browser windows:

• Subsystem allows you to filter entries by a single predicate for one specified subsystem.
• Period lets you set a default period for log excerpts, given in decimal seconds, so you can set 2.5 seconds if you wish.
• Max entries is the limit of entries to be fetched and displayed. This can be set as high as 20,000 or even more.
• Light Mode will set the app’s windows to Light Mode when you next open the app, if your Mac is also set to run in Light Mode. This allows you to opt out of Dark Mode if you really must.

Window controls let you override the first three of those defaults, and add

• Start, a date and time to start the log excerpt.
• Full Fields, whether to show all fields or just a shortened selection.
• Get Log button to get a log excerpt.
• Save as RTF button to write the log excerpt out to a rich text file.
• The count of entries in the current excerpt.

The end result is, I think, a considerable improvement on Ulbow, in terms of readability, without sacrificing too much space as in Console’s rigid columns.

This experimental release comes with its own PDF documentation, also accessible within the app as its Help book. I’d be very grateful if you could take it out for a spin and see how robust its log engine is, and whether you prefer its new layout for log entries. You can download a copy from here: logui120
Note that it requires a minimum macOS version of 14.6, to ensure that it doesn’t rob your Mac of memory.

Once its engine is reliable, I will add more features, starting with Search/Find support, and the ability to copy entries from its window.

Thank you, and happy logging around.