How to Use the log stream Command in macOS Terminal to Debug Real-Time Unified System Logs

Prior to macOS Sierra, troubleshooting system anomalies on Apple computers involved tailing static text files inside /var/log. Modern macOS releases use the Apple Unified Logging System, an enterprise-grade memory-mapped binary logging framework that captures events from the kernel, Darwin subsystems, third-party applications, and security daemons. While the graphical Console.app provides access to these logs, it often stutters under heavy throughput. The log stream terminal command allows developers and sysadmins to stream, filter, and inspect live macOS system logs with microsecond precision.

Basic Syntax and Fundamental Behavior of log stream

Executing log stream without arguments streams every single event generated across all hardware sensors, background daemons, and active applications in real time:

log stream

Because modern Macs generate thousands of events per second, streaming without filtering will immediately overwhelm your terminal buffer. To extract actionable debugging telemetry, exact filtering expressions must be specified.

Filtering by Process Name or Process ID (–process)

To inspect logs generated exclusively by a specific application or background daemon (such as Safari, Bluetooth daemon, or Finder), use the --process flag:

log stream --process Bluetooth
log stream --process "Safari"
log stream --process 45812

This filters out background system chatter, displaying only diagnostic output initiated by that target process.

Advanced Filtering with Predicates (–predicate)

The true power of log stream lies in Apple’s NSPredicate syntax, which supports granular logical filtering by subsystem, category, message content, and log level:

1. Filtering by Subsystem and Category

Apple engineering organizes system components into reverse-DNS formatted subsystems (such as com.apple.wifi or com.apple.TimeMachine):

log stream --predicate 'subsystem == "com.apple.wifi"'
log stream --predicate 'subsystem == "com.apple.TimeMachine" && category == "General"'

2. Filtering by Log Level (Error and Fault Only)

By default, log stream captures informative messages, debug strings, and notices. To isolate critical errors and kernel faults while troubleshooting crashes or peripheral disconnects:

log stream --predicate 'messageType == error || messageType == fault'

3. Searching Message Text Content

To locate specific strings or error codes appearing within log message bodies, use the CONTAINS or BEGINSWITH predicate operators:

log stream --predicate 'eventMessage CONTAINS[c] "authentication failed"'

The [c] modifier ensures case-insensitive matching across log streams.

Customizing Output Formatting and Detail Levels

You can adjust the verbosity and data structure of streamed logs using the --style flag:

• --style default: Standard human-readable log formatting showing timestamp, process, and message text.
• --style compact: Abbreviated single-line format that removes redundant headers for fast scanning.
• --style json: Structured machine-readable JSON output suitable for piping into external log ingestion pipelines or parsing via jq.
• --style syslog: Legacy BSD syslog format compatible with traditional log parsing scripts.

log stream --predicate 'subsystem == "com.apple.securityd"' --style compact

Collecting Historical Logs with log show

While log stream monitors events live as they occur, you can query historical log archives using companion command log show:

log show --predicate 'subsystem == "com.apple.wifi"' --last 1h

This command queries the unified log database, extracting Wi-Fi events recorded during the preceding 60 minutes.