NAME

log — access system wide log messages created by os_log, os_trace, and other logging systems

SYNOPSIS

DESCRIPTION

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:

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.

-o, --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.

-S, --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"

-l, --last num[s|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. For example, ‘--last 2m’ or ‘--last 3h’.

-z, --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. For example, ‘--size 100k’ or ‘--size 20m’.

-d, --device

Collect system logs from paired device (first device found).

-n, --device-name name

Collect system logs from paired device with the given name.

-u, --device-udid UDID

Collect system logs from paired device with the given UDID.

-P, --predicate predicate

Collect system logs using a given predicate following NSPredicate format or shorthand. This option can significantly increase the time and memory usage required to collect an archive. For example, ‘--predicate "process==kernel.development'"’.

-D, --directory directory

Collect content from the provided log store directory, instead of the local log store. The directory must contain a system logging database similar to what can be found in /var/db/diagnostics, and its parent directory must also contain an uuidtext directory similar to what can be found in /var/db/uuidtext. This option is useful to collect logs from a system partition that is not booted, e.g. from a recovery environment or an external drive.

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.

-r, --reset | -s, --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, and ‘log config --mode "level: default"’ will set the system log level to default.

-S, --subsystem name

Set or get mode for a specified subsystem.

-c, --category name

Set or get mode for a specified category. If category is supplied, subsystem is required.

-p, --process pid

Set mode for a specified pid.

-m, --mode modes

Will enable given modes. Multiple modes are comma-separated. Modes include:

level:<off|default|info|debug>

Default logging level. The level is a hierarchy, so debug implies debug, info, and default.

persist:<off|default|info|debug>

Persistence level. The persist mode is a hierarchy, so debug implies debug, info, and default.

stream:<live|default>

Streaming mode.

signpost-persisted:<off|on|default>

Signpost persistence level.

signpost-enabled:<off|on|default>

Signpost enablement.

signpost-backtrace-enabled:<off|on|default>

Signpost backtrace enablement.

oversize-enabled:<off|on|default>

Oversized log message enablement.

The modes available to each scope are as follows:

(system-wide)

level, persist, stream

--subsystem

level, persist, signpost-persisted, signpost-enabled, signpost-backtrace-enabled, oversize-enabled

--category

level, persist, signpost-persisted, signpost-enabled, signpost-backtrace-enabled, oversize-enabled

--process

level, persist, stream

diagnose

Print various diagnostic information for a given archive. Running without options is the same as using .Fl -all.

-A, --archive archive

Archive to be diagnosed.

-v, --verbose

Output additional debugging information.

-j, --json

Output in JSON.

-p, --process process

Only print relevant quarantine information for the given process.

-a, --all

Print all available diagnostics.

-e, --erase

Print timestamps emitted when .Nm purged the archive.

-s, --logd-starts

Print timestamps emitted when .Nm starts.

-t, --time

Print the beginning capture time for each given log book.

-q, --quarantine

Print detailed quarantine information per process.

emit

Emit a log message to the system logging facility. This command is primarily used for testing and debugging purposes, allowing generation of log entries with specific types, subsystems, and categories.

-t, --type type

Specify the type of log message to emit. Valid types are: debug, info, default, error, fault, signpost-event, signpost-begin, and signpost-end. If not specified, default is used.

-S, --subsystem name

Specify the subsystem identifier for the log message. The subsystem is typically a reverse DNS name identifying the component generating the log message (e.g., com.example.myapp). If not specified, the message uses OS_LOG_DEFAULT.

-c, --category name

Specify the category within the subsystem. Categories provide additional organization within a subsystem. This option does nothing unless used with --subsystem. If a subsystem is specified but no category is provided, an empty category is used.

-i, --signpost-id id

Specify the signpost identifier for interval operations. This option is used with signpost-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, --public

Emit the message publicly.

message

The text message to emit to the logging system. This is a required argument and should be the last argument on the command line. By default, this is emitted as a private string.

erase

Delete selected log data from the system. If no arguments are specified, the main log datastore and inflight log data will be deleted.

-A, --all

Deletes main log datastore, and inflight log data as well as time-to-live data (TTL), and the fault and error content.

-t, --ttl

Deletes time-to-live log content.

--uuidtext

Prunes erased uuids from the database.

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.

-A, --archive archive

Archive to be repacked.

-t, --no-timeout

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

-w, --fatal-warnings

Treat all warnings as errors and stop repacking.

-p, --predicate predicate

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

-v, --verbose

Include extra output for debugging.

-m, --mutate

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

-u, --skip-uuid-purge

Skip purging unused UUIDs from the resulting archive.

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.

-A, --archive archive

Display events stored in the given archive. The archive must be a valid log archive bundle with the suffix .logarchive.

-f, --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.

-p, --predicate filter

Filters messages based on the provided predicate, based on NSPredicate or shorthand. A compound predicate or multiple predicates can be provided. See section PREDICATE-BASED FILTERING below.

-H, --highlight-predicate filter

Like --predicate, but highlighting matching results.

-P, --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.

-s, --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).

