log

Access system wide log messages created by os_log, os_trace and other logging systems.

Syntax
log [command [options]]

log help [command]

log config [--reset | --status] [--mode mode(s)]
[--subsystem name [--category name]] [--process pid]

log erase [--all] [--ttl]

Key
help General help or help specific to command argument

collect Collect the system logs into a .logarchive that can be viewed later with tools such as log or Console.
If an output path is not specified, system_logs.logarchive will be created in the current directory.

--output path Save the archive to the specified path or file. If the path is a directory, a file
named system_logs.logarchive will be created in thespecified directory.
If the path contains the extension .logarchive, a new logarchive will be created with
that name at the specified path.

--start date/time
Limits the content capture to the date and time forward to now.
The following date/time formats are accepted: "YYYY-MM-DD", "YYYY-MM-DD
HH:MM:SS", "YYYY-MM-DD HH:MM:SSZZZZZ"

--last num [m|h|d]
Limits the captured events to the period starting at the given interval ago
from the current time. Time is assumed in seconds unless
specified. Example: "--last 2m" or "--last 3h"

--size num [k|m]
The amount of data to be captured in kilobytes or megabytes.
This is an approximation, as the actual size may be more than requested.
Example: "--size 100k" or "--size 20m"

--device Collect system logs from paired device (first device found).

--device-name name
Collect system logs from paired device with the given name.

--device-udid UDID
Collect system logs from paired device with the given UDID.

config Configure, reset or read settings for the logging system.
config commands can act system-wide or on a subsystem.
If not specified, system-wide is assumed. If subsystem is specified, category is optional.
Requires root access.

--reset | --status
Option to show or reset the current settings for the system or a specific subsystem.
If reset or status is not specified, a change to the
configuration is assumed. For example, "log config --reset --subsystem com.mycompany.mysubsystem"
will reset the subsystem to its default settings.
"log config --status" will show the current system-wide logging settings.
"log config --mode "level: default"" will set the system log level to default.

--subsystem name
Set or get mode for a specified subsystem.

--category name Set or get mode for a specified category. If category is supplied, subsystem is required.

--process pid Set mode for a specified pid.

--mode mode(s) Will enable given mode. Modes include:

level: {off | default | info | debug} The level is a hierarchy, e.g. debug implies debug,
info, and default.
persist: {off | default | info | debug}
The persist mode is a hierarchy, e.g. debug implies debug, info, and default.

erase Delete selected log data from the system.
If no arguments are specified, the main log datastore and inflight log data will be deleted.

--all Deletes main log datastore, and inflight log data as well as time-to-live data (TTL),
and the fault and error content.

--ttl Deletes time-to-live log content.

show Shows contents of the system log datastore, archive or a specific tracev3 file.
If a file or archive is not specified, the system datastore will be shown.
it is from a future system version that log cannot understand, it exits with EX_DATAERR (65) and an error message.
The output contains only default level
If messages unless --info and/or --debug are specified. The output does not contain signposts unless
--signpost is specified.

--archive archive
Display events stored in the given archive.
The archive must be a valid log archive bundle with the suffix .logarchive.

--file file Display events stored in the given .tracev3 file. In order to be decoded,
the file must be contained within a valid .logarchive bundle, or part of the
system logs directory.

--[no-]pager Enable or disable pagination of output via less.

--predicate filter
Filters messages based on the provided predicate, based on NSPredicate.
A compound predicate or multiple predicates can be provided. See section
"PREDICATE-BASED FILTERING" below.

--process pid | process
The process on which to operate. This option can be passed more than once to operate on
multiple processes.

--source Include symbol names and source line numbers for messages, if available.

--style style Control the output formatting of events:

default Human readable output. ISO-8601 date (microsecond precision and
timezone offset), thread ID, log type, activity ID, process ID,
TTL, process, subsystem, category and message content.

compact Compact human readable output. ISO-8601 date (millisecond precision),
abbreviated log type, process, processID, thread ID,
subsystem, category and message content.
This output uses less horizontal space to indicate event metadata than
the default style.

json JSON output. Event data is synthesized as an array of JSON dictionaries.

