Birds Eye View - Performance Profiling

Q: Which profiling tools are used in this guide?

The page uses GPerfTools to collect CPU profiling data and pprof to inspect the output. For graphical views and PDF exports, the page also relies on Graphviz.

Q: How do I profile the entire runtime of a BEV application?

To profile the whole runtime, preload libprofiler.so with LD PRELOAD and set CPUPROFILE to the output filename before running the application. When the application exits normally, GPerfTools writes a profile file that can be analyzed with pprof.

Q: How do I profile only part of the application runtime?

You can profile only a selected runtime window by setting CPUPROFILESIGNAL in addition to CPUPROFILE. This lets you toggle profiling on and off by sending the chosen signal to the running process, which is useful when you only want to capture a specific phase of execution.

Q: What signal-based workflow does the page recommend for partial runtime profiling?

The page shows using CPUPROFILESIGNAL=12 and then sending signal 12 to the process, for example from htop or with killall -12. Sending the same signal again turns profiling off and produces the profile output for that window.

Q: How do I profile a specific section of source code?

Include in your code and wrap the target code with ProfilerStart("output inside.prof") and ProfilerStop(). This method is useful when you want to isolate one function, loop, or processing block instead of profiling the entire program.

⇦ Performance/PC

Home

Performance/NVIDIA_Jetson ⇨

RidgeRun's Birds Eye view has a built-in developer-oriented profiling feature that uses gperftools. This page is a guide to enable and use the built-in profiling feature.

RidgeRun's Birds Eye View (BEV) includes built-in profiling support for developers who need to identify bottlenecks in the BEV pipeline. This page explains how to enable profiling support at build time, install the required GPerfTools utilities, and collect CPU profiles for the whole process runtime, a selected runtime window, or a specific section of source code. Use this guide when you need to understand where BEV spends processing time and when you want actionable profiling output that can be visualized with pprof.

Requirements

To enable RidgeRun's Birds Eye View profiling feature you need:

Birds Eye View compiled with profiling enabled, see How to Get the Code if you don't have the source code yet.
GPerfTools installed on the target platform.

Compile Birds Eye View with Profiling Support

To enable profiling compile the library with the following option:

meson -Dprofiling=enabled ..
ninja

Install GPerfTools

Clone, build and install GPerfTools using the following commands:

git clone https://github.com/gperftools/gperftools
cd gperftools
./autogen.sh
./configure
make
sudo make install

On Debian-based systems, the complementary tools are packaged under the google-perftools package. For graphical output you also need Graphviz installed:

sudo apt-get install google-perftools graphviz

Note that all the tools have the “google-” prefix under debian - the prefix may be missing on other systems (and is also missing in the official documentation).

Profiling

There are three methods to profile Birds Eye View:

Profile the whole process runtime.
Profile part of process runtime.
Profile a section of the source code.

Each of those methods are explained in the sub-sections below.

Profile the whole process runtime

To start profiling set the environment variables LD_PRELOAD: to the to the libprofiler.so usually located at /usr/local/lib/ and CPUPROFILE: to the name of the output log file. For example:
```
LD_PRELOAD=/usr/local/lib/libprofiler.so CPUPROFILE=test.prof ./path/to/bin
```
Keep the application open or running until it finishes, in this mode if the execution is canceled, for example with Ctrl+C, the output file will not be generated.
Once the application concludes its execution, the file test.prof will contain the CPU profile information. To get a graphical output run:
```
pprof -gv ./path/to/bin test.prof
```
You can also view the profiling result with a web browser by running:
```
pprof --web ./path/to/bin test.prof
```
To generate a PDF report with the previous graphic output run:
```
pprof --pdf ./path/to/bin test.prof > output.pdf
```

Fig. 1 provides an example of the expected output from the process profiling.

Profile part of process runtime

In addition to defining the environment variable CPUPROFILE you can also define CPUPROFILESIGNAL. This allows profiling to be controlled via the signal number that you specify. The signal number must be unused by the program under normal operation. Internally it acts as a switch, triggered by the signal, which is off by default.

To start profiling run:

LD_PRELOAD=/usr/local/lib/libprofiler.so CPUPROFILE=test.prof CPUPROFILESIGNAL=12 ./path/to/bin

Leave the program running until you want to start the profiling process. Then you can use the htop program to send the signal to the desired process as shown in Fig. 2. Alternatively, you can use killall command to send the -12 signal
```
killall -12 /path/to/bin
```
Leave the program until the point you want to profile it, then run again:
```
killall -12 /path/to/bin
```
You will notice the following output when the output file was correctly generated:
```
Using signal 12 as cpu profiling switch
PROFILE: interrupts/evictions/bytes = 4773/1826/231936
```
Once the application ended the test.prof.0 file contains the CPU profile information. To get a graphical output run:
```
pprof -gv ./path/to/bin test.prof
```

