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 [m|h|d]] [--device | --device-name name | --device-udid UDID] [--predicate predicate]


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:

General help or help specific to command argument
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.
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.
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"
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"
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"
Collect system logs from paired device (first device found).
name
Collect system logs from paired device with the given name.
UDID
Collect system logs from paired device with the given UDID.
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'"
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.
|
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.
name
Set or get mode for a specified subsystem.
name
Set or get mode for a specified category. If category is supplied, subsystem is required.
pid
Set mode for a specified pid.
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.

Delete selected log data from the system. If no arguments are specified, the main log datastore and inflight log data will be deleted.
Deletes main log datastore, and inflight log data as well as time-to-live data (TTL), and the fault and error content.
Deletes time-to-live log content.
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
Display events stored in the given archive. The archive must be a valid log archive bundle with the suffix .logarchive.
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.
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.
pid | process
The process on which to operate. This option can be passed more than once to operate on multiple processes.
Include symbol names and source line numbers for messages, if available.
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).
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.
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"
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"
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"
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.
Disable or enable info level messages in the output. (By default info messages are not displayed.)
Disable or enable debug level messages in the output. (By default debug messages are not displayed.)
Disable or enable display of signposts in the output. (By default signposts are not displayed.)
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
Display statistics for events stored in the given archive. The archive must be a valid log archive bundle with the suffix .logarchive.
events | bytes
Sort tabulated data output by number of events, or number of bytes.
count | all
Limit tabulated data to the given number of lines, or all displays all entries in tables.
human | json
Control the format style of the requested output mode.
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.
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"
date/time
Shows statistics for events up to the provided date.

In addition, one of the following output modes can be supplied:

Displays statistics for the entire archive.
Displays statistics per log book, the subsections of a log archive.
Displays statistics per file in the archive.
sender
Displays statistics for a given sender image name.
process
Displays statistics for a given originating process.
predicate
Displays statistics for all events matching the given predicate.
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.
default | info | debug
Shows messages at specified level and below. The level is a hierarchy. Specifying debug implies debug, info and default.
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.
pid | process
The process on which to operate. This option can be passed more than once to operate on multiple processes.
default | compact | json | syslog
Output the content as a different style.
auto | always | none
Highlight certain types of log messages. In auto, highlighting will be disabled if the output is detected to be non-TTY.
Include symbol names and source line numbers for messages, if available.
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.
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 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 to be repacked.
Remove the default timeout (5 Mins) for repacking. This is generally not needed.
Treat all warnings as errors and stop repacking.
predicate
Include events matching a predicate. See section "PREDICATE-BASED FILTERING" below.
Include extra output for debugging.
Mutate logarchive 'in-place' without copying it. This is a destructive operation and cannot be undone.
Skip purging unused UUIDs from the resulting archive.

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:

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:

black
red
green
brown
blue
magenta
cyan
light grey
bold black, usually shows up as dark grey
bold red
bold green
bold brown, usually shows up as yellow
bold blue
bold magenta
bold cyan
bold light grey; looks like bright white
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.

Control the default output style of log show: default, compact, json or syslog.
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.
Change the type of streaming enabled.
live
Live streaming from the process using IPC.
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.

os_log(3), os_trace(3)

May 10, 2016 Darwin