Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 15. Creating uprobes with perf

Uprobes (user-space probes) are dynamic instrumentation mechanisms that monitor specific points in user-space applications at runtime, without requiring changes to the source code or recompilation.

There are two primary use cases where uprobes are useful:

Debugging and performance analysis
Uprobes function similarly to watchpoints. You can insert them at specific locations in your application to count how often those code paths are executed. Additionally, they can capture rich context such as call stacks or variable values, making them useful for identifying performance bottlenecks or tracking down bugs.
Event-based data collection
Uprobes act as switching events for mechanisms such as circular buffers, helping control when data is recorded or flushed based on execution triggers in user space.

Uprobes integrate seamlessly with perf, which can both consume existing uprobes and create new ones. This flexibility allows for powerful, non-intrusive observability and profiling of user-space behavior alongside kernel-space instrumentation (via kprobes).

You can use the perf tool to create dynamic tracepoints at arbitrary points in a process or application. These tracepoints can then be used in conjunction with other perf tools such as perf stat and perf record to better understand the process or applications behavior.

Prerequisites

  • You have the perf user space tool installed. For more information, see Installing perf.

Procedure

  • Create the uprobe in the process or application you are interested in monitoring at a location of interest within the process or application: 

    # perf probe -x /path/to/executable -a function

Added new event:
  probe_executable:function   (on function in /path/to/executable)

You can now use it in all perf tools, such as:
    perf record -e probe_executable:function -aR sleep 1
    Copy to Clipboard Toggle word wrap

You can use the tracepoints conjunction with other perf tools such as perf stat and perf record to better understand the process or applications behavior.

Prerequisites

  • You have the perf user space tool installed. For more information, see Installing perf.

  • You have received the debugging symbols for your executable: 

    # objdump -t ./your_executable | head
    Copy to Clipboard Toggle word wrap
    Note

    To do this, the debuginfo package of the executable must be installed or, if the executable is a locally developed application, the application must be compiled with debugging information, the -g option in GCC.

Procedure

  1. View the function lines where you can place a uprobe: 

    $ perf probe -x ./your_executable -L main
    Copy to Clipboard Toggle word wrap

  2. Output of this command looks similar to: 

    <main@/home/user/my_executable:0>
              0  int main(int argc, const char *argv) 1 { int err; const char *cmd; char sbuf[STRERR_BUFSIZE]; / libsubcmd init */
              7         exec_cmd_init("perf", PREFIX, PERF_EXEC_PATH, EXEC_PATH_ENVIRONMENT);
8         pager_init(PERF_PAGER_ENVIRONMENT);
    Copy to Clipboard Toggle word wrap

  3. Create the uprobe for the desired function line: 

    # perf probe -x ./my_executable main:8
Added new event:
          probe_my_executable:main_L8   (on main:8 in /home/user/my_executable)

you can now use it in all perf tools, such as:

Perf record -e probe_my_executable:main_L8 -aR sleep 1
    Copy to Clipboard Toggle word wrap

A common method to analyze data collected with uprobes is to run the perf script command, which reads the perf.data file and displays a detailed trace of the recorded workload.

In the perf script example output
  • A uprobe is added to the function isprime() in a program called my_prog

  • a is a function argument added to the uprobe. Alternatively, a could be an arbitrary variable visible in the code scope of where you add your uprobe: 

    # perf script
    my_prog  1367 [007] 10802159.906593: probe_my_prog:isprime: (400551) a=2
    my_prog  1367 [007] 10802159.906623: probe_my_prog:isprime: (400551) a=3
    my_prog  1367 [007] 10802159.906625: probe_my_prog:isprime: (400551) a=4
    my_prog  1367 [007] 10802159.906627: probe_my_prog:isprime: (400551) a=5
    my_prog  1367 [007] 10802159.906629: probe_my_prog:isprime: (400551) a=6
    my_prog  1367 [007] 10802159.906631: probe_my_prog:isprime: (400551) a=7
    my_prog  1367 [007] 10802159.906633: probe_my_prog:isprime: (400551) a=13
    my_prog  1367 [007] 10802159.906635: probe_my_prog:isprime: (400551) a=17
    my_prog  1367 [007] 10802159.906637: probe_my_prog:isprime: (400551) a=19
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat