Profile a Linux Program with gp-collect-app

Your app is slow somewhere in the code, and gp-collect-app can record exactly where before you touch a single line. By the end you will have a gprofng experiment directory containing a bounded performance recording, and you will have checked its header without opening a graphical tool. The command is installed here as GNU binutils 2.42, from the Ubuntu packages binutils-common, binutils-aarch64-linux-gnu and binutils-x86-64-linux-gnu. The unprefixed command is gp-collect-app; the architecture-prefixed names are aliases for the same collector interface.

Allow about five minutes for a first run. You need an ELF executable that you can run, enough disk space for the experiment, and permission to observe that process. Ordinary user programs normally need no elevated privileges. Do not use sudo as a first fix: it can change the environment and the program being measured.

1. Confirm the collector

Check the installed version and the command syntax:

gp-collect-app --version
gp-collect-app --help

The synopsis is gprofng collect app [option(s)] target [target-option(s)]. Options belong before the target. Arguments after the target are passed to that target, so put an option such as -t before the executable. The prefixed form can be useful in a cross-toolchain directory:

x86_64-linux-gnu-gp-collect-app --version
aarch64-linux-gnu-gp-collect-app --version

On this installation the output identifies gprofng binutils version 2.42. The package version is 2.42-4ubuntu2.10. If your output differs, keep the local help and manpage beside your notes because defaults can change between releases.

2. Perform a dry run

Ask the collector to display its resolved settings without starting the program or collecting data:

gp-collect-app -n -o /tmp/example.er /path/to/your-program --your-argument

Replace both placeholders. The output should include the target, the experiment name, clock profiling, descendant-process handling and the command line. It should not run the target. In a local check, -n returned status 0 and printed the resolved collection parameters for /bin/true.

The -o name must end in .er. It may be an absolute path, which makes /tmp convenient for a disposable trial. With -o, an existing experiment is not overwritten. That refusal is useful: it stops a typo destroying an earlier recording.

3. Collect a bounded experiment

Run the target for a known interval and write the result to a new experiment directory:

gp-collect-app -t 10s -o /tmp/example.er /path/to/your-program --your-argument

-t accepts seconds by default, or an explicit m or s. A single value records from the start until that time. A range such as 5-20s records between those times, while a range ending in zero, such as 5-0s, continues until the target exits. For repeatable troubleshooting, prefer a short explicit interval or a target that naturally terminates.

For a harmless smoke test on this machine, the following command completed successfully and produced an experiment directory with files including overview, profile, map.xml and warnings.xml:

gp-collect-app -t 1s -o /tmp/gp-collect-app-guide.er /bin/sleep 1
test -d /tmp/gp-collect-app-guide.er && echo "experiment created"

Do not expect a useful profile from a program that exits before the sampling window. For a server, start the collector before sending representative requests, then stop the server or let the chosen interval expire.

4. Choose what to record

Clock profiling is enabled by default with -p on. You can disable it with -p off, or select the low, high or a millisecond sampling granularity with -p low, -p high or a numeric value. More frequent sampling can add overhead and produce larger data, so change it for a reason and record the setting with the experiment.

Descendant processes are followed by default, equivalent to -F on. Use -F off when worker processes would obscure the target, or -F '=regex' to follow descendants whose executable basename matches a regular expression. Quote that value when the shell could interpret its characters:

gp-collect-app -F '=worker-[0-9]+' -t 30s -o /tmp/workers.er /path/to/launcher

Archiving is enabled for load objects by default, equivalent to -a ldobjects. This stores material needed to interpret the recording later. The choices include off, on, src, usedldobjects and usedsrc. Source archiving can increase the experiment size and may copy source files into the result, so select it deliberately.

Use hardware counters with -h followed by the counter definition or definitions. First ask the installed collector what this host supports:

gp-collect-app -h

On the checked host this reported that hardware counter profiling is not supported. That is a host capability result, not evidence that the command syntax is wrong. If counters are unavailable, use clock profiling and the tracing options instead.

5. Use signals and tracing deliberately

Use -y SIGUSR1,r when collection should begin immediately but later be paused and resumed with a signal. Without the r, collection begins paused. For example:

gp-collect-app -y SIGUSR1,r -t 60s -o /tmp/service.er /path/to/service

Send only signals that the target documents as safe. The manpage recommends SIGUSR1 or SIGUSR2, but the signal must not already have a meaning in the application. The -l option uses a signal to request a process-wide resource sample. If you use both options, choose different signals.

Java profiling is on by default with -j on; use -j off for a native-only target, or give a JVM path. -J passes extra JVM options and implies Java profiling. Synchronisation tracing is off by default with -s off; heap tracing and I/O tracing are also off, enabled with -H on and -i on. These options can increase overhead, so enable one at a time when isolating a problem.

6. Inspect and recover

Read the experiment header after collection:

gprofng display text -header /tmp/example.er

A successful header report identifies the target, collector version, host, collection duration and active parameters. The smoke-test report showed Experiment: /tmp/gp-collect-app-guide.er, No errors and a one-second data-collection duration. Warnings about a short run or variable clock frequency are diagnostic information, not a guarantee that the profile is accurate enough for a performance decision.

If the target fails, read its own exit output first. If the experiment name already exists, choose a new name.

test -d /tmp/example.er && echo "refusing to overwrite: inspect this experiment first"
gp-collect-app -O /tmp/example.er /path/to/your-program

The first command is a guard for a script, but it does not make the second command safe by itself. If an overwrite goes wrong, the collector has no undo operation; restore the experiment from your backup or rerun the measurement. Treat experiment directories as data, not as disposable cache, until you have exported the findings you need.