The unified system log on Apple platforms gets a lot of stick for being ‘too verbose’. I understand that perspective: If you’re used to a traditional Unix-y system log, you might expect to learn something about an issue by manually looking through the log, and the unified system log is way too chatty for that. However, that’s a small price to pay for all its other benefits.
This post is my attempt to explain those benefits, broken up into a series of short bullets. Hopefully, by the end, you’ll understand why I’m best friends with the system log, and why you should be too!
If you have questions or comments about this, start a new thread and tag it with OSLog so that I see it.
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
Your Friend the System Log
Apple’s unified system log is very powerful. If you’re writing code for any Apple platform, and especially if you’re working on low-level code, it pays to become friends with the system log!
Friends with Benefits
The public API for logging is fast and full-featured.
And it’s particularly nice in Swift.
Logging is fast enough to leave log points [1] enabled in your release build, which makes it easier to debug issues that only show up in the field.
The system log is used extensively by the OS itself, allowing you to correlate your log entries with the internal state of the system.
Log entries persist for a long time, allowing you to investigate an issue that originated well before you noticed it.
Log entries are classified by subsystem, category, and type. Each type has a default disposition, which determines whether that log entry is enable and, if it is, whether it persists in the log store. You can customise this, based on the subsystem, category, and type, in four different ways:
-
Install a configuration profile created by Apple (all platforms).
-
Add an
OSLogPreferencesproperty in your app’s profile (all platforms). -
Run the
logtool with theconfigcommand (macOS only) -
Create and install a custom configuration profile with the
com.apple.system.loggingpayload (macOS only).
When you log a value, you may tag it as private. These values are omitted from the log by default but you can configure the system to include them.
The Console app displays the log, both on the local Mac and on attached iOS devices. It also opens log snapshots (.logarchive). It also supports surprisingly sophisticated filtering.
The log command-line tool lets you do all of this and more from Terminal.
There’s a public API to read back existing log entries, albeit one with significant limitations on iOS (more on that below).
Every sysdiagnose log includes a snapshot of the system log, which is ideal for debugging hard-to-reproduce problems. For more information about sysdiagnose logs, see the info on Bug Reporting > Profiles and Logs.
But you don’t have to use sysdiagnose logs. To create a quick snapshot of the system log, run the log tool with the collect subcommand.
For more information, see:
[1] Well, most log points. If you’re logging thousands of entries per second, the very small overhead for these disabled log points add up.
Foster Your Friendship
Good friendships take some work on your part, and your friendship with the system log is no exception. Follow these suggestions for getting the most out of the system log.
The system log has many friends, and it tries to love them the all equally. Don’t abuse that by logging too much. One key benefit of the system log is that log entries persist for a long time, allowing you to debug issues with their roots in the distant past. But there’s a trade off here: The more you log, the shorter the log window, and the harder it is to debug such problems.
Put some thought into your subsystem and category choices. One trick here is to use the same category across multiple subsystems, allowing you to track issues as they cross between subsystems in your product.
Don’t use too many unique subsystem and context pairs. As a rough guide: One is fine, ten is OK, 100 is too much.
Choose your log types wisely. The documentation for each OSLogType value describes the default behaviour of that value; use that information to guide your choices.
Remember that disabled log points have a very low cost. It’s fine to leave chatty logging in your product if it’s disabled by default.
No Friend Is Perfect
The system log API is hard to wrap. The system log is so efficient because it’s deeply integrated with the compiler. If you wrap the system log API, you undermine that efficiency. For example, a wrapper like this is very inefficient:
// -*-*-*-*-*- DO NOT DO THIS -*-*-*-*-*-
void myLog(const char * format, ...) {
va_list ap;
va_start(ap, format);
char * str = NULL;
vasprintf(&str, format, ap);
os_log_debug(sLog, "%s", str);
free(str);
va_end(ap);
}
// -*-*-*-*-*- DO NOT DO THIS -*-*-*-*-*-
This is mostly an issue with the C API, because the modern Swift API is nice enough that you rarely need to wrap it.
If you do wrap the C API, use a macro and have that pass the arguments through to the underlying os_log_xyz macro.
iOS has very limited facilities for reading the system log. Currently, an iOS app can only read entries created by that specific process, using .currentProcessIdentifier scope. This is annoying if, say, the app crashed and you want to know what it was doing before the crash. What you need is a way to get all log entries written by your app (r. 57880434).
Xcode’s console pane has no system log integration (r. 32863680). I generally work around this by ignoring the console pane and instead running Console and viewing my log entries there.
Revision History
-
2022-06-23 Added the Foster Your Friendship section. Made other editorial changes.
-
2022-05-12 First posted.
