NAME¶

uftrace - Function graph tracer for userspace

SYNOPSIS¶

uftrace [record|replay|live|report|info|dump|recv|graph|script|tui] [options] COMMAND [command-options]

DESCRIPTION¶

The uftrace tool is a function tracer that traces the execution of given COMMAND at the function level. COMMAND should be a C or C++ executable built with compiler instrumentation (-pg or -finstrument-functions). COMMAND needs to have an ELF symbol table (i.e. not be strip(1)-ed) in order for the names of traced functions to be available.

The uftrace command consists of a number of sub-commands, in the manner of git(1) or perf(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.

For convenience, if no sub-command is given, uftrace acts as though the live sub-command was specified, which runs the record and replay sub-commands in turn. See uftrace-live(1) for options belonging to the live sub-command. For more detailed analysis, it is better to use uftrace-record(1) to save trace data, and then analyze it with other uftrace commands like uftrace-replay(1), uftrace-report(1), uftrace-info(1), uftrace-dump(1), uftrace-script(1) or uftrace-tui(1).

SUB-COMMANDS¶

record

Run a given command and save trace data in a data file or directory.

replay

Print recorded function trace data with time durations.

live

Do live tracing. Print function trace of the given command.

report

Print various statistics and summary of the recorded trace data.

info

Print side-band information like OS version, CPU info, command line and so on.

dump

Print raw tracing data in the data files.

recv

Save tracing data sent to network

graph

Print function call graph

script

Run a script for recorded function trace

tui

Show text user interface for graph and report

OPTIONS¶

-h, --help

Print help message and list of options with description

--usage

Print usage string

-V, --version

Print program version

-v, --verbose

Print verbose messages. This option increases a debug level and can be used at most 3 times.

--debug

Print debug messages. This option is same as -v/--verbose and is provided only for backward compatibility.

--debug-domain=DOMAIN[,DOMAIN, ...]

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, -v --debug-domain=filter:2 will apply debug level of 2 to the “filter” domain and apply debug level of 1 to others.

-d DATA, --data=DATA

Specify name of trace data (directory). Default is uftrace.data.

--logfile=FILE

Save warning and debug messages into this file instead of stderr.

--color=VAL

Enable or disable color on the output. Possible values are “yes”(= “true” | “1” | “on” ), “no”(= “false” | “0” | “off” ) and “auto”. The “auto” value is default and turns on coloring if stdout is a terminal.

--no-pager

Do not use a pager.

--opt-file=FILE

Read command-line options from the FILE.

SEE ALSO¶

uftrace-live(1), uftrace-record(1), uftrace-replay(1), uftrace-report(1), uftrace-info(1), uftrace-dump(1), uftrace-recv(1), uftrace-graph(1), uftrace-script(1), uftrace-tui(1)

AUTHORS¶

Namhyung Kim <namhyung@gmail.com>.