UFTRACE(1)

📦
version 0.19 · 6 versions
, in nixos 26.05, ubuntu stonking

✨ UFTRACE(1) ✨

okay bestie, welcome to the General Commands Manual entry for uftrace(1) — like, THE function graph tracer for userspace. buckle up 🎀

💖 NAME 💖

uftrace — Function graph tracer for userspace

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

so. uftrace is a function tracer, and what it does is trace the execution of whatever COMMAND you hand it, but at the function level. that's the whole vibe. ✨

COMMAND has to be a C or C++ executable that was built with compiler instrumentation — we're talking -pg or -finstrument-functions. and it also needs an ELF symbol table (so basically: don't let anyone strip(1) it 😭), otherwise there's no way to get the names of the functions being traced. no names, no trace, no slay.

the uftrace command is made up of a bunch of sub-commands, structured the way git(1) or perf(1) do it. below is a short lil description of each sub-command — for the full tea, go read the respective manual pages. and heads up: the options on this page can be given to any sub-command. 💅

for convenience, if you don't give a sub-command at all, uftrace just acts like you said the live sub-command — which runs record and replay one after the other. see uftrace-live(1) for the options that belong to live. but ngl, if you want more detailed analysis it's genuinely better to use uftrace-record(1) to save your trace data, and then analyze it with the other uftrace commands like uftrace-replay(1), uftrace-report(1), uftrace-info(1), uftrace-dump(1), uftrace-script(1) or uftrace-tui(1). save first, analyze later, that's the main character pipeline. 👑

🌈 SUB-COMMANDS 🌈

  • record — run a given command and save the trace data in a data file or directory.
  • replay — print recorded function trace data with time durations.
  • live — do live tracing. print the 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 that all uftrace subcommands support, periodt:

  • -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 one bumps up a debug level and you can use it at most 3 times.
  • --debug — print debug messages. it's literally the same as -v/--verbose and it exists only for backward compatibility. lowkey legacy behavior, we love her anyway 🫶
  • --debug-domain=DOMAIN[,DOMAIN, ...] — limit the printing of debug messages to those belonging to one of the DOMAINs you specified. available domains are: uftrace, symbol, demangle, filter, fstack, session, kernel, mcount, dynamic, event, script and dwarf. each domain can optionally have its own debug level (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 all the others. give the girl her own volume knob ✨
  • -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 the 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 are listed here for completeness, but bestie, they're only effective with specific subcommands. so don't come for me if they don't do anything in your context.

for more info please see the uftrace-<subcommand> manual pages. and the manual for uftrace-live(1) is special: the live subcommand does record and replay internally, so that one describes most regular options 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

and that's the whole page, bestie!! this one came straight out of the Uftrace User Manuals, dated Sep, 2018, under the title UFTRACE(1). iconic, historic, obsessed. go trace something 💜🦋✨

📦 where this page comes from