Profile a Linux program with gprofng and read the result

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 accepts 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 the name available for 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 is a useful 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 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 vary. A zero exit status and a new directory ending in .er are the useful results. The directory is a bundle of profiling data, not a single report file. If you use a real program, replace /bin/sleep 1 with its path and arguments, keeping the target arguments after the target name.

The default clock profiling is enabled. The collector can also use hardware counters and tracing, but those are separate measurements with their own overhead and host support requirements. Begin with the default collection so that a surprising result is not mixed with several untested settings.

3. Avoid overwriting an experiment

-o refuses to overwrite an existing experiment with the same name. That is the safer option 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. 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 you are 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 warns about 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 are processed from left to right, so their 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 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. The program may finish before that duration. Do not interpret a longer recording as automatically better: it increases data volume and can alter a workload whose timing or resource use matters.

To inspect source or disassembly, the target needs usable symbol and source information. A stripped binary can still be measured, but the report may be less descriptive. Build symbols and source paths according to 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 intend 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 displays run-time settings but does not run the target or collect data. Use it to catch argument placement and configuration issues. It does not prove that the target will complete successfully under normal collection.

If the 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, and then add one measurement change at a time.