UFTRACE(1) UFTRACE(1)

uftrace - Function graph tracer for userspace

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

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).

Run a given command and save trace data in a data file or directory.
Print recorded function trace data with time durations.
Do live tracing. Print function trace of the given command.
Print various statistics and summary of the recorded trace data.
Print side-band information like OS version, CPU info, command line and so on.
Print raw tracing data in the data files.
Save tracing data sent to network
Print function call graph
Run a script for recorded function trace
Show text user interface for graph and report

These are the common options supported by all uftrace subcommands:

Print help message and list of options with description
Print usage string
Print program version
Print verbose messages. This option increases a debug level and can be used at most 3 times.
Print debug messages. This option is same as -v/--verbose and is provided only for backward compatibility.
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.
Specify name of trace data (directory). Default is uftrace.data.
Save warning and debug messages into this file instead of stderr.
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.
Do not use a pager.
Read command-line options from the FILE.

These options are listed here for completeness, but are only effective with specific subcommands.

Please see the uftrace-<subcommand> manual pages for more information: The manual for uftrace-live(1) is special: The subcommand live does record and replay internally. Thus, it describes most regular option in detail.

Show average/min/max of self function time
Show average/min/max of total function time
Show arguments and return value of known functions
Show function arguments
Size of tracing buffer (default: 128K)
Dump recorded data in chrome trace format
Set clock source for timestamp (default: mono)
Offset of each column (default: 8)
Print tasks in separate columns
Only trace callers of those FUNCs
C++ symbol demangling: full, simple, no (default: simple)
Report differences
Control diff report policy (default: `abs,compact,no-percent')
Start with tracing disabled
Trace functions within DEPTH
Use only entry record type for safety
Show all events outside of function
Enable EVENT to save more information
Dump recorded data in FlameGraph format
Use flat output format
Trace even if executable is not instrumented
Use FORMAT for output: normal, html (default: normal)
Show FIELDs in the replay or graph output
Only trace those FUNCs
Start an agent in mcount to listen to commands
Dump recorded data in DOT format
Hide FUNCs from trace
Send trace data to HOST instead of write to file
Trace kernel functions also (if supported)
Keep same pid during execution of traced program
Size of kernel tracing buffer (default: 1408K)
Show kernel functions outside of user
Dump kernel data only
Skip kernel functions outside of user (deprecated)
Trace kernel functions within DEPTH
Use single thread version of libmcount
List available events
Save warning and debug messages into this file instead of stderr.
Show nested library calls
Show libname name with symbol name
Load libmcount libraries from this PATH
Support pattern match: regex, glob (default: regex)
Set max stack depth to DEPTH (default: 65535)
Do not show arguments and return value
Don’t show comments of returned functions
Disable (default) events
Disable schedule events
Hide pre-emptive schedule event but show regular(sleeping) schedule event
Don’t trace library function calls
Don’t merge leaf functions
Do not bind dynamic symbols (LD_BIND_NOT)
Disable ASLR (Address Space Layout Randomization)
No operation (for performance test)
Create NUM recorder threads
Don’t trace those FUNCs
Connect to the PID of an interactive mcount instance
Use PORT for network connection (default: 8090)
Apply dynamic patching for FUNCs
Record a new trace before running given script
Show a live report before replay
Record with real-time (FIFO) priority
Show output within the TIME (timestamp or elapsed time) range only
Command line that want to execute after tracing data received
Show function return values for FUNC, optionally with given uftrace retspec
Show flame graph with this sampling time
Trigger the given actions when the given SIGNAL is received
Sort diff report on column INDEX (default: 2)
Enable recording source line info
Print symbol table instead of the recorded tracing info
Sort reported functions by KEYs (default: 2)
Run a given SCRIPT in function entry and exit
Hide small functions run less than the TIME
Print task relationship in a tree form instead of the tracing info.
Interleave a newline when task is changed
Only replay those tasks
Print time information
Trigger action on those FUNCs
Don’t apply dynamic patching for FUNCs
Use symbol files in the DIR
Watch and report POINT if it’s changed
Apply dynamic patching for functions bigger than SIZE

For more detail about these command-specific options, please see the more specific manual pages listed below.

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)

Namhyung Kim <namhyung@gmail.com>.

Sep, 2018 Uftrace User Manuals