This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.

Linux Perf Profiler Support in Native Image

The perf profiler is a performance analysis tool in Linux that enables you to collect and analyze various performance-related data such as CPU utilization, memory usage, and more. It is particularly useful for profiling and understanding the behavior of applications.

Installation #

Perf is a profiler tool for Linux systems. Most distributions come with perf pre-installed, but you can install it using your package manager if it is not available.

To install perf on Oracle Linux/Red Hat/CentOS, run this command:

sudo yum install perf

To install perf on Debian/Ubuntu, run the following commands one by one:

sudo apt update
sudo apt install linux-tools-common linux-tools-generic

After installing perf, backup the default values of the following options:

cat /proc/sys/kernel/perf_event_paranoid > perf_event_paranoid.backup
cat /proc/sys/kernel/kptr_restrict > kptr_restrict.backup

Then set them to the new desired values:

echo -1 > /proc/sys/kernel/perf_event_paranoid
echo 0 > /proc/sys/kernel/kptr_restrict

In the example above, -1 and 0 are used as values, which are the least restrictive, so it is not recommended to use them in production code. You can customize these values according to your needs.

perf_event_paranoid has four different levels (values):

-1: Allow use of (almost) all events by all users.
>=0: Disallow ftrace function tracepoint by users without CAP_SYS_ADMIN.
>=1: Disallow CPU event access by users without CAP_SYS_ADMIN.
>=2: Disallow kernel profiling by users without CAP_SYS_ADMIN.

kptr_restrict has three different levels (values):

0: Kernel pointers are readable by all users.
1: Kernel pointers are only accessible to privileged users (those with the CAP_SYS_ADMIN capability).
2: Kernel pointers are hidden from all users.

Once finished using perf, restore the original values:

cat perf_event_paranoid.backup > /proc/sys/kernel/perf_event_paranoid
cat kptr_restrict.backup > /proc/sys/kernel/kptr_restrict

Building Native Executables #

The following command assumes that native-image is on the system path and available. If it is not installed, refer to the Getting Started.

native-image -g <entry_class>

The -g option instructs Native Image to produce debug information for the generated binary. perf can use this debug information, for example, to provide proper names for types and methods in traces.

Basic Operations #

CPU Profiling #

List all available events:
```
perf list
```
This command displays a list of all available events that you can use for profiling.
Record CPU events:
```
perf record -e <event> -o perf.data <your_executable>
```
Replace <event> with the desired event from the list. This command profiles your executable and save the data to a file named perf.data.
Generate a report:
```
perf report
```
This command generates a report based on the collected data. You can use various options to customize the output.

Memory Profiling #

Record memory events:
```
perf record -e memory:<event> -o perf.data <your_executable>
```
Replace <event> with a specific memory event. This command profiles memory-related events.
Generate a memory report:
```
perf report --sort=dso
```
This command generates a report focused on memory-related events, sorted by dynamic shared object (DSO).

Tracing #

Record system-wide traces:
```
sudo perf record -a -g -o perf.data
```
This command records system-wide traces, including call-graph information, and saves the data to a file named perf.data. Use sudo for system-wide tracing.
Generate a trace report:
```
perf script
```
This command generates a script that can be used for analyzing the recorded trace data.