Read gprofng Experiments with gp-display-text

gp-display-text turns a gprofng experiment directory into a short, readable performance report instead of a folder of binary data you cannot eyeball. It comes from the installed GNU binutils 2.42 tools, and this guide takes about 15 minutes once you already have an experiment directory. It does not collect new samples or change the experiment.

You will print an overview, narrow it to the functions or source lines worth investigating, inspect one function and its callers, and compare two experiments without misreading the numbers.

1. Check the installed command

gp-display-text is the short command name for the gprofng text display tool. The documented interface is gprofng display text, and it accepts one or more experiment directories. Architecture-prefixed names in the package point to the same tool family; use whichever is present on your host.

$ command -v gp-display-text
/usr/bin/gp-display-text
$ gp-display-text --version
GNU x86_64-linux-gnu-gp-display-text binutils version 2.42
$ dpkg-query -W -f='${Package} ${Version}\n' binutils-common binutils-x86-64-linux-gnu
binutils-common 2.42-4ubuntu2.10
binutils-x86-64-linux-gnu 2.42-4ubuntu2.10

Exact package revisions vary between hosts. Record the version with the report when the investigation needs to be reproducible. The manpage installed here is dated 9 February 2026 and describes the common command set; the upstream gprofng manual documents additional commands.

2. Print an overview from an experiment

Replace /path/to/experiment.er with the directory created by gprofng collect app. Remember it is an input directory, not a single profile data file. Start with -overview, which summarises the recorded performance data.

$ gp-display-text -overview /path/to/experiment.er

A valid experiment produces a text report containing its recorded performance information. The exact headings and metric values depend on how the experiment was collected. If you get an error about opening or reading the experiment, check the path and permissions first:

$ test -d /path/to/experiment.er && echo 'experiment directory found'
$ find /path/to/experiment.er -maxdepth 1 -type f -printf '%f\n' | head

3. Start with functions, then limit the noise

• List functions. -functions lists executed functions with the active metrics, such as CPU time.
• Cap the output. Add -limit when a large report would distract you, for example -limit 25.
• Mind the order. Commands run left to right, so put the limit after the view you want it to affect, and test the order when combining several commands.

$ gp-display-text -functions -limit 25 /path/to/experiment.er

The result is a function list capped at 25 lines in the tool's output. A line limit is a display limit, not a reduction of the recorded experiment: remove it when you need the complete list.

To inspect source lines instead, use -lines. To see program counters, use -pcs. Both views are ordered by the current sort metric, so a surprising top result may reflect the sort rather than a different set of samples.

$ gp-display-text -lines -limit 40 /path/to/experiment.er
$ gp-display-text -pcs -limit 40 /path/to/experiment.er

4. Inspect one function and its callers

• Read the source. -source FUNCTION gives annotated source for a matching function name.
• See the instructions too. -disasm FUNCTION mixes source with the function's disassembly.
• Summarise one function. -fsingle FUNCTION gives a function summary; add -callers-callees for caller and callee relationships.

$ gp-display-text -functions -source my_func /path/to/experiment.er
$ gp-display-text -fsingle my_func -callers-callees /path/to/experiment.er

If several functions share a name, -fsingle accepts an optional numeric selector. Do not guess that number: use the function view first to find the relevant entry, then rerun the focused report. For a broad relationship view, -calltree shows the dynamic call graph with hierarchical metrics.

Function names can be displayed in short, long or mangled form with -name short, -name long or -name mangled. The optional soname or nosoname suffix controls whether the load object's name is included; keep the colon tight, for example -name long:soname.

5. Make metrics and sorting explicit

Default metrics are convenient for a first look, but they are not the whole experiment. Run -metric_list to see the selected metrics and the metrics available in the data. Then use -metrics with a colon-separated specification, or restore the default selection with -metrics default.

$ gp-display-text -metric_list /path/to/experiment.er
$ gp-display-text -metrics 'e.totalcpu:name' -functions /path/to/experiment.er
$ gp-display-text -metrics default -functions /path/to/experiment.er

Precise metric names depend on the recorded experiment. Do not copy a metric from another machine without checking -metric_list first. If hardware counters were recorded, the special hwc metric expands to the active hardware event counters; CPI and IPC are available only when the required instructions and clock cycles were measured.

Use -sort METRIC to choose the ordering. Prefix a metric definition with a minus sign for reverse order, such as -sort -e.totalcpu. The sort setting persists within the display session, and -sort default restores the command's default sort.

6. Compare two experiments safely

With multiple experiment directories, gprofng aggregates results by default. Add -compare on to keep values separate for supported views. The first experiment is the reference: -compare delta reports later experiments relative to it, while -compare ratio reports later values divided by the reference.

$ gp-display-text -compare delta -functions baseline.er candidate.er
$ gp-display-text -compare ratio -functions baseline.er candidate.er

These modes are easy to misread. Keep the reference first, use the same collection conditions where possible, and label the output with the experiment names. A ratio is not a percentage unless you convert it yourself. Use -compare off to return to aggregation.

There is no destructive action in these display commands: they read the experiment directories and write the report to standard output. If you redirect to a file, use a new name when the old report matters:

$ gp-display-text -overview /path/to/experiment.er > report.txt
$ test -s report.txt && echo 'report written'

Shell redirection truncates an existing report.txt before the tool runs. If that file is valuable, copy it first or redirect to report.txt.new and rename it only after checking the result. Remove an unwanted temporary report with your normal file-management process; the experiment remains untouched.

7. Save a repeatable report script

A script file holds display commands without the leading dash. This is useful when you want the same view for several experiments, or need a reviewable report recipe.

$ cat > /tmp/gprofng-report.txt <<'EOF'
overview
metrics default
sort -e.totalcpu
functions
limit 25
EOF
$ gp-display-text -script /tmp/gprofng-report.txt /path/to/experiment.er

The heredoc creates a temporary local file; it does not alter the experiment. In a permanent workflow, store the script alongside your analysis notes and review it as ordinary configuration. Order still matters: later commands can change the state used by later output, so move limit 25 after the view it should affect when you need an unambiguous recipe.

For an interactive session, invoke the tool without options, commands or a script. It enters interpreter mode: type commands without the leading dash and finish with exit. Useful for exploring an unfamiliar experiment, but a script is easier to rerun and audit.