Generate browsable gprofng HTML reports with gp-display-html

You will turn an existing gprofng experiment directory into a directory of HTML files, with index.html as the entry point. Allow about ten minutes if the experiment already exists. This guide uses the installed GNU binutils 2.42 command from package version 2.42-4ubuntu2.10.

The command is a report generator, not a profiler. You need a readable experiment directory, normally ending in .er, created by gprofng collect app or another compatible gprofng workflow. You do not need root privileges to read an experiment and write the report in a directory you own.

1. Check the installed interface

Start by checking the command that will actually run and its option syntax:

$ command -v gp-display-html
/usr/bin/gp-display-html
$ gp-display-html --version
GNU binutils version 2.42
$ gp-display-html --help
Usage: gprofng display html [OPTION(S)] EXPERIMENT(S)

The manpage aliases aarch64-linux-gnu-gp-display-html and x86_64-linux-gnu-gp-display-html describe the same tool, but an alias name is not necessarily installed as an executable. Use the command found by command -v.

Checkpoint: gp-display-html --help should return usage information. The synopsis accepts one or more experiment directories after the options.

2. Generate the report in a new directory

Give the output directory an explicit name so that a script or a later browser bookmark does not depend on the automatic numbering:

$ gp-display-html --output=/path/to/report.html /path/to/profile.er
$ test -f /path/to/report.html/index.html && printf '%s\n' 'report ready'
report ready

The value of --output is a directory name, despite the default naming pattern ending in .html. The tool creates that directory and writes the report files inside it. The input can be one experiment or several experiment directories:

$ gp-display-html --output=/path/to/combined-report.html /path/to/profile-1.er /path/to/profile-2.er

With no output option, the default is display.<n>.html, where <n> is the first positive number not already used in the current directory. A normal --output run refuses an existing directory rather than overwriting it. This is useful protection when reports are valuable.

3. Treat overwrite as a destructive operation

$ test ! -e /path/to/report.html && printf '%s\n' 'destination does not exist'
$ gp-display-html --overwrite=/path/to/report.html /path/to/profile.er

The command documentation does not provide an undo operation. Preserve a report by choosing a new destination, or copy the existing directory with your normal file backup tool before overwriting it. If an overwrite was accidental, restore that backup rather than trying to reconstruct the generated HTML manually.

4. Set highlighting only when the default is wrong

Source lines and instructions near the highest metric values are colour-coded using a default threshold of 90 per cent. Change it with the long option and an equals sign:

$ gp-display-html --highlight-percentage=75 --output=/path/to/report-75.html /path/to/profile.er
$ test -f /path/to/report-75.html/index.html && printf '%s\n' 'highlighted report ready'

The accepted range is 0 to 100. A value of zero disables this highlighting feature. This setting changes how the report selects and marks hot source lines and instructions; it does not change the collected profile data. Option names and values are case-sensitive.

5. Keep diagnostics useful while testing

Leave normal diagnostics enabled for the first run. Add --verbose when you need processing messages, or --debug=m when troubleshooting and a larger diagnostic volume is useful:

$ gp-display-html --verbose --output=/path/to/report-debug.html /path/to/profile.er
$ gp-display-html --debug=m --output=/path/to/report-debug.html /path/to/profile.er

Debug sizes are s, S, m, M, l, L, xl and XL. The manual says that l and xl are currently equivalent, but that may change. Use --nowarnings to suppress warnings on standard output, or --quiet when a script should receive no ordinary messages. Quiet mode still reports errors, and it ignores verbose and debug output.

Warnings are also made available through the report's main index.html page. The tool may accumulate warnings before displaying them, so a quiet terminal is not proof that the report contains no warnings.

6. Check this installed package before relying on automation

On this machine, a temporary experiment collected with gprofng collect app was passed to the installed command. The command failed before creating index.html with:

Undefined subroutine &bigint::hex called at /usr/bin/gp-display-html line 4059, <MAP_XML> line 1.

This is an observed failure of binutils 2.42-4ubuntu2.10, not a documented report result. Do not treat a non-zero exit status as a generated report, and do not open a partially created directory as if it were complete. Capture the version, command and error for your package maintainer or compare the installed package with a newer binutils build after checking your distribution's update process. The sourceware documentation describes the same basic workflow, but it does not remove this local package-specific test.

For a repeatable check, use a temporary destination and test for the entry file:

set -eu
report_dir=/tmp/gprofng-html-check.html
gp-display-html --quiet --output="$report_dir" /path/to/profile.er
test -s "$report_dir/index.html"
printf '%s\n' 'HTML report exists'

Do not add sudo to this check unless the experiment itself is unreadable because of file permissions. Elevated privileges will not repair a program error such as the one above, and they can create output owned by root that your normal account cannot update.