Ubuntu Manpage: uftrace - Function graph tracer for userspace

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

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

AUTHORS

       Namhyung Kim <namhyung@gmail.com>.