How to Use the macOS log stream Command to Debug Application Crashes

The Shift from Traditional Log Files

Historically, diagnosing application crashes or erratic system behavior on a Mac involved opening the Console application and reading plain-text files located in /var/log/system.log. However, starting with macOS Sierra (10.12), Apple introduced the Unified Logging System. This architecture drastically changed how macOS handles telemetry.

Instead of writing text to flat files, macOS now streams log data in a compressed, binary format directly into memory and dedicated data stores. While this greatly improves system performance and security, it makes traditional command-line tools like tail, grep, and cat completely useless for reading live system logs.

To interact with the Unified Logging System from the Terminal, administrators and developers must use the log command. Specifically, the log stream subcommand is essential for live debugging.

Understanding the log stream Command

The log stream command attaches to the live logging buffer and outputs events in real-time to your Terminal window. If you run log stream by itself, your Terminal will immediately be flooded with thousands of messages per second from background daemons, kernel extensions, and user applications.

Because the volume of data is so immense, the true power of log stream lies in its filtering capabilities, known as predicates.

Step 1: Filtering by Subsystem or Process

When an application crashes or fails to launch, you only want to see logs generated by that specific application. You can filter the stream using the --process argument.

log stream --process "Safari"

This will stream only the events generated by the Safari browser. However, a modern macOS application often relies on various background XPC services and frameworks. To capture a broader picture, you can filter by --subsystem.

log stream --subsystem com.apple.TimeMachine

Step 2: Advanced Filtering with Predicates

For deep debugging, you need to use NSPredicate syntax. This allows you to chain multiple conditions together to isolate the exact error causing an application crash.

For example, if you are troubleshooting a third-party application named “DeveloperApp” and you only want to see messages classified as “Error” or “Fault”, you can construct a predicate:

log stream --predicate 'processImagePath CONTAINS "DeveloperApp" AND (messageType == error OR messageType == fault)'

This command silently monitors the system until the application throws a critical error, at which point the exact trace is printed to the screen.

Step 3: Revealing Private Data

One of the most frustrating aspects of the Unified Logging System for developers is that macOS actively censors sensitive data in the logs to protect user privacy. Variables like file paths, URLs, or user IDs are often replaced with the string <private>.

If you are attempting to debug why an application cannot read a specific file, seeing Failed to open <private> is unhelpful.

To force macOS to reveal this data during a live debugging session, you must use the --info and --debug flags, and sometimes install a specific configuration profile (if SIP allows it), but temporarily showing info-level messages can be done directly:

sudo log stream --level debug --predicate 'process == "Finder"'

Note: Since macOS Big Sur, disabling the privacy redaction entirely across the system requires a custom Configuration Profile deployed via MDM, but filtering deeply can often extract the context you need.

Step 4: Formatting the Output

By default, log stream outputs data in a dense, tabular format. If you need to export this data to another tool (like a Python script) for further analysis, you can instruct the command to output raw JSON.

log stream --process "Mail" --style json

This prints a continuous stream of JSON objects, which can be piped directly into jq for real-time parsing and alerting.

Conclusion

The macOS Unified Logging System is a highly efficient, high-performance telemetry engine. By mastering the log stream command and NSPredicate filtering, Mac administrators and developers can cut through the noise and immediately pinpoint the root cause of application crashes, kernel panics, and permission failures.