-c, --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.

-D, --directory directory

Reads content from the provided log store directory, instead of the local log store. The directory must contain a system logging database similar to what can be found in /var/db/diagnostics, and its parent directory must also contain an uuidtext directory similar to what can be found in /var/db/uuidtext. This option is useful to display logs from a system partition that is not booted, e.g. from a recovery environment or an external drive.

-S, --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"

-E, --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"

-l, --last num[s|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. For example, ‘--last 2m’ or ‘--last 3h’. If set to zero, this will reset a previous -l setting or do nothing.

-L, --last24

Shorthand for --last 24h.

-T, --today

Show events since the start of the day.

-Y, --yesterday

Show events for the full day prior.

-Z, --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.

--metric

Show metrics messages in the output.

--[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.)

--[no-]loss

Disable or enable display of loss event messages in the output. (By default loss event messages are not displayed.)

stats

Shows a breakdown of the events contained within a log datastore, archive, tracev3, tailspin or apple trace file. The following options can be supplied to all modes of log stats:

-A, --archive archive

Display statistics for events stored in the given archive. The archive must be a valid log archive bundle with the suffix .logarchive.

-F, --file file

Display statistics for events stored in the given file. The file may be a .tracev3, .ktrace, .atrc, or .tailspin file. A .tracev3 file must be contained within a valid .logarchive bundle, or part of the system logs directory. This option is mutually exclusive with --archive, --per-book, and --per-file.

-o, --sort events | bytes

Sort tabulated data output by number of events, or number of bytes.

-c, --count count | all

Limit tabulated data to the given number of lines, or all displays all entries in tables.

-s, --style human | json

Control the format style of the requested output mode.

-l, --last num[s|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. If set to zero, this will reset a previous -l setting or do nothing.

-S, --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"

-E, --end date/time

Shows statistics for events up to the provided date.

--[no-]pager

Enable or disable pagination of output via less.

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

-O, --overview

Displays statistics for the entire archive.

-B, --per-book

Displays statistics per log book, the subsections of a log archive.

-f, --per-file

Displays statistics per file in the archive.

-b, --sender sender

Displays statistics for a given sender image name.

-p, --process process

Displays statistics for a given originating process.

-P, --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.

-c, --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.

-l, --level default | info | debug

Shows messages at specified level and below. The level is a hierarchy. Specifying debug implies debug, info and default.

-P, --predicate filter

Filters messages using the provided predicate based on NSPredicate or shorthand. A compound predicate or multiple predicates can be provided. See section PREDICATE-BASED FILTERING below.

-p, --process pid | process

The process on which to operate. This option can be passed more than once to operate on multiple processes.

-u, --user uid | user

The user on which to operate. This option can be passed more than once to operate on multiple users.

-s, --style default | compact | json | ndjson | syslog

Output the content as a different style.

--source

Include symbol names and source line numbers for messages, if available.

-T, --timeout time [m|h|d]

Timeout the stream operation after a specified time. For example, ‘--timeout 5m’ or ‘--timeout 1h’. If minutes, hours, days not specified, seconds will be used.

-Y, --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.

--mach-continuous-time

Print mach continuous time timestamps rather than walltime.

--unreliable

Annotate output with whether the log was emitted unreliably.

--ignore-dropped

Don't output anything for dropped messages whilst streaming.

-o, --payload

Stream payload information. May not use syslog style.

--[no]-backtrace

Control whether backtraces are shown.

--[no]-debug

Include or don't include debug level events.

--[no]-info

Include or don't include info level events.

--metric

Include metrics events.

--[no]-signpost

Include or don't include signpost events.

All commands accept the following options:

-h, --help

Print a brief help message and exit with EX_USAGE (64).

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 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:

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 that 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

SHORTHAND-BASED FILTERING

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 omit

The pattern within the message text.

process, p

The name of the process that originated the event.

processImagePath, pip

The full path of the process that originated the event.

pid

The identifier of the process that originated the event.

subsystem, s

The subsystem used to log an event. Only works with log messages generated with os_log(3) APIs.

category, c

The category used to log an event. Only works with log messages generated with os_log(3) APIs.

type

A type of message: default, info, debug, error, fault, signpost, statedump, or activity.

Supported operators include

=, is

Equality.

!=, <>

Inequality.

:, contains

Contains a substring.

!:

Does not contain a substring.

:^

Starts with.

endswith

Ends with.

<=, >=

Numerical comparison.

~/regex/

Regular expression.

VALUES

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.

SHORTHAND-BASED FILTERING EXAMPLES

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'

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:

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.

EXAMPLES

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

SEE ALSO

os_log(3), os_trace(3)