Much of our literature is based on a few legends. When one pirate, William Kidd, was believed to have buried his ill-gotten gains on Gardiners Island, that formed the basis of many adventure stories, including Washington Irving's Wolfert Webber, Edgar Allan Poe's The Gold-Bug, and Robert Louis Stevenson's Treasure Island, and dozens of derivatives. Last week I too was digging for buried treasure, this time in the deep soil of the macOS log.
Following up on my previous observations of Battery Centre (com.apple.BatteryCenter) and its log entries recording checks on wireless input devices and UPS, my first task was to build myself a shovel using SwiftUI, a utility I've named Unhidden for several good reasons. Although I'll be releasing and explaining that tomorrow (Monday) morning, in this article I'll explain why it, and other log analysis tools, are so valuable.
For the last eight years, since its introduction in Sierra, macOS has written copious entries into its Unified log. Although supported from the start by the log command tool, for the first three of those years, third-party developers were denied direct access to the new log. Even now, reading log entries using Swift is rudimentary to say the least: for example, the API still can't deliver a collection of entries written during an arbitrary period, which can only be achieved by calling the log command to deliver them in JSON format, and parsing that. Given those limitations, all my previous utilities that retrieve log entries have relied on the log command; Unhidden is the first of them to use the Swift API of OSLog.
If Apple intended the Unified log and its bad habits, like censoring so much key information with <private>, as a means of obfuscating macOS internals, it was hugely successful. Seasoned Mac experts who had previously gained much from browsing the log found themselves submerged in so much log chatter that most abandoned all further attempts. So many developers gave up trying to make use of the log that Apple is still trying to win them back. In High Sierra, using the newfs_apfs command to encrypt a previously unencrypted APFS volume leaked passwords in plain text to the Unified log for six months until Sarah Edwards discovered the bug, and Apple fixed it in 10.13.4.
Those who use my utility T2M2 will be aware of how its analysis of log entries makes them aware of serious problems occurring in their Time Machine backups that are never reported to the user. Two years ago, log entries confirmed the function of a new form of XProtect, Remediator, and how it runs periodic scans looking for malware. The only way to tell if APFS trims volumes is to read the entries it writes in the log, and for many other systems in macOS log entries are the only evidence of their completing key tasks successfully.
This journey into com.apple.BatteryCenter started with chance observations that revealed how macOS may periodically interrogate what Apple terms Human Interface Devices, or HID (hence Unhidden), to discover key information including their battery charge status. As far as I'm aware, there's no public API to perform that, and the only approach is to dig through the I/O Registry, a task akin to searching for treasure using the clues to a cryptic crossword puzzle instead of a map.
After drawing a complete blank in Apple's documentation I discovered that BatteryCenter is a Private Framework new to macOS Sonoma 14.0, and didn't exist in Ventura, where similar information came from com.apple.iohid. Alongside are two related user interface frameworks, BatteryCenterUI and BatteryUIKit, making a total of three of the over 1,600 private frameworks in Sonoma, and presumably destined for Sequoia. Whether they'll ever make the leap to being part of the public API appears doubtful, so for the time being, the only way to access them is through their entries in the log.
When it comes to searching for buried treasure in macOS, there's nowhere as rewarding as the Unified log. There may be no maps, and when we need shovels all Apple provides are trowels, but there's more silver and gold here than there ever were on Gardiners Island.
