Profile a Linux Program with gprofng

gprofng is the newer Binutils profiler, built to replace gprof without needing the target rebuilt with -pg. You will finish with a repeatable command-line workflow for collecting a gprofng experiment and reading a plain-text report from it. The examples use the installed GNU binutils 2.42 package, specifically version 2.42-4ubuntu2.10 on this machine. Allow about fifteen minutes for a first run. You need a shell, an executable you are allowed to run, and enough free space for the experiment directory.

Profiling normally needs no elevated privileges when you own the program and can write the destination directory. Do not start with sudo: it can change the environment, hide permission problems and create root-owned experiment data. Hardware event access and a protected target may need separate operating-system permissions, but that is a host policy question, not a reason to make every profiling command privileged.

1. Check the installed driver

The driver is the stable entry point. It takes an action, sometimes a qualifier, then the target and any arguments for that target. The three installed names, gprofng, aarch64-linux-gnu-gprofng and x86_64-linux-gnu-gprofng, are the same family of driver: use whichever name is available on your host.

$ command -v gprofng
/usr/bin/gprofng
$ gprofng --version
GNU x86_64-linux-gnu-gprofng binutils version 2.42
$ gprofng --help
Usage: x86_64-linux-gnu-gprofng [OPTION(S)] COMMAND [KEYWORD] [ARGUMENTS]

The installed help doubles as a version check. The local gprofng(1) page documents the common --version and --help options, while this executable also reports options such as --check and --verbose. For action-specific options, ask the action itself for help:

$ gprofng collect app --help
Usage: gprofng collect app [OPTION(S)] TARGET [TARGET_ARGUMENTS]
$ gprofng display text --help
Usage: gprofng display text [OPTION(S)] [COMMAND(S)] [-script <script_file>] EXPERIMENT(S)

2. Run a harmless collection first

Use collect app to record the target while it runs. The -o option names the experiment directory, and the target comes after gprofng's own options. This command profiles a short-lived system utility and writes only under /tmp:

$ gprofng collect app -o /tmp/gprofng-check.er /bin/sleep 1
Creating experiment directory /tmp/gprofng-check.er (Process ID: 12345) ...

The process ID and timing text will vary. A zero exit status and a new directory ending in .er are the results that matter. The directory is a bundle of profiling data, not a single report file. For a real program, replace /bin/sleep 1 with its path and arguments, keeping the target arguments after the target name.

Default clock profiling is enabled out of the box. The collector can also use hardware counters and tracing, but those are separate measurements with their own overhead and host support requirements. Start with the default collection, so a surprising result is not tangled up with several untested settings at once.

3. Avoid overwriting an experiment

-o refuses to overwrite an existing experiment with the same name, which is the safer choice for scripts and repeated investigations. Choose a new name when comparing runs:

$ gprofng collect app -o /tmp/my-program-run-01.er /path/to/program PROGRAM_ARGUMENT
$ test -d /tmp/my-program-run-01.er && echo 'experiment created'
experiment created

Replace both placeholders with values that exist on your machine, and quote arguments containing spaces. If the target itself begins with a dash, use an absolute or relative path such as ./-worker so it is unambiguous.

4. Inspect the experiment as text

display text accepts display commands before the experiment name. -header shows collection details and -functions shows the functions seen by the collector. Limit the output when exploring a large run:

$ gprofng display text -header -functions -limit 12 /tmp/gprofng-check.er
Experiment: /tmp/gprofng-check.er
No errors
Target command (64-bit): '/bin/sleep 1'
Collector version: `2.42'; experiment version 12.4 (64-bit)
Functions sorted by metric: Exclusive Total CPU Time
Print limit set to 12

Exact warnings, timing and function rows depend on the kernel, CPU, target and run length. A very short or idle program can produce an empty-looking function list even though collection succeeded. Read the header first: it tells you what was actually recorded and flags conditions such as variable clock frequency.

For an interactive session, omit the display commands and run:

$ gprofng display text /tmp/gprofng-check.er
gprofng> header
gprofng> functions
gprofng> exit

In a script or shell command, prefer explicit commands such as -header and -functions. Display commands run in the order you give them, so that order matters. The installed text viewer also supports a script file with -script when you need a repeatable report.

5. Make a useful run

Once the smoke test works, profile the command that actually matters. Keep the output in a dedicated directory, and use -t when the program is long-running or you want a fixed recording window:

$ gprofng collect app -o /tmp/my-program-run-02.er -t 10s /path/to/program --input /path/to/input
$ gprofng display text -header -functions /tmp/my-program-run-02.er

-t controls the collection duration, with seconds as the default unit and minutes available too. The program may finish before that duration. A longer recording is not automatically better: it just increases data volume, and can alter a workload whose timing or resource use is what you are trying to measure.

To inspect source or disassembly, the target needs usable symbol and source information. A stripped binary can still be measured, but the report will be less descriptive. Build symbols and source paths through your normal build process, then rerun the same workload. The archive setting can preserve load objects and source files, but that increases storage and may capture material you did not mean to distribute.

6. Diagnose failures without guessing

If collection fails, first check the target and destination as the current user:

$ test -x /path/to/program && echo 'target is executable'
$ test -w /tmp && echo 'destination is writable'
$ gprofng collect app -n -o /tmp/dry-run.er /path/to/program
Target: /path/to/program

The -n option performs a dry run: it shows the run-time settings but never runs the target or collects data. Use it to catch argument placement and configuration issues early. It does not prove the target will complete successfully under normal collection.

If a report says the data may be unreliable, note the warning rather than hiding it. Variable clock frequency can affect time and cycle conversions. Hardware counter requests can be unavailable on a particular CPU, or restricted by system policy. Reduce the command to default clock profiling, verify the target independently, then add one measurement change at a time.