Read gprofng experiments as focused plain-text reports

You will turn a gprofng experiment directory into a small, readable performance report, then narrow it to the functions or source lines worth investigating. This guide uses the installed GNU binutils 2.42 tools and takes about 15 minutes once you have an experiment directory. It does not collect new samples or change the experiment.

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 the command accepts one or more experiment directories. The architecture-prefixed names in the package point to the same tool family; use the name that 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. Record the version with the report when you need a reproducible investigation. 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. The experiment is an input directory, not a single profile data file. Start with -overview, which asks for a summary of the recorded performance data.

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

A valid experiment should produce 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

Do not run this as root merely because the data was collected by another user. Grant the inspecting account read access, or copy the experiment to a directory it can read. Avoid changing ownership of a profiling archive without checking the implications for other users.

3. Start with functions, then limit the noise

The -functions command lists executed functions with the active metrics, such as CPU time. Add -limit when a large report would distract you. Commands are processed from 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 according to the tool's output. A line limit is a display limit, not a reduction of the recorded experiment. Remove it when you need to examine the complete list.

To inspect source lines instead, use -lines. To see program counters, use -pcs. These 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

Use -source FUNCTION for annotated source, or -disasm FUNCTION for source mixed with the function's instructions. The function name must match a name in the experiment. The manpage also provides -fsingle FUNCTION for a function summary and -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. First use the function view to find the relevant entry, then rerun the focused report. For a broad relationship view, -calltree displays 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

The precise metric names depend on the recorded experiment. Do not copy a metric from another machine without checking -metric_list. 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 is persistent 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 when that is what you intend.

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 contains 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. The order remains significant: later commands can change the state used by later output. If you put limit 25 before a view, move it after the view 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 command-line dash and finish with exit. This is useful for exploring an unfamiliar experiment, but a script is easier to rerun and audit.