Log Literacy: Extending Ulbow with predicates, filters & styles

Even when you’re used to writing predicates to determine which entries appear in a log extract, they’re not simple, and are best developed interactively, as are filters. Ulbow is the only utility that I know of that can do that, and can style log extracts to make them easier to read. This article explains how you can create your own predicates, filters and styles.


These consist of a series of terms that can narrow down, or expand, the entries to be shown in an extract. It’s straightforward to write single terms, but combining them into a better predicate is more of a challenge. I suggest that you develop each term interactively, pasting it into the Predicate box in one of Ulbow’s browser windows.

For example,
subsystem == "com.apple.windowmanagement"
will return only those log entries whose subsystem field is exactly as given. Make sure that it has straight double-quotation marks, not typographic ones that will result in errors. Although you can use a single equals sign =, you might like to be more consistent and use double as shown.


Paste that into the Predicate box and press the Enter key to get a fresh log extract using that predicate. Repeat that with a different predicate, such as
subsystem == "com.apple.AppKit"
that can usefully be added to broaden the results. Rather than entering the compound predicate here, use Ulbow’s Settings to add it to the popup menu.

Open the Settings window using the command in the Ulbow app menu. To add your new predicate, first select the New… item at the end of the popup menu in the top Predicate section.


Enter a name for this predicate, then paste into the predicate box your compound predicate of
subsystem == "com.apple.windowmanagement" || subsystem == "com.apple.AppKit"
to specify log entries from either of those two subsystems.


Then click the Add button just below and the name of your new predicate will appear in the popup menu.


Close Settings, then in the main window select your new predicate in the popup menu and press Enter to fetch a log extract whose entries come from either of those two subsystems.



Filters are generally simpler, and are applied to the existing log extract, so don’t need you to get a fresh log extract each time. To test your filter out, type it into the filter box and press the Tab key. Although Ulbow does support the use of regex in filters, those need to be entered through a new item in the popup menu, as explained in the Help book.

Once you’re happy with the filter to be used, open the Settings window again, and select the New… item in the Filters popup menu. Give it a name, which can be the same as the filter term itself, then enter the text to use as the filter, and click the Add button.


Close the Settings window and try selecting your new filter there. It takes effect immediately, without having to get a fresh log extract.


These are a bit more complicated, as they consist of a string defining which fields are to be shown, and how each is to be treated and coloured. However, they are much more than just aesthetic: if the style doesn’t include a field, then you won’t see any data from that field in the log extract you’re browsing. Colour is also important, as Ulbow deliberately doesn’t use fixed-length fields, or much of the window would contain empty space, so use colours to make important fields easy to distinguish.

The best way to develop a style is interactively, with the aid of two windows: Ulbow’s Help book, open at the page on Style definitions, and the Fields window, also available from the Help menu.

As an example here, start with the style definition of
0h 2g 4b 3 11fr 13fg 10
which you can type straight into the style box in Ulbow’s browser window, then press Tab for it to be applied immediately to the current log extract.


That definition will display the timestamp without the date in black, the messageType in green, the subsystem in blue, the category in black, the processImagePath truncated to just the file name in red, the senderImagePath truncated to just the file name in green, and the eventMessage in black.

Once you’re happy with a style, add it to the style popup menu using Ulbow’s settings in the same way that you did for predicates and filters, this time in the Styles section. Select the New… item at the end of the popup menu, give your style a name, paste in the definition string, and click on the Add button below.



Moving settings

Changes you make to Ulbow’s settings are saved into its preference property list. To make it easy for you to transfer your custom predicates, filters and styles to another Mac, Ulbow can export them into a separate property list, and import a property list containing custom settings to a copy of the app. Use the menu commands in the Ulbow menu to do that.


There’s even an option in Settings to determine whether imported custom settings should replace all existing settings, and a button there to reset them all to the default.

Happy log browsing.