log(1) BSD 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]]
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]
[--source] [--style json | syslog | compact]
[--color auto | always | none] [--start date/time] [--end date/time]
[--info] [--debug] [--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] [--process pid | process]
[--predicate filter] [--source] [--style json | syslog | compact]
[--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 privi-
leges.
Available commands and their options:
help [command] 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"
config Configure, reset or read settings for the logging sys-
tem. config commands can act system-wide or on a sub-
system. 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 configura-
tion 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 subsys-
tem.
--category name Set or get mode for a specified cate-
gory. If category is supplied, subsys-
tem 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 argu-
ments 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 exists with EX_DATAERR (65) and an error message.
The output contains only default level messages unless
--info and/or --debug are specified.
--archive archive
Display events stored in the given ar-
chive. The archive must be a valid log
archive bundle with the suffix .loga-
rchive.
--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.
--predicate filter
Filters messages based on the provided
predicate, based on NSPredicate. A
compound predicate or multiple predi-
cates can be provided. See section
"PREDICATE-BASED FILTERING" below.
--source Include symbol names and source line
numbers for messages, if available.
--style json | syslog | compact
Output the content as a different
style.
--color auto | always | none
Highlight certain types of log mes-
sages. In auto, highlighting will be
disabled if the output is detected to
be non-TTY.
--start date/time
Shows content starting from the pro-
vided 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 dis-
played in the timezone at the time the
entry was written to source archive or
file.
--info Shows info level messages in the out-
put.
--debug Shows debug level messages in the out-
put.
stats Shows a breakdown of the events contained within a log
datastore or archive. The following options can be sup-
plied to all modes of log stats:
--archive archive Display statistics for events
stored in the given archive. The
archive must be a valid log ar-
chive 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 predi-
cate.
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. Spec-
ifying debug implies debug, info and
default.
--predicate filter
Filters messages using the provided
predicate based on NSPredicate. A com-
pound predicate or multiple predicates
can be provided. See section "PREDI-
CATE-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 json | syslog | compact
Output the content as a different
style.
--color auto | always | none
Highlight certain types of log mes-
sages. 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 speci-
fied. 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 NSPred-
icate rules. Supported keys include:
eventType The type of event: activityCreateEvent, activityTran-
sitionEvent, 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 exten-
sion, 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 cat-
egory 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
There are various environment variables that can be used to control log-
ging, activity flow, and other things.
OS_ACTIVITY_MODE <m> 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 mes-
sages. Does not override log-
ging Preferences that have
info level or debug level dis-
abled.
OS_ACTIVITY_STREAM <m> 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.
SEE ALSO
os_log(3), os_trace(3)
Darwin May 10, 2016 Darwin
Mac OS X 10.12.6 - Generated Sun Oct 29 07:45:17 CDT 2017