Profile specific section of source code

Add the header file in your code:
```
#include <gperftools/profiler.h>
```

Add the following functions calls around the code you want to profile:


ProfilerStart("output_inside.prof"); //Start profiling section and save to file

/* 
* Code to be analyzed
*/

ProfilerStop(); //End profiling section

Run the test application, where you will an output similar to the following:

fsolano@ridgerun-laptop:build$ ./test
PROFILE: interrupts/evictions/bytes = 9/0/280
PROFILE: interrupts/evictions/bytes = 7/0/584
PROFILE: interrupts/evictions/bytes = 12/0/872
PROFILE: interrupts/evictions/bytes = 9/0/712
PROFILE: interrupts/evictions/bytes = 9/0/904
PROFILE: interrupts/evictions/bytes = 7/0/464
PROFILE: interrupts/evictions/bytes = 8/0/680

With this method you can wait until the application execution ends, or end it with Ctrl+C.
Once the application ended the output_inside.prof file contains the CPU profile information. To get a graphical output run:
```
pprof -gv ./test output_inside.prof
```

FAQ

What is this profiling page for?: This page explains how to profile RidgeRun's Birds Eye View using GPerfTools. It shows how to enable profiling support, generate CPU profile output files, and inspect the results with pprof.
What kind of profiling does Birds Eye View support on this page?: This guide focuses on CPU profiling using GPerfTools. It covers three modes: profiling the whole process runtime, profiling only part of the process runtime, and profiling a specific section of source code.
What do I need before I can profile Birds Eye View?: You need a build of Birds Eye View compiled with profiling enabled and GPerfTools installed on the target platform. The page also notes that Graphviz is needed if you want graphical profiling output from pprof.
How do I enable profiling support when building Birds Eye View?: Compile Birds Eye View with profiling enabled by configuring the build with meson -Dprofiling=enabled .. and then building with ninja.
Which profiling tools are used in this guide?: The page uses GPerfTools to collect CPU profiling data and pprof to inspect the output. For graphical views and PDF exports, the page also relies on Graphviz.
How do I profile the entire runtime of a BEV application?: To profile the whole runtime, preload libprofiler.so with LD_PRELOAD and set CPUPROFILE to the output filename before running the application. When the application exits normally, GPerfTools writes a profile file that can be analyzed with pprof.
Why is no profile generated if I stop the application with Ctrl+C during whole-process profiling?: In the whole-runtime method described on the page, the output file is generated when the application finishes normally. If the execution is interrupted early, such as with Ctrl+C, the profiling output may not be written.
How do I profile only part of the application runtime?: You can profile only a selected runtime window by setting CPUPROFILESIGNAL in addition to CPUPROFILE. This lets you toggle profiling on and off by sending the chosen signal to the running process, which is useful when you only want to capture a specific phase of execution.
What signal-based workflow does the page recommend for partial runtime profiling?: The page shows using CPUPROFILESIGNAL=12 and then sending signal 12 to the process, for example from htop or with killall -12. Sending the same signal again turns profiling off and produces the profile output for that window.
How do I profile a specific section of source code?: Include <gperftools/profiler.h> in your code and wrap the target code with ProfilerStart("output_inside.prof") and ProfilerStop(). This method is useful when you want to isolate one function, loop, or processing block instead of profiling the entire program.
How do I view the profiling results?: Once a profile file is generated, you can inspect it with pprof. The page shows examples such as pprof -gv ./path/to/bin test.prof for a graphical view, pprof --web ./path/to/bin test.prof for a browser-based view, and pprof --pdf ./path/to/bin test.prof > output.pdf for a PDF report.
When should I use each profiling method?: Use whole-process profiling when you want a broad view of total runtime cost, partial runtime profiling when you want to isolate one stage of a long-running application, and source-code section profiling when you want the most precise analysis of a specific BEV code path or custom integration block.
Where should I go after identifying a performance bottleneck?: After finding a bottleneck, you can compare behavior with the platform-specific benchmark pages such as Birds Eye View/Performance/PC, Birds Eye View/Performance/NVIDIA Jetson, and Birds Eye View/Performance/NXP iMX8. For pipeline and product integration guidance, review the relevant BEV GStreamer pages or contact RidgeRun through Birds Eye View/Contact us.