manpagez: man 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]]
         [--last num [m|h|d]]

     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]
         [--source] [--style json | syslog | compact]
         [--color auto | always | none] [--start date/time] [--end date/time]
         [--info] [--debug] [--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] [--process pid | process]
         [--predicate filter] [--source] [--style json | syslog | compact]
         [--color auto | always | none] [--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.  Some commands require root privi-
     leges.

     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.  The following
                                       date/time formats are accepted: "YYYY-
                                       MM-DD", "YYYY-MM-DD HH:MM:SS", "YYYY-
                                       MM-DD HH:MM:SSZZZZZ"

                      --last 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"

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

                                       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.

     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 exists with EX_DATAERR (65) and an error message.
                      The output contains only default level messages unless
                      --info and/or --debug are specified.

                      --archive archive
                                       Display events stored in the given ar-
                                       chive. The archive must be a valid log
                                       archive bundle with the suffix .loga-
                                       rchive.

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

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

                      --color auto | always | none
                                       Highlight certain types of log mes-
                                       sages. In auto, highlighting will be
                                       disabled if the output is detected to
                                       be non-TTY.

                      --start date/time
                                       Shows content starting from the pro-
                                       vided date.  The following date/time
                                       formats are accepted: "YYYY-MM-DD",
                                       "YYYY-MM-DD HH:MM:SS", "YYYY-MM-DD
                                       HH:MM:SSZZZZZ"

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

                      --last 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"

                      --timezone local | timezone
                                       Displays content in the local timezone,
                                       or a specified timezone (see tzset(3)).
                                       If not specified, the output is dis-
                                       played in the timezone at the time the
                                       entry was written to source archive or
                                       file.

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

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

     stats            Shows a breakdown of the events contained within a log
                      datastore or archive. The following options can be sup-
                      plied to all modes of log stats:

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

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

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

                      --style human | json    Control the format style of the
                                              requested output mode.

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

                      --overview              Displays statistics for the
                                              entire archive.

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

                      --per-file              Displays statistics per file in
                                              the archive.

                      --sender sender         Displays statistics for a given
                                              sender image name.

                      --process process       Displays statistics for a given
                                              originating process.

                      --predicate predicate   Displays statistics for all
                                              events matching the given predi-
                                              cate.

     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.

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

                      --color auto | always | none
                                       Highlight certain types of log mes-
                                       sages. In auto, highlighting will be
                                       disabled if the output is detected to
                                       be non-TTY.

                      --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          The type of event: activityCreateEvent, activityTran-
                        sitionEvent, 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 exten-
                        sion, 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 cat-
                        egory 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.6 - Generated Sun Oct 29 07:45:17 CDT 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.