ndjson Line-delimited JSON output. Event data is synthesized as JSON dictionaries,
each emitted on a single line. A trailing record,
identified by the inclusion of a "finished" field, is emitted to indicate
the end of events.

syslog syslog-style output intended to be more compatible with the output format
used by syslog(1).

--color auto | always | none
Control the display of colourised output.
By default, log will disable colourised output when not directed to a terminal, unless
overidden using always.

--start date/time
Shows content starting from the provided date.
The following date/time formats are accepted: "YYYY-MM-DD", "YYYY-MM-DD HH:MM:SS",
"YYYY-MM-DD HH:MM:SSZZZZZ"

--end date/time Shows content up to the provided date.
The following date/time formats are accepted: "YYYY-MM-DD", "YYYY-MM-DD HH:MM:SS" ,
"YYYY-MM-DD HH:MM:SSZZZZZ"

--last time[m|h|d] | boot
Shows events that occurred within the given time relative to the end of the
log archive, or beginning at the last boot contained within the log archive.
Time may be specified as minutes, hours or days. Time is assumed in seconds
unless specified. Example: "--last 2m" or "--last 3h"

--timezone local | timezone
Displays content in the local timezone, or a specified timezone (see tzset(3)).
If not specified, the output is displayed in the timezone at
the time the entry was written to source archive or file.

--[no-]info Disable or enable info level messages in the output.
(By default info messages are not displayed.)

--[no-]debug Disable or enable debug level messages in the output.
(By default debug messages are not displayed.)

--[no-]signpost Disable or enable display of signposts in the output.
(By default signposts are not displayed.)

stats Shows a breakdown of the events contained within a log datastore or archive.
The following options can be supplied to all modes of log stats:

--archive archive Display statistics for events stored in the given archive.
The archive must be a valid log archive bundle with the suffix .logarchive.

--sort events | bytes Sort tabulated data output by number of events, or number of bytes.

--count count | all Limit tabulated data to the given number of lines, or
all displays all entries in tables.

--style human | json Control the format style of the requested output mode.

In addition, one of the following output modes can be supplied:

--overview Displays statistics for the entire archive.

--per-book Displays statistics per log book, the subsections of a log archive.

--per-file Displays statistics per file in the archive.

--sender sender Displays statistics for a given sender image name.

--process process Displays statistics for a given originating process.

--predicate predicate Displays statistics for all events matching the given predicate.

stream Stream activities, log data or trace messages for the system or from a given process.
By default, the command assumes system-wide streaming. Specifying a
process id with the --process option will narrow the results.

--level default | info | debug
Shows messages at specified level and below. The level is a hierarchy.
Specifying debug implies debug, info and default.

--predicate filter
Filters messages using the provided predicate based on NSPredicate.
A compound predicate or multiple predicates can be provided. See section
"PREDICATE-BASED FILTERING" below.

--process pid | process
The process on which to operate. This option can be passed more than once
to operate on multiple processes.

--style default | compact | json | syslog
Output the content as a different style.

--color auto | always | none
Highlight certain types of log messages. In auto, highlighting will be disabled
if the output is detected to be non-TTY.

--source Include symbol names and source line numbers for messages, if available.

--timeout time [m|h|d]
Timeout the stream operation after a specified time,
e.g. "--timeout 5m", "--timeout 1h"
If minutes, hours, days not specified, seconds will be used.

--type activity | log | trace
Dictates the type of events to stream from a process.
By default all types are streamed unless otherwise specified.
Pass an appropriate --type for each requested type of event.

PREDICATE-BASED FILTERING

Using predicate-based filters via the --predicate option allows users to focus on messages based on
the provided filter criteria. For detailed information on the use of predicate based filtering,
please refer to the Predicate Programming Guide

The filter argument defines one or more pattern clauses following NSPredicate rules.
See log help predicates for the full list of supported keys.
Supported keys include:

eventType The type of event: activityCreateEvent, activityTransitionEvent, logEvent, signpostEvent,
stateEvent, timesyncEvent, traceEvent and userActionEvent.

eventMessage The pattern within the message text, or activity name of a log/trace entry.

messageType For logEvent and traceEvent, the type of the message itself: default, info, debug, error
or fault.

