--- name: "uftrace" section: "1" platform: "linux" package: "uftrace" version: "0.17-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/uftrace" --- # uftrace(1) 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)](/strip/1.md)-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)](/git/1.md) or [`perf`(1)](/perf/1.md). 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)](/uftrace-live/1.md) for options belonging to the `live` sub-command. For more detailed analysis, it is better to use [`uftrace-record`(1)](/uftrace-record/1.md) to save trace data, and then analyze it with other uftrace commands like [`uftrace-replay`(1)](/uftrace-replay/1.md), [`uftrace-report`(1)](/uftrace-report/1.md), [`uftrace-info`(1)](/uftrace-info/1.md), [`uftrace-dump`(1)](/uftrace-dump/1.md), [`uftrace-script`(1)](/uftrace-script/1.md) or [`uftrace-tui`(1)](/uftrace-tui/1.md). ## 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)](/uftrace-live/1.md) 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-live/1.md), [`uftrace-record`(1)](/uftrace-record/1.md), [`uftrace-replay`(1)](/uftrace-replay/1.md), [`uftrace-report`(1)](/uftrace-report/1.md), [`uftrace-info`(1)](/uftrace-info/1.md), [`uftrace-dump`(1)](/uftrace-dump/1.md), [`uftrace-recv`(1)](/uftrace-recv/1.md), [`uftrace-graph`(1)](/uftrace-graph/1.md), [`uftrace-script`(1)](/uftrace-script/1.md), [`uftrace-tui`(1)](/uftrace-tui/1.md) ## AUTHORS Namhyung Kim ⟨namhyung@gmail.com⟩\\c.