| LOG(1) | General Commands Manual | LOG(1) |
log — access
system wide log messages created by os_log, os_trace, and other logging
systems
log |
[command [options]] |
log |
help [command] |
log |
collect [--output
path] [--start
date/time] [--size
num [k|m]] [--last
num[s|m|h|d]] [--device |
--device-name name |
--device-udid UDID]
[--predicate predicate]
[--directory directory] |
log |
config [--reset |
--status] [--mode
modes] [--subsystem
name [--category
name]] [--process
pid] |
log |
diagnose [--archive
archive] [--all]
[--erase] [--json]
[--logd-starts] [--process
process] [--quarantine]
[--time] |
log |
emit [--type
type] [--subsystem
name] [--category
name] [--signpost-id
id] [--public]
message |
log |
erase [--all]
[--ttl] [--uuidtext] |
log |
repack [--archive
archive] [--fatal-warnings]
[--mutate] [--predicate
predicate]
[--skip-uuid-purge] |
log |
show [--archive
archive | --file
file] [--predicate
filter]
[--highlight-predicate
filter] [--process
pid | process]
[--source] [--style
default | compact |
json | ndjson |
syslog] [--color
auto | always |
none] [--directory
directory] [--start
date/time] [--end
date/time] [--metric]
[--[no-]info]
[--[no-]debug]
[--[no-]pager]
[--[no-]signpost]
[--[no-]loss] [--last
num[s|m|h|d] |
boot] [--last24]
[--today] [--yesterday]
[--timezone local |
timezone] |
log |
stats [--archive
archive | --file
file] [--sort
events | bytes]
[--count count |
all] [--start
date/time] [--end
date/time] [--last
num[s|m|h|d] |
boot] [--style
human | json]
[--[no-]pager] [--overview
| --per-book | --per-file
| --sender sender |
--process process |
--predicate predicate] |
log |
stream [--color
auto | always |
none] [--level
default | info |
debug] [--predicate
filter] [--process
pid | process]
[--user uid |
user] [--source]
[--style default |
compact | json |
ndjson | syslog]
[--timeout time [m|h|d]]
[--type activity |
log | trace]
[--mach-continuous-time]
[--unreliable]
[--ignore-dropped]
[--payload]
[--[no-]backtrace]
[--[no-]debug]
[--[no-]info] [--metric]
[--[no-]signpost] |
log is used to access system wide log
messages created by os_log(3),
os_trace(3), and other logging systems. Some commands
require root privileges.
Available commands and their options:
helpcollectlog or Console. If an output path is
not specified, system_logs.logarchive will be
created in the current directory.
-o,
--output path-S,
--start date/time-l,
--last num[s|m|h|d]--last
2m’ or ‘--last
3h’.-z,
--size num [k|m]--size 100k’ or
‘--size 20m’.-d,
--device-n,
--device-name name-u,
--device-udid UDID-P,
--predicate predicate--predicate
"process==kernel.development'"’.-D,
--directory directoryconfigconfig 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.
-r,
--reset |
-s,
--statuslog 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, and ‘log config --mode "level:
default"’ will set the system log level to
default.-S,
--subsystem name-c,
--category name-p,
--process pid-m,
--mode modesThe modes available to each scope are as follows:
--subsystem--category--processdiagnose-A,
--archive archive-v,
--verbose-j,
--json-p,
--process process-a,
--all-e,
--erase-s,
--logd-starts-t,
--time-q,
--quarantineemit-t,
--type typedebug, info,
default, error,
fault, signpost-event,
signpost-begin, and
signpost-end. If not specified,
default is used.-S,
--subsystem namecom.example.myapp). If not
specified, the message uses
OS_LOG_DEFAULT.-c,
--category name--subsystem. If a subsystem
is specified but no category is provided, an empty category is
used.-i,
--signpost-id idsignpost-begin and
signpost-end types to create matching pairs
for performance measurement intervals. The id should be a positive
integer that uniquely identifies the interval. If not specified for
signpost operations, OS_SIGNPOST_ID_EXCLUSIVE
is used.-p,
--publicerase-A,
--all-t,
--ttl--uuidtextrepack-A,
--archive archive-t,
--no-timeout-w,
--fatal-warnings-p,
--predicate predicate-v,
--verbose-m,
--mutate-u,
--skip-uuid-purgeshowEX_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.
-A,
--archive archive-f,
--file file--[no-]pager-p,
--predicate filter-H,
--highlight-predicate
filter--predicate, but highlighting matching
results.-P,
--process pid |
process--source-s,
--style style-c,
--color auto |
always | nonelog will disable colorized output when not
directed to a terminal, unless overidden using
always.-D,
--directory directory-S,
--start date/time-E,
--end date/time-l,
--last
num[s|m|h|d] |
boot--last 2m’ or
‘--last 3h’. If set to zero,
this will reset a previous -l setting or do
nothing.-L,
--last24--last
24h.-T,
--today-Y,
--yesterday-Z,
--timezone local |
timezone--metric--[no-]info--[no-]debug--[no-]signpost--[no-]lossstatslog stats:
-A,
--archive archive-F,
--file file--archive, --per-book,
and --per-file.-o,
--sort events |
bytes-c,
--count count |
all-s,
--style human |
json-l,
--last
num[s|m|h|d] |
boot-l setting or
do nothing.-S,
--start date/time-E,
--end date/time--[no-]pagerIn addition, one of the following output modes can be supplied:
-O,
--overview-B,
--per-book-f,
--per-file-b,
--sender sender-p,
--process process-P,
--predicate predicatestream-c,
--color auto |
always | none-l,
--level default |
info | debug-P,
--predicate filter-p,
--process pid |
process-u,
--user uid |
user-s,
--style default |
compact | json |
ndjson | syslog--source-T,
--timeout time
[m|h|d]--timeout 5m’ or
‘--timeout 1h’. If minutes,
hours, days not specified, seconds will be used.-Y,
--type activity |
log | trace--type for each requested type of event.--mach-continuous-time--unreliable--ignore-dropped-o,
--payload--[no]-backtrace--[no]-debug--[no]-info--metric--[no]-signpostAll commands accept the following options:
-h,
--helpEX_USAGE
(64).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
Format String Syntax.
The filter argument defines one or more
pattern clauses following NSPredicate rules. Run log help
predicates for the full list of supported keys. Supported keys
include:
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
Use shorthand filters via the --predicate
option as an alternative to NSPredicate-based syntax. Run
log help shorthand for the full list of supported
keys. Supported keys include:
message,
m, or
omitprocess,
pprocessImagePath,
pippidsubsystem,
scategory,
ctypedefault,
info, debug,
error, fault,
signpost, statedump, or
activity.Supported operators include
Values can be grouped together using a vertical bar as a logical OR operator. When a vertical bar is used on the right hand side of an equality operator, the comparison becomes case-sensitive.
Filter for specific subsystem:
log show --predicate 's=com.example.my_subsystem'
Filter for categories containing "network" with messages containing certain text:
log show --predicate 'c:network and "subtext to find"'
Filter for specific subsystem and categories:
log show --predicate 's=com.example.my_subsystem and category=category1|category2'
Filter for errors from processes:
log show --predicate 'p=myprocess|yourprocess and type=error'
The following environment variables affect the execution of
log:
LOG_COLORSlog 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:
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:
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_STYLElog show:
default, compact, json or syslog.OS_ACTIVITY_MODEOS_ACTIVITY_STREAMOS_ACTIVITY_PROPAGATE_MODEYou 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:
'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.
View recent log messages:
log show --last 1h
Stream live log messages:
log stream
Emit a test log message:
log emit "Test message"
Emit an error message with subsystem information:
log emit --type error --subsystem com.example.app "An error occurred"
Emit a signpost event for performance analysis:
log emit --type signpost-event "Performance marker reached"
Begin a signpost interval for performance measurement:
log emit --type signpost-begin --signpost-id 42 "Operation started"
End a signpost interval for performance measurement:
log emit --type signpost-end --signpost-id 42 "Operation completed"
Begin and end a signpost interval with subsystem information:
log emit --subsystem com.example.app --category performance \
--type signpost-begin --signpost-id 123 "Database query started"
log emit --subsystem com.example.app --category performance \
--type signpost-end --signpost-id 123 "Database query completed"
Show help for a specific command:
log help show log help emit
| May 10, 2016 | Darwin |