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

log config [--reset | --status] [--mode mode(s)] [--subsystem name [--category name]] [--process pid]

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

log show [archive | file] [--predicate filter] [--source] [--style json | syslog] [--start date/time] [--end date/time] [--info] [--debug] [--last time [m|h|d]]

log stream [--level default | info | debug] [--parent pid | process] [--process pid | process] [--predicate filter] [--source] [--style json | syslog] [--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. The logging system stores content in /var/db/diagnostics and references content in /var/db/uuidtext. These system directories are required for operation of the logging system. Some commands require root privileges.

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. Date and time are specified as "YYYY-MM-DD HH:MM:SS". The date can be specified with or without a time. e.g., "2016-04-12" or "2016-04-12 13:30:00".

    --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 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. Off can only be used with process.

        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.

    --faulterror
        Deletes fault and error specific log content.

show [archive | file]
    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. The output contains only default level messages unless --info and/or --debug are specified.

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

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

    --style json | syslog
        Output the content as a different style.

    --start date/time
        Shows content starting from the provided date. Date and time are specified as "YYYY-MM-DD HH:MM:SS". The date can be specified with or without a time. e.g., "2016-04-12" or "2016-04-12 13:30:00".

    --end date/time
        Shows content up to the provided date. Date and time are specified as "YYYY-MM-DD HH:MM:SS". The date can be specified with or without a time. e.g., "2016-04-12" or "2016-04-12 13:30:00".

    --info
        Shows info level messages in the output.

    --debug
        Shows debug level messages in the output.

    --last time [m|h|d]
        Shows content that that has happened since time specified. Time may be specified as minutes, hours or days. If not specified, seconds is assumed. For example, "--last 30", "--last 3m", "--last 8h", "--last 2d"

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.

    --parent pid | process
        Any child process of the provided process or pid will stream messages associated with the same activity id.

    --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
        Output the content as a different style.

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

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. Supported keys include:

eventType
    Matches the type of event: logEvent, traceEvent, activityCreateEvent, or activityTransitionEvent.

eventMessage
    Matches the pattern within the message text, or activity name of a log/trace entry.

messageType
    Matches the type of message for logEvent and traceEvent, which includes "default", "info", "debug", etc.

processImagePath
    Matches the pattern within the name of the process that originated the event.

senderImagePath
    Matches the pattern within the name of the sender that originated the event. This could be a specific library, framework, kext, or any valid mach-o binary that is executed.

subsystem
    Matches the pattern within the specified subsystem of the event. Only works with log messages generated with os_log(3) APIs.

category
    Matches the pattern within the specified cateogry of the 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
There are various environment variables that can be used to control logging, 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 messages. Does not override logging Preferences that have info level or debug level disabled.

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)