Introduction to macOS Unified Logs
Summary
With the introduction of Apple Unified Logging, most useful system logs are no longer stored in flat files like /var/log/system.log. They are now stored in binary files and the log command is used to extract what we’re looking for.
You could display all system logs for the last 5 minutes (this will have a lot of noise):
log show --last 5mTo watch system logs as they’re happening (similar to tailing a log), use:
log streamYou can also use grep to narrow down the logs that are being displayed in realtime (although using predicates will reduce realtime resource usage – see below):
log stream | egrep screensharingdPredicate Filtering
There are various “predicates” that we can use to filter out the noise in the logs. We’ll mostly use three predicates:
- process – shows logs only from a specific process, such as screensharingd for Screen Sharing
- subsystem – shows logs only from a specific subsystem, such as com.apple.SoftwareUpdate for update logs
- eventMessage – think of this as the “body” of each log line. For example, if we’re searching for successful Screen Sharing logins with the screensharingd process, we’d further filter for “Authentication: SUCCEEDED” in the eventMessage.
By filtering on predicates rather than a string search of the entirety of the logs, we significantly speed up the time it takes to search.
Note that just filtering a subsystem will usually still result in a lot of noise – further filter with eventMessage to eliminate junk.
Filtering with Multiple Predicates
Simply use && within the –predicate ‘ ‘ option to search with multiple filters.
Filtering Based on Time
To only search for a specific amount of time, we can specify time periods using the –last option:
–last 10m – Search last 10 minutes of logs
–last 24h – Search last 24 hours of logs
–last 7d – Search last 7 days of logs
To specify a window of dates to search, use the –start and –end options
Unified logging will generally retain the last ~30 days of logs.
Examples
Show Time Machine logs for last hour
log show --predicate 'subsystem == "com.apple.TimeMachine"' --info --last 1hNotice that we added the –info option – without this, some of the Time Machine logs that we’re looking for may not be displayed.
Show Screen Sharing (VNC) login attempts
Show successful VNC logins in the last 24 hours:
log show --predicate 'process == "screensharingd" && eventMessage CONTAINS "Authentication: SUCCEEDED"' --last 24hShow failed VNC logins in the last 24 hours:
log show --predicate 'process == "screensharingd" && eventMessage CONTAINS "Authentication: FAILED"' --last 24hShow macOS shutdown/reboot cause
This command can help identify the cause of an unexpected reboot:
log show --predicate 'eventMessage contains "Previous shutdown cause"' --last 72hCode 5 means “Correct Shut Down”.
Other cause codes can be identified here: https://georgegarside.com/blog/macos/shutdown-causes/
Additional Information
https://blog.kandji.io/mac-logging-and-the-log-command-a-guide-for-apple-admins (contains list of common subsystems)
https://www.crowdstrike.com/blog/how-to-leverage-apple-unified-log-for-incident-response/ (Incident Response)
https://www.dssw.co.uk/reference/log.html (general reference)