Unknown option: "-4"
Unix manual page for trace. (host=minya system=Darwin)
TRACE(1) BSD General Commands Manual TRACE(1)
NAME
trace -- configure, record, and display kernel trace events
SYNOPSIS
trace -d [-a pid | -x pid]
trace -e [-c class [-p end-class] [-s subclass]] [-a pid | -x pid]
[-k code] [-P] [-T filter-file]
trace -E [-c class [-p end-class] [-s subclass]] [-a pid | -x pid]
[-k code] [-P] [-T tracefilter] command [argument ...]
trace -h
trace -i [-b num-events]
trace -g
trace -l rawfile
trace -L rawfile [-S secs]
trace -n
trace -r
trace -R rawfile [-X] [-F frequency] [-o outfile] [-N] [codesfile ...]
trace -t [-o outfile] [-N] [codesfile ...]
DESCRIPTION
trace initializes and configures the kernel trace subsystem. Trace
events can be recorded to an in-memory buffer or logged directly to a
file, and optionally converted to a human-readable, plain-text format.
trace operates according to the command flag specified.
COMMANDS
-h Print a succinct help message to stdout(4).
-i [-b num-events]
Initialize the kernel trace buffer. This command is required
before tracing.
-b num-events
Set the number of events that can be stored in the kernel
trace buffer. num-events is a decimal number of events.
The default (and minimum) value is 8192 event records per
logical CPU. No more than half of available memory may
be used by trace buffers, though running with a buffer
this large is not recommended.
-g Print the current kernel trace buffer settings to stdout(4).
-d [-a pid | -x pid]
By default, disable collection of events. This command does not
remove the kernel trace buffer.
-a pid Disable event collection for the process identified by
pid.
-x pid Stop excluding pid from the trace. This reenables event
collection of events for. pid.
-r Remove the kernel trace buffer.
-n Disable ring buffer mode. When set, the trace buffer will fill
to capacity and then stop collecting events. Ring buffer mode is
sometimes called "head," "stop," or "no-wrap" mode. By default,
the trace buffer will wrap around, overwriting previous events.
The default behavior is sometimes called windowed or wrap-around
mode.
-e [-c class [-p end-class] [-s subclass]] [-a pid | -x pid]
[-k code ...] [-P] [-T filter-file]
Enable collection of events. By default, all events are col-
lected.
Options can be used to restrict collection to specific classes,
class ranges, subclasses, and codes. Classes and subclasses can
be specified any number of times, but only 4 codes can be fil-
tered at once. Values can be specified in hex (0x...), decimal,
or octal (0...).
-c class
Restrict collection to the events with the specified class.
This option can be specified any number of times to collect
events from more classes.
-p end-class
Provide an ending class to restrict collection to events in
an inclusive range of classes between class and end-class.
-s subclass
Restrict collection to the events with the specified
subclass.
-a pid
Restrict collection to to those events emitted by the process
identified by pid.
-x pid
Exclude events emitted by the process identified by pid.
-k code
Restrict collection to events with the specified code. This
option can be specified up to 4 times, and applies to all
classes being collected.
-T filter-file
Restrict collection to events specified in the provided
filter-file. See TRACEFILTER FORMAT for details.
-P Restrict collection to PPT events. This special collection of
trace events provides insight into system performance.
-E [-c class [-p end-class] [-s subclass]] [-a pid | -x pid]
[-k code ...] [-P] [-T filter-file] command [args ...]
Execute command with trace collection enabled for events emitted
by the process. See -e for more information.
-t [-o outfile] [-N] [codesfile ...]
Extract events from the kernel trace buffer and print them in a
formatted, plain-text representation. Additional code files can
be specified to help trace find the names of unknown events. For
more information on the formatting process, see TRACE CODES
FORMAT.
-o outfile
Output the plain-text events to outfile.
-N Ignore the system-wide trace codes file when getting
names of events. Additional trace codes files specified
will still be used.
-l rawfile
Empty the current kernel trace buffer into rawfile in a binary
format. If rawfile is -, the file will be written to stdout(4).
-L rawfile -S seconds
Copy the current trace buffer to rawfile and send all future
trace events to rawfile.
-S seconds
After seconds have elapsed, stop recording and exit. If
rawfile is -, the file will be written to stdout(4).
-R rawfile [-o outfile] [-N] [-F frequency] [-X] [codesfile ...]
Read events from rawfile and print them in a human-readable for-
mat.
-F frequency
If rawfile does not contain clock frequency information, it
can be specified with -F.
-X
Force the binary format to be interpreted as 32-bit, as
opposed to matching the width of the system running trace.
See -t for additional options.
TRACE CODES FORMAT
Event classes, subclasses, and codes are matched to names using a trace
codes file. Any events that cannot be matched will be referred to by
their debugid in hex.
The system-wide trace codes file is located at
/usr/share/misc/trace.codes. Additional files are typically stored in
/usr/local/share/misc.
A code file consists of a list of tracepoints, one per line, with the
tracepoint's debugid (component, subclass, and code) in hex, followed by
a tab, followed by the tracepoint's name.
For instance, the MSC_mach_msg_trap tracepoint is defined by
0x010c007c MSC_mach_msg_trap
This describes the tracepoint with the following info:
Name MSC_mach_msg_trap
Class 0x01 (Mach events)
Subclass 0x0c (Mach system calls)
Code 0x007c (msg_trap)
See /usr/include/sys/kdebug.h for class and subclass values.
TRACEFILTER FORMAT
A tracefilter description file consists of a list of class and subclass
filters in hex, one per line, which are applied as if they were passed
with -c and -s. Pass -v to see what classes and subclasses are being
set.
Comment lines start with `#', class filter lines start with `C', and sub-
class filter lines start with `S' and include the class they apply to.
For example, to trace Mach events (class 1):
C 0x01
And to trace Mach system calls (class 1, subclass 13):
S 0x010C
EXAMPLES
trace usually requires multiple invocations in order to set up the trace
buffers, enable the correct events, and collect the events. A typical
session with trace is:
trace -i
trace -e -c 1 -s 31
sleep 1
trace -d
trace -t
This initializes the trace buffers to their default values, enables the
mach_msg_trap subclass of the MACH_SysCall class, waits for one second,
then disables tracing and prints it to stdout(4). This is useful for
investigating isolated issues or gaining some understanding about a ker-
nel subsystem. If a specific execuable should be traced, with the events
saved for later analysis, the sequence of commands would be:
trace -i
trace -E -c 0x4 ./my_prog
trace -d
trace -l tracefile
trace -R tracefile
This initializes the trace buffers, enables all events in the BSC_SysCall
class and runs my_prog, disables tracing, collects events into tracefile,
and finally prints those events out in a human-readable form.
CAVEATS
Almost all trace command flags require superuser (root) privileges.
After failures, the trace buffers usually need to be re-initialized.
DIAGNOSTICS
The trace utility exits 0 on success, and >0 if an error occurs.
SEE ALSO
trace(4), fs_usage(1), sc_usage(1), latency(1), top(1)
Mac OS X April 3, 2015 Mac OS X