manpagez: man(ual) pages & more
man log(1)
Home | html | info | man

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

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

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

                      --start date/time
                                       Shows content starting from the pro-
                                       vided date.  Date and time are speci-
                                       fied 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 spec-
                                       ified with or without a time. e.g.,
                                       "2016-04-12" or "2016-04-12 13:30:00".

                      --info           Shows info level messages in the out-
                                       put.

                      --debug          Shows debug level messages in the out-
                                       put.

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

                      --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 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   Matches the type of event: logEvent, traceEvent, activityCre-
                 ateEvent, 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 orig-
                 inated the event.

     senderImagePath
                 Matches the pattern within the name of the sender that origi-
                 nated the event.  This could be a specific library, frame-
                 work, 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 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.3 - Generated Sat Feb 4 12:24:40 CST 2017
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.