process The name of the process the originated the event.

processImagePath The full path of the process that originated the event.

sender The name of the library, framework, kernel extension, or mach-o image, that originated
the event.

senderImagePath The full path of the library, framework, kernel extension, or mach-o image, that
originated the event.

subsystem The subsystem used to log an event. Only works with log messages generated with
os_log(3) APIs.

category The category used to log an event. Only works with log messages generated with os_log(3)
APIs. When category is used, the subsystem filter should also be provided.

PREDICATE-BASED FILTERING EXAMPLES
Filter for specific subsystem:
log show --predicate 'subsystem == "com.example.my_subsystem"'

Filter for specific subsystem and category:
log show --predicate '(subsystem == "com.example.my_subsystem") && (category == "desired_category")'

Filter for specific subsystem and categories:
log show --predicate '(subsystem == "com.example.my_subsystem") && (category IN { "category1", "category2" })'

Filter for a specific subsystem and sender(s):
log show --predicate '(subsystem == "com.example.my_subsystem") && ((senderImagePath ENDSWITH "mybinary") || (senderImagePath ENDSWITH "myframework"))'

PREDICATE-BASED FILTERING EXAMPLES WITH LOG LINE

log show system_logs.logarchive --predicate 'subsystem == "com.example.subsystem" and category contains "CHECK"'

Timestamp Thread Type Activity PID
2016-06-13 11:46:37.248693-0700 0x7c393 Default 0x0 10371 timestamp: [com.example.subsystem.CHECKTIME] Time is 06/13/2016 11:46:37

log show --predicate 'processImagePath endswith "hidd" and senderImagePath contains[cd] "IOKit"' --info

Timestamp Thread Type Activity PID
2016-06-10 13:54:34.593220-0700 0x250 Info 0x0 113 hidd: (IOKit) [com.apple.iohid.default] Loaded 6 HID plugins

ENVIRONMENT
The following environment variables affect the execution of log:

LOG_COLORS Controls the colour of text output from log show.
This string is a concatenation of pairs of the format fb, where f is the foreground colour
and b is the background colour.

The colour designators are as follows:

a black
b red
c green
d brown
e blue
f magenta
g cyan
h light grey
A bold black, usually shows up as dark grey
B bold red
C bold green
D bold brown, usually shows up as yellow
E bold blue
F bold magenta
G bold cyan
H bold light grey; looks like bright white
x default foreground or background

Note that the above are standard ANSI colours.
The actual display may differ depending on the colour capabilities of the terminal in use.

The order of the attributes are as follows:

1. timestamp
2. thread identifier
3. event type
4. activity identifier
5. process identifier
6. time-to-live
7. process name
8. sender image name
9. subsystem
10. category
11. event message
12. highlight colour

The default is "xxxxxxxxxxxxFxdxcxExxxxA", i.e. bold magenta process name, yellow sender,
green subsystem, bold blue category and dark grey background for highlighted lines.

LOG_STYLE Control the default output style of log show: default, compact, json or syslog.

OS_ACTIVITY_MODE Change the mode of launched processes to:
info Enables info level messages.
Does not override logging Preferences that have info level disabled.
debug Enables debug level messages which includes info level messages.
Does not override logging Preferences that have info level or debug
level disabled.

OS_ACTIVITY_STREAM Change the type of streaming enabled.
live Live streaming from the process using IPC.

OS_ACTIVITY_PROPAGATE_MODE If set, will propagate the mode settings via activities.

FILES
You can control the execution of log show and log stream with a configuration file located at ~/.logrc.

log is used to access system wide log messages created by os_log, os_trace and other logging systems. Some commands require root privileges.

Examples

Display recent Time Machine log files:

# clear the scrollback because the output is likely to be long
printf '\e[3J' 
# display the log
log show --predicate 'subsystem == "com.apple.TimeMachine"' --info --last 6h | grep -F 'eMac' | grep -Fv 'etat' | awk -F']' '{print substr($0,1,19), $NF}'

“I cannot remember the books I've read any more than the meals I have eaten; even so, they have made me” ~ Ralph Waldo Emerson

Related macOS commands

Local man page: log - Command line help page on your local machine.
printf - Format and print data.