ostraceutil(1) BSD General Commands Manual ostraceutil(1)
NAME
ostraceutil -- is used to see application level os_trace messages.
SYNOPSIS
ostraceutil -list file
ostraceutil -setmode disable|default|debug|stream -process pid | -parent
pid
ostraceutil -stream [-activity binary:activity_name] [-buffered] [-debug]
[-filter query] [-payload] [-process pid | -parent pid]
[-source] [-style json|syslog] [-timeout seconds]
[-type activity|breadcrumb|message]
ostraceutil -watch [-errors] [-faults] [-process pid] [-quiet]
[-timeout seconds]
DESCRIPTION
ostraceutil is used to see application level os_trace messages. Must be
run with root privileges.
Available options:
-activity binary:activity_name
Stream will filter a specific activity from a
process, does not operate with the -parent option.
-buffered Stream will run in buffered mode (delivers as
buffers are filled), reduces overhead and impact
to application. Normal stream is 1 IPC per mes-
sage. This option only applies when directed
towards a specific process.
-errors Watch for software errors triggered by processes.
-faults Watch for software faults triggered by processes.
Allows watching for a specific activity based on
name. The binary must be listed first, e.g.,
"AppKit:sendAction:".
-filter query Stream will filter messages based on the provided
(required) query argument. See section "Filtering"
below.
-list file Will list all available trace related strings for
a binary.
-payload Will output the payload content, forcing the out-
put to be JSON. If the output is cancelled then a
trailing ']' may be needed to make JSON parsers
happy.
-parent pid When passed with -stream any processes that are
sent IPC from the provided PID will also stream
messages associated with the same activity.
-process pid The process to operate on. This option can be
passed more than once to operate on multiple pro-
cesses. Passing -1 in conjunction with -setmode
or -stream will change the global mode of the sys-
tem.
-setmode disable|default|debug|stream
Changes the mode of a process. The parameter
-setmode can be passed more than once to enable
multiple modes. An environment variable can be
used to enable a specific mode:
OS_ACTIVITY_MODE="stream"
NOTE: -setmode must be accompanied by a -process
pid or -parent pid argument.
-timeout seconds Timeout a stream or watch operation after a speci-
fied number of seconds.
-source Include symbol names and source line numbers for
-stream
-stream Stream breadcrumbs, activities and/or trace mes-
sages from a given process. Using this flag with-
out a process will listen for anything that is in
stream mode.
-type activity|breadcrumb|message
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.
-quiet Reduce the amount of duplicate information in
ostraceutil output.
-watch Watch for events for a given process or all pro-
cesses. The default will be to watch both types of
events if neither -fault nor -error is provided.
FILTERING
Filtering via the -filter query option allows users to focus on messages
based on the provided query criteria. The query argument defines one or
more key/pattern clauses with the form 'type:"pattern"[,type:"pat-
tern"...]' (additional clauses separated by commas) where pattern is an
extended regular expression (see regex(3)) and type is one of the follow-
ing:
message Matches pattern with the message text, activity name, or bread-
crumb name of a trace entry.
process Matches pattern with the name of the process that originated the
trace entry.
In addition to multiple clauses per -filter query argument, more than one
-filter query argument may be provided. Clauses within an individual
-filter query argument will be joined using a logical AND, while multiple
-filter query arguments will be joined using a logical OR. Thus, the fol-
lowing example
ostraceutil -stream -filter 'process:"my_process",message:"unexpected"'
would result in ostraceutil only streaming messages from the process
named "my_process" AND whose message text contained "unexpected", while
the following example
ostraceutil -stream -filter 'process:"my_process"' -filter 'message:"unexpected"'
would result in ostraceutil only streaming messages from the process
named "my_process" OR those whose message text contained "unexpected".
NOTE: To avoid shell expansion of special characters in the regex(3) pat-
tern, query arguments must be enclosed in single quotes.
ADDITIONAL FILTERING EXAMPLES
To filter messages from a single process:
ostraceutil -stream -filter 'process:"process_name"'
To filter messages from a single process OR messages containing the key-
word ALERT:
ostraceutil -stream -filter 'process:"process_name"' -filter 'message:"ALERT"'
To filter messages pertaining to the creation of an activity (see
os_activity_initiate(3)):
ostraceutil -stream -filter 'message:"activity_description"'
Likewise to filter messages pertaining to the creation of a breadcrumb
(see os_activity_set_breadcrumb(3)):
ostraceutil -stream -filter 'message:"breadcrumb_name"'
SEE ALSO
os_trace(3), os_activity_initiate(3), regex(3)
Darwin January 28, 2017 Darwin
Mac OS X 10.11.6 - Generated Sat Jan 28 08:22:58 CST 2017