log(1) General Commands Manual log(1)
NAME
log – Access system wide log messages created by os_log, os_trace and other
logging systems.
SYNOPSIS
log [command [options]]
log help [command]
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]
DESCRIPTION
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.
--[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 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.
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:
https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Predicates/Articles/pSyntax.html
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 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:
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 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.
FILES
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.
SEE ALSO
os_log(3), os_trace(3)
Darwin May 10, 2016 Darwin