Home

Overview

uftrace is a tool to trace and analyze execution of a program written in C/C++. It was inspired by Linux kernel's ftrace (especially function graph tracer), and supports userspace programs on Linux. In order to use uftrace, the program should be compiled with -pg or -finstrument-functions option. (On ARM platforms, you may need to add -fno-omit-frame-pointer option also). The example output looks like below:

$ cat hello.c
#include <stdio.h>
int main(void)
{
   return printf("%s world\n", "Hello");
}

$ gcc -pg -o hello hello.c

$ uftrace ./hello
Hello world
# DURATION    TID     FUNCTION
            [ 7516] | main() {
 414.023 us [ 7516] |   printf();
 697.310 us [ 7516] | } /* main */

In the above example, uftrace ran the hello program (it printed "Hello world") and showed the execution replay with duration and tid. As you can see, the uftrace replay output resembles the original source code. In addition, uftrace provides useful commands and features to analyze behavior of your program.

Quick install

The uftrace has some optional dependencies but it can be built without any of them. If you have git installed, below command will download and build it from the source:

$ git clone https://github.com/namhyung/uftrace.git
$ cd uftrace

$ sudo misc/install-deps.sh    # optional for advanced features
$ ./configure                  # --prefix can be used to change install dir
$ make
$ sudo make install

For more information, please refer INSTALL.md page.

Tutorials

• Tutorial in this wiki
• CppCon 2016 lighting talk - presented by Honggyu Kim
• Tracing Summit 2016 presentation - presented by Namhyung Kim
• CppCon 2017 presentation - presented by Honggyu Kim
• Open Source Summit Europe 2017 tutorial - presented by Taeung Song
• Open Source Summit North America 2017 presentation - by Namhyung Kim
• Tracing Summit 2019 presentation - presented by Namhyung Kim
• Black Hat Asia 2023 Arsenal - presented by Honggyu Kim

Man pages

• uftrace - uftrace overview
• uftrace record - run and save result
• uftrace replay - show execution flow
• uftrace report - analyze execution result
• uftrace live - run and show execution flow
• uftrace info - show process metadata
• uftrace dump - show and convert raw result
• uftrace recv - save result through network
• uftrace graph - show function call graph
• uftrace script - run a script for recorded function trace
• uftrace tui - interactive Text-base User Interface