.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "UFTRACE" "1" "Sep, 2018" "Uftrace User Manuals" ""
.hy
.SH NAME
.PP
uftrace - Function graph tracer for userspace
.SH SYNOPSIS
.PP
uftrace
[\f[I]record\f[R]|\f[I]replay\f[R]|\f[I]live\f[R]|\f[I]report\f[R]|\f[I]info\f[R]|\f[I]dump\f[R]|\f[I]recv\f[R]|\f[I]graph\f[R]|\f[I]script\f[R]|\f[I]tui\f[R]]
[\f[I]options\f[R]] COMMAND [\f[I]command-options\f[R]]
.SH DESCRIPTION
.PP
The uftrace tool is a function tracer that traces the execution of given
\f[V]COMMAND\f[R] at the function level.
\f[V]COMMAND\f[R] should be a C or C++ executable built with compiler
instrumentation (\f[V]-pg\f[R] or \f[V]-finstrument-functions\f[R]).
COMMAND needs to have an ELF symbol table (i.e.\ not be
\f[V]strip\f[R](1)-ed) in order for the names of traced functions to be
available.
.PP
The uftrace command consists of a number of sub-commands, in the manner
of \f[V]git\f[R](1) or \f[V]perf\f[R](1).
Below is a short description of each sub-command.
For more detailed information, see the respective manual pages.
The options in this page can be given to any sub-command also.
.PP
For convenience, if no sub-command is given, uftrace acts as though the
\f[V]live\f[R] sub-command was specified, which runs the
\f[V]record\f[R] and \f[V]replay\f[R] sub-commands in turn.
See \f[V]uftrace-live\f[R](1) for options belonging to the
\f[V]live\f[R] sub-command.
For more detailed analysis, it is better to use
\f[V]uftrace-record\f[R](1) to save trace data, and then analyze it with
other uftrace commands like \f[V]uftrace-replay\f[R](1),
\f[V]uftrace-report\f[R](1), \f[V]uftrace-info\f[R](1),
\f[V]uftrace-dump\f[R](1), \f[V]uftrace-script\f[R](1) or
\f[V]uftrace-tui\f[R](1).
.SH SUB-COMMANDS
.TP
record
Run a given command and save trace data in a data file or directory.
.TP
replay
Print recorded function trace data with time durations.
.TP
live
Do live tracing.
Print function trace of the given command.
.TP
report
Print various statistics and summary of the recorded trace data.
.TP
info
Print side-band information like OS version, CPU info, command line and
so on.
.TP
dump
Print raw tracing data in the data files.
.TP
recv
Save tracing data sent to network
.TP
graph
Print function call graph
.TP
script
Run a script for recorded function trace
.TP
tui
Show text user interface for graph and report
.SH COMMON OPTIONS
.PP
These are the common options supported by all uftrace subcommands:
.TP
-h, --help
Print help message and list of options with description
.TP
--usage
Print usage string
.TP
-V, --version
Print program version
.TP
-v, --verbose
Print verbose messages.
This option increases a debug level and can be used at most 3 times.
.TP
--debug
Print debug messages.
This option is same as \f[V]-v\f[R]/\f[V]--verbose\f[R] and is provided
only for backward compatibility.
.TP
--debug-domain=\f[I]DOMAIN\f[R][,\f[I]DOMAIN\f[R], \&...]
Limit the printing of debug messages to those belonging to one of the
DOMAINs specified.
Available domains are: uftrace, symbol, demangle, filter, fstack,
session, kernel, mcount, dynamic, event, script and dwarf.
The domains can have an their own debug level optionally (preceded by a
colon).
For example, \f[V]-v --debug-domain=filter:2\f[R] will apply debug level
of 2 to the \[lq]filter\[rq] domain and apply debug level of 1 to
others.
.TP
-d \f[I]DATA\f[R], --data=\f[I]DATA\f[R]
Specify name of trace data (directory).
Default is \f[V]uftrace.data\f[R].
.TP
--logfile=\f[I]FILE\f[R]
Save warning and debug messages into this file instead of stderr.
.TP
--color=\f[I]VAL\f[R]
Enable or disable color on the output.
Possible values are \[lq]yes\[rq](= \[lq]true\[rq] | \[lq]1\[rq] |
\[lq]on\[rq] ), \[lq]no\[rq](= \[lq]false\[rq] | \[lq]0\[rq] |
\[lq]off\[rq] ) and \[lq]auto\[rq].
The \[lq]auto\[rq] value is default and turns on coloring if stdout is a
terminal.
.TP
--no-pager
Do not use a pager.
.TP
--opt-file=\f[I]FILE\f[R]
Read command-line options from the FILE.
.SH SUBCOMMAND-SPECIFIC OPTIONS
.PP
These options are listed here for completeness, but are only effective
with specific subcommands.
.PP
Please see the uftrace-<\f[I]subcommand\f[R]> manual pages for more
information: The manual for \f[I]uftrace-live\f[R](1) is special: The
subcommand \f[V]live\f[R] does \f[V]record\f[R] and \f[V]replay\f[R]
internally.
Thus, it describes most regular option in detail.
.TP
--avg-self
Show average/min/max of self function time
.TP
--avg-total
Show average/min/max of total function time
.TP
-a, --auto-args
Show arguments and return value of known functions
.TP
-A, --argument=\f[I]FUNC\f[R]\[at]arg[,arg,\&...]
Show function arguments
.TP
-b, --buffer=\f[I]SIZE\f[R]
Size of tracing buffer (default: 128K)
.TP
--chrome
Dump recorded data in chrome trace format
.TP
--clock
Set clock source for timestamp (default: mono)
.TP
--column-offset=\f[I]DEPTH\f[R]
Offset of each column (default: 8)
.TP
--column-view
Print tasks in separate columns
.TP
-C, --caller-filter=\f[I]FUNC\f[R]
Only trace callers of those FUNCs
.TP
--demangle=\f[I]TYPE\f[R]
C++ symbol demangling: full, simple, no
(default: simple)
.TP
--diff=\f[I]DATA\f[R]
Report differences
.TP
--diff-policy=\f[I]POLICY\f[R]
Control diff report policy
(default: `abs,compact,no-percent')
.TP
--disable
Start with tracing disabled
.TP
-D, --depth=\f[I]DEPTH\f[R]
Trace functions within \f[I]DEPTH\f[R]
.TP
-e, --estimate-return
Use only entry record type for safety
.TP
--event-full
Show all events outside of function
.TP
-E, --Event=\f[I]EVENT\f[R]
Enable \f[I]EVENT\f[R] to save more information
.TP
--flame-graph
Dump recorded data in FlameGraph format
.TP
--flat
Use flat output format
.TP
--force
Trace even if executable is not instrumented
.TP
--format=\f[I]FORMAT\f[R]
Use \f[I]FORMAT\f[R] for output: normal, html (default: normal)
.TP
-f, --output-fields=\f[I]FIELD\f[R]
Show FIELDs in the replay or graph output
.TP
-F, --filter=\f[I]FUNC\f[R]
Only trace those FUNCs
.TP
-g, --agent
Start an agent in mcount to listen to commands
.TP
--graphviz
Dump recorded data in \f[I]DOT\f[R] format
.TP
-H, --hide=\f[I]FUNC\f[R]
Hide FUNCs from trace
.TP
--host=\f[I]HOST\f[R]
Send trace data to \f[I]HOST\f[R] instead of write to file
.TP
-k, --kernel
Trace kernel functions also (if supported)
.TP
--keep-pid
Keep same pid during execution of traced program
.TP
--kernel-buffer=\f[I]SIZE\f[R]
Size of kernel tracing buffer (default: 1408K)
.TP
--kernel-full
Show kernel functions outside of user
.TP
--kernel-only
Dump kernel data only
.TP
--kernel-skip-out
Skip kernel functions outside of user (deprecated)
.TP
-K, --kernel-depth=\f[I]DEPTH\f[R]
Trace kernel functions within \f[I]DEPTH\f[R]
.TP
--libmcount-single
Use single thread version of libmcount
.TP
--list-event
List available events
.TP
--logfile=\f[I]FILE\f[R]
Save warning and debug messages into this file instead of stderr.
.TP
-l, --nest-libcall
Show nested library calls
.TP
--libname
Show libname name with symbol name
.TP
--libmcount-path=\f[I]PATH\f[R]
Load libmcount libraries from this \f[I]PATH\f[R]
.TP
--match=\f[I]TYPE\f[R]
Support pattern match: regex, glob (default:
regex)
.TP
--max-stack=\f[I]DEPTH\f[R]
Set max stack depth to \f[I]DEPTH\f[R] (default: 65535)
.TP
--no-args
Do not show arguments and return value
.TP
--no-comment
Don\[cq]t show comments of returned functions
.TP
--no-event
Disable (default) events
.TP
--no-sched
Disable schedule events
.TP
--no-sched-preempt
Hide pre-emptive schedule event
but show regular(sleeping) schedule event
.TP
--no-libcall
Don\[cq]t trace library function calls
.TP
--no-merge
Don\[cq]t merge leaf functions
.TP
--no-pltbind
Do not bind dynamic symbols (\f[I]LD_BIND_NOT\f[R])
.TP
--no-randomize-addr
Disable \f[I]ASLR\f[R] (Address Space Layout Randomization)
.TP
--nop
No operation (for performance test)
.TP
--num-thread=\f[I]NUM\f[R]
Create \f[I]NUM\f[R] recorder threads
.TP
-N, --notrace=\f[I]FUNC\f[R]
Don\[cq]t trace those FUNCs
.TP
-p, --pid=\f[I]PID\f[R]
Connect to the \f[I]PID\f[R] of an interactive mcount instance
.TP
--port=\f[I]PORT\f[R]
Use \f[I]PORT\f[R] for network connection (default: 8090)
.TP
-P, --patch=\f[I]FUNC\f[R]
Apply dynamic patching for FUNCs
.TP
--record
Record a new trace before running given script
.TP
--report
Show a live report before replay
.TP
--rt-prio=\f[I]PRIO\f[R]
Record with real-time (\f[I]FIFO\f[R]) priority
.TP
-r, --time-range=\f[I]TIME\f[R]\[ti]\f[I]TIME\f[R]
Show output within the \f[I]TIME\f[R] (timestamp or elapsed time)
range only
.TP
--run-cmd=\f[I]CMDLINE\f[R]
Command line that want to execute after tracing
data received
.TP
-R, --retval=\f[I]FUNC\f[R][\[at]retspec]
Show function return values for \f[I]FUNC\f[R], optionally with given
uftrace retspec
.TP
--sample-time=\f[I]TIME\f[R]
Show flame graph with this sampling time
.TP
--signal=\f[I]SIGNAL\f[R]\[at]act[,act,\&...]
Trigger the given actions when the given \f[I]SIGNAL\f[R] is received
.TP
--sort-column=\f[I]INDEX\f[R]
Sort diff report on column \f[I]INDEX\f[R] (default: 2)
.TP
--srcline
Enable recording source line info
.TP
--symbols
Print symbol table instead of the recorded tracing info
.TP
-s, --sort=\f[I]KEY\f[R][,\f[I]KEY\f[R],\&...]
Sort reported functions by KEYs (default: 2)
.TP
-S, --script=\f[I]SCRIPT\f[R]
Run a given \f[I]SCRIPT\f[R] in function entry and exit
.TP
-t, --time-filter=\f[I]TIME\f[R]
Hide small functions run less than the \f[I]TIME\f[R]
.TP
--task
Print task relationship in a tree form instead of the tracing info.
.TP
--task-newline
Interleave a newline when task is changed
.TP
--tid=\f[I]TID\f[R][,\f[I]TID\f[R],\&...]
Only replay those tasks
.TP
--time
Print time information
.TP
-T, --trigger=\f[I]FUNC\f[R]\[at]act[,act,\&...]
Trigger action on those FUNCs
.TP
-U, --unpatch=\f[I]FUNC\f[R]
Don\[cq]t apply dynamic patching for FUNCs
.TP
--with-syms=\f[I]DIR\f[R]
Use symbol files in the \f[I]DIR\f[R]
.TP
-W, --watch=\f[I]POINT\f[R]
Watch and report \f[I]POINT\f[R] if it\[cq]s changed
.TP
-Z, --size-filter=\f[I]SIZE\f[R]
Apply dynamic patching for functions bigger than \f[I]SIZE\f[R]
.PP
For more detail about these command-specific options, please see the
more specific manual pages listed below.
.SH SEE ALSO
.PP
\f[V]uftrace-live\f[R](1), \f[V]uftrace-record\f[R](1),
\f[V]uftrace-replay\f[R](1), \f[V]uftrace-report\f[R](1),
\f[V]uftrace-info\f[R](1), \f[V]uftrace-dump\f[R](1),
\f[V]uftrace-recv\f[R](1), \f[V]uftrace-graph\f[R](1),
\f[V]uftrace-script\f[R](1), \f[V]uftrace-tui\f[R](1)
.SH AUTHORS
Namhyung Kim <namhyung@gmail.com>.