log — Access
system wide log messages created by os_log, os_trace and other logging
systems.
log |
collect [--output
path] [--start
date/time] [--size
num [k|m]] [--last
num [m|h|d]] [--device |
--device-name name |
--device-udid UDID] |
log |
config [--reset |
--status] [--mode
mode(s)] [--subsystem
name [--category
name]] [--process
pid] |
log |
erase [--all]
[--ttl] |
log |
show [--archive
archive | --file
file] [--predicate
filter] [--process
pid | process]
[--source] [--style
default | compact |
json | ndjson |
syslog] [--color
auto | always |
none] [--start
date/time] [--end
date/time] [--[no-]info]
[--[no-]debug]
[--[no-]pager]
[--[no-]signpost] [--last
time [m|h|d]] [--timezone
local | timezone] |
log |
stats [--archive
archive] [--sort
events | bytes]
[--count count |
all] [--overview |
--per-book | --per-file |
--sender sender |
--process process |
--predicate predicate] |
log |
stream [--level
default | info |
debug] [--predicate
filter] [--process
pid | process]
[--source] [--style
default | compact |
json | syslog]
[--color auto |
always | none]
[--timeout time [m|h|d]]
[--type activity |
log | trace] |
log is used to access system wide log
messages created by os_log, os_trace and other logging systems. Some
commands require root privileges.
Available commands and their options:
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 the
specified 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. If 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 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.
- 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 colorized output. By default,
log will disable colorized 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.
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.
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"))'
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
The following environment variables affect the execution of
log:
LOG_COLORS- Controls the color of text output from log show. This string is a
concatenation of pairs of the format
fb, where
f is the foreground color and
b is the background color.
The color 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 colors. The actual
display may differ depending on the color capabilities of the terminal
in use.
The order of the attributes are as follows:
- timestamp
- thread identifier
- event type
- activity identifier
- process identifier
- time-to-live
- process name
- sender image name
- subsystem
- category
- event message
- highlight color
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.
You can control the execution of log show and log
stream with a configuration file located at ~/.logrc. Given a ~/.logrc
like this:
# .logrc - default log(1) arguments, handy predicate shortcuts
show:
--style compact
--last 1h
--info # turn back off with --no-info
--no-debug # turn back on with --debug
predicate:
app 'process == "application"'
errors 'process == "application" and messageType == error'
s
'process == "application" and ' # adjacent strings
'subsystem == "com.example.support"' # get merged
log show would automatically run as though the
arguments
--style compact --last 1h --info --no-debug
were passed in. Explicit options will override the arguments
provided by ~/.logrc. Furthermore, running with --predicate app would
be the same as using:
--predicate 'process == "application"'
The syntax of the ~/.logrc file made of comments, section headers,
options, words, and single-quoted strings. Comments start with the hash
character and run to the end of the line. Otherwise, contents are
whitespace-separated.
The structure of the ~/.logrc file is broken into sections.
Section headers are specified by a word and a colon. There are three kinds
of sections. The show: and stream: sections operate similarly.
Their contents are literal options and arguments that will be passed to the
respective command as if they were entered on the command line. The
predicate: section creates aliases for predicates. It is made up of
pairs of:
word
'predicate'
where word is a combination of letters
(presumably a simple, easy-to-type one) and predicate
is some filtering logic, as described in the
PREDICATE-BASED
FILTERING section above. The predicate is
delimited by single quotes, but adjacent quoted elements are
"glued" together; this helps in making long predicates easier to
read and write.