uftrace1

Usage

Overview

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

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.

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.