log(1) man page

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 config [--reset | --status] [--mode mode(s)]
[--subsystem name [--category name]] [--process pid]

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

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.

--predicate predicate
Collect system logs using a given predicate
following NSPredicate format. This option
can significantly increase the time and
memory usage required to collect an
archive. Example: "--predicate
"process=='kernel.development'"

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.

--last time[m|h|d] | boot
Shows statistics for 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.

--start date/time Shows statistics for events 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 statistics for events up to
the provided date.

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.

repack Repack all logs in a logarchive matching a predicate into a
new logarchive with only the matching logs. Includes info
and debug messages by default.

--archive archive Archive to be repacked.

--no-timeout Remove the default timeout (5 Mins)
for repacking. This is generally not
needed.

--fatal-warnings Treat all warnings as errors and
stop repacking.

--predicate predicate Include events matching a predicate.
See section "PREDICATE-BASED
FILTERING" below.

--verbose Include extra output for debugging.

--mutate Mutate logarchive 'in-place' without
copying it. This is a destructive
operation and cannot be undone.

--skip-uuid-purge Skip purging unused UUIDs from the
resulting archive.

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.