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.
NOTE: trace is obsolete. The command you probably want is ktrace(1)
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 collected.
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 filtered 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 format.
-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 subclass 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 typi-
cal 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 sec-
ond, then disables tracing and prints it to stdout(4). This is useful for investigating isolated issues or gaining some understanding about
a kernel 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