.\" Automatically generated by Pandoc 2.9.2.1
.\"
.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[C]COMMAND\f[R] at the function level.
\f[C]COMMAND\f[R] should be a C or C++ executable built with compiler
instrumentation (\f[C]-pg\f[R] or \f[C]-finstrument-functions\f[R]).
COMMAND needs to have an ELF symbol table (i.e.\ not be
\f[C]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[C]git\f[R](1) or \f[C]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[C]live\f[R] sub-command was specified, which runs the
\f[C]record\f[R] and \f[C]replay\f[R] sub-commands in turn.
See \f[C]uftrace-live\f[R](1) for options belonging to the
\f[C]live\f[R] sub-command.
For more detailed analysis, it is better to use
\f[C]uftrace-record\f[R](1) to save trace data, and then analyze it with
other uftrace commands like \f[C]uftrace-replay\f[R](1),
\f[C]uftrace-report\f[R](1), \f[C]uftrace-info\f[R](1),
\f[C]uftrace-dump\f[R](1), \f[C]uftrace-script\f[R](1) or
\f[C]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 OPTIONS
.TP
-?, --help
Print help message and list of options with description
.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[C]-v\f[R]/\f[C]--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[C]-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[C]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 SEE ALSO
.PP
\f[C]uftrace-live\f[R](1), \f[C]uftrace-record\f[R](1),
\f[C]uftrace-replay\f[R](1), \f[C]uftrace-report\f[R](1),
\f[C]uftrace-info\f[R](1), \f[C]uftrace-dump\f[R](1),
\f[C]uftrace-recv\f[R](1), \f[C]uftrace-graph\f[R](1),
\f[C]uftrace-script\f[R](1), \f[C]uftrace-tui(1)\f[R]
.SH AUTHORS
Namhyung Kim <namhyung@gmail.com>.