UFTRACE(1)

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

COMMON OPTIONS
These are the common options supported by all uftrace subcommands:

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

SUBCOMMAND-SPECIFIC OPTIONS
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.

--avg-self
    Show average/min/max of self function time

--avg-total
    Show average/min/max of total function time

-a, --auto-args
    Show arguments and return value of known functions

-A, --argument=FUNC@arg[,arg,...]
    Show function arguments

-b, --buffer=SIZE
    Size of tracing buffer (default: 128K)

--chrome
    Dump recorded data in chrome trace format

--clock
    Set clock source for timestamp (default: mono)

--column-offset=DEPTH
    Offset of each column (default: 8)

--column-view
    Print tasks in separate columns

-C, --caller-filter=FUNC
    Only trace callers of those FUNCs

--demangle=TYPE
    C++ symbol demangling: full, simple, no (default: simple)

--diff=DATA
    Report differences

--diff-policy=POLICY
    Control diff report policy (default: `abs,compact,no-percent')

--disable
    Start with tracing disabled

-D, --depth=DEPTH
    Trace functions within DEPTH

-e, --estimate-return
    Use only entry record type for safety

--event-full
    Show all events outside of function

-E, --Event=EVENT
    Enable EVENT to save more information

--flame-graph
    Dump recorded data in FlameGraph format

--flat
    Use flat output format

--force
    Trace even if executable is not instrumented

--format=FORMAT
    Use FORMAT for output: normal, html (default: normal)

-f, --output-fields=FIELD
    Show FIELDs in the replay or graph output

-F, --filter=FUNC
    Only trace those FUNCs

-g, --agent
    Start an agent in mcount to listen to commands

--graphviz
    Dump recorded data in DOT format

-H, --hide=FUNC
    Hide FUNCs from trace

--host=HOST
    Send trace data to HOST instead of write to file

-k, --kernel
    Trace kernel functions also (if supported)

--keep-pid
    Keep same pid during execution of traced program

--kernel-buffer=SIZE
    Size of kernel tracing buffer (default: 1408K)

--kernel-full
    Show kernel functions outside of user

--kernel-only
    Dump kernel data only

--kernel-skip-out
    Skip kernel functions outside of user (deprecated)

-K, --kernel-depth=DEPTH
    Trace kernel functions within DEPTH

--libmcount-single
    Use single thread version of libmcount

--list-event
    List available events

--logfile=FILE
    Save warning and debug messages into this file instead of stderr.

-l, --nest-libcall
    Show nested library calls

--libname
    Show libname name with symbol name

--libmcount-path=PATH
    Load libmcount libraries from this PATH

--match=TYPE
    Support pattern match: regex, glob (default: regex)

--max-stack=DEPTH
    Set max stack depth to DEPTH (default: 65535)

--no-args
    Do not show arguments and return value

--no-comment
    Don’t show comments of returned functions

--no-event
    Disable (default) events

--no-sched
    Disable schedule events

--no-sched-preempt
    Hide pre-emptive schedule event but show regular(sleeping) schedule event

--no-libcall
    Don’t trace library function calls

--no-merge
    Don’t merge leaf functions

--no-pltbind
    Do not bind dynamic symbols (LD_BIND_NOT)

--no-randomize-addr
    Disable ASLR (Address Space Layout Randomization)

--nop
    No operation (for performance test)

--num-thread=NUM
    Create NUM recorder threads

-N, --notrace=FUNC
    Don’t trace those FUNCs

-p, --pid=PID
    Connect to the PID of an interactive mcount instance

--port=PORT
    Use PORT for network connection (default: 8090)

-P, --patch=FUNC
    Apply dynamic patching for FUNCs

--record
    Record a new trace before running given script

--report
    Show a live report before replay

--rt-prio=PRIO
    Record with real-time (FIFO) priority

-r, --time-range=TIME~TIME
    Show output within the TIME (timestamp or elapsed time) range only

--run-cmd=CMDLINE
    Command line that want to execute after tracing data received

-R, --retval=FUNC[@retspec]
    Show function return values for FUNC, optionally with given uftrace retspec

--sample-time=TIME
    Show flame graph with this sampling time

--signal=SIGNAL@act[,act,...]
    Trigger the given actions when the given SIGNAL is received

--sort-column=INDEX
    Sort diff report on column INDEX (default: 2)

--srcline
    Enable recording source line info

--symbols
    Print symbol table instead of the recorded tracing info

-s, --sort=KEY[,KEY,...]
    Sort reported functions by KEYs (default: 2)

-S, --script=SCRIPT
    Run a given SCRIPT in function entry and exit

-t, --time-filter=TIME
    Hide small functions run less than the TIME

--task
    Print task relationship in a tree form instead of the tracing info.

--task-newline
    Interleave a newline when task is changed

--tid=TID[,TID,...]
    Only replay those tasks

--time
    Print time information

-T, --trigger=FUNC@act[,act,...]
    Trigger action on those FUNCs

-U, --unpatch=FUNC
    Don’t apply dynamic patching for FUNCs

--with-syms=DIR
    Use symbol files in the DIR

-W, --watch=POINT
    Watch and report POINT if it’s changed

-Z, --size-filter=SIZE
    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.

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