GNU gprofng GUI ¶

3.1 Build Requirements ¶

The GUI is a Java application. In order to build it, the javac Java compiler and developer classes are needed. The compiler reads the source files for the GUI and compiles them into bytecode class files.

For this, the java-devel package needs to be installed in order to build and execute the GUI. The minimum Java version required is 8.

If the git repository is used to build and install the GUI, the autoconf and automake tools need to be installed. This is not needed when using the tar file.

3.2 Runtime Requirements ¶

The GUI utilizes the Java Swing framework, and needs the X Window System (‘X11’, or simply ‘X’). It is commonly available for Linux systems, but may not be installed by default. Please make sure that it is installed before using the GUI.

There are two common scenarios regarding accessing a system remotely (e.g. a cloud instance) where the GUI is to be executed:

• If ssh is used to access the remote system, make sure to have the correct access permissions and to set environment variable DISPLAY accordingly.
• If a remote desktop like vnc is used, the GUI can be executed from within this desktop. No additional settings are needed.

Since the GUI uses some of the tools that come with the core part of gprofng, it is necessary to also install this tool. Make sure to include these tools in the search path as set with environment variable PATH.

4.1 Prepare the Build from the Tar File ¶

In general it is recommended to use the most recent version, but there may be a reason to use an older release. This is why various releases of the GUI are available on the GNU ftp site. The files have been compressed and are available in different formats. From this web site, the code may be downloaded directly. Alternatively, the wget command can be used to download the tar file from the command line.

To build the gprofng GUI from a released tar file, get your copy of the tar file first. In the example below we assume that version 1.1 has been selected, but the process is identical for other versions.

Below we show how the wget command can be used to download a specific version. Below this, we show the output for a specific release. For lay-out reasons it has been slightly shortened and modified.

$ wget https://ftp.gnu.org/gnu/gprofng-gui/gprofng-gui-1.1.tar.gz

wget https://ftp.gnu.org/gnu/gprofng-gui/gprofng-gui-1.1.tar.gz
--2024-03-19  https://ftp.gnu.org/gnu/gprofng-gui/gprofng-gui-1.1.tar.gz
       ...
Proxy request sent, awaiting response... 200 OK
Length: 1576556 (1.5M) [application/x-gzip]
Saving to: 'gprofng-gui-1.1.tar.gz'

gprofng-gui-1.1.tar.gz   100%[========================>] 1.50M 2.00MB/s in 0.8s

2024-03-19 (2.00 MB/s) - 'gprofng-gui-1.1.tar.gz' saved [1576556/1576556]

The next step is to unpack the compressed tar file and go into the newly created directory with the name gprofng-gui-1.1. Make sure that the target directory name, gprofng-gui-1.1 in this example, does not exist already. If so, remove it first.

Unpack the tar file:

$ tar xzvf gprofng-gui-1.1.tar.gz

This is sample output from the command:

gprofng-gui-1.1/
gprofng-gui-1.1/compile
gprofng-gui-1.1/ChangeLog
...
gprofng-gui-1.1/gprofng-gui.sh

Next, go into the newly created directory:

$ cd gprofng-gui-1.1

This directory with the name gprofng-gui-1.1 has everything needed to build and install the GUI. See Build and Install from Source how to proceed next.

4.2 Prepare the Build from the Git Repository ¶

The development git repository contains the most recent version of the GUI. If this is used to build and installed the GUI, make sure that the autoconf and automake tools are installed and in the search path.

Before cloning the git repository, make sure that a directory with the name gprofng-gui does not exist. If so, the clone command fails with an error message. The next step is to clone the git repository:

$ git clone https://git.savannah.gnu.org/git/gprofng-gui.git

There should be diagnostic messages similar to what is shown below:

Cloning into 'gprofng-gui'...
remote: Counting objects: 1334, done.
remote: Compressing objects: 100% (605/605), done.
remote: Total 1334 (delta 777), reused 1222 (delta 696)
Receiving objects: 100% (1334/1334), 1.77 MiB | 4.29 MiB/s, done.
Resolving deltas: 100% (777/777), done.

The clone command succeeded and the newly created gprofng-gui directory should be present. The ls command may be used to verify this:

$ ls
gprofng-gui

Go into this directory and execute the autoreconf command:

$ cd gprofng-gui
$ autoreconf -i -f

The output from this command should be similar to this:

configure.ac:18: installing './compile'
configure.ac:17: installing './install-sh'
configure.ac:17: installing './missing'
Makefile.am: installing './INSTALL'

We are now ready to build and install the GUI. See Build and Install from Source how to proceed next.

4.3 Build and Install from Source ¶

Whether the sources originate from a tar file, or a git repository, the steps to build and install the code are the same. They are covered in this section.

By default, the GUI related files are installed in /usr/local, but through the --prefix option, this can be changed.

As a first step, a build location needs to be selected. This is the directory where, among other files, the generated files like the Java classes and jar files will be placed.

Before the code can be built, a configuration step is needed. This is handled by the configure tool that comes with the distribution. This is also where an alternate location for the installation needs to be specified.

In the example below, it is assumed that the current directory is at the same level as where the source directory is located. This is where we create the build directory. It is called build in this example, but any other name may be chosen.

In the next step, the configure tool is used to set up the configuration details. This tool is located in the source directory, but is executed from the build directory.

By default, the necessary files will be installed in /usr/local. In the example the --prefix option is used to change this and set the installation directory to /home/demo/gui-install. This is where the files needed to execute the gprofng display gui command will be installed. Make sure to set the correct permissions such that the installation process is allowed to write to directory /home/demo.

As an example, below it is assumed that a tar file with version 1.1 has been used. The following commands create the build directory and configure the settings:

$ mkdir build
$ cd build
$ ../gprofng-gui-1.1/configure --prefix=/home/demo/gui-install

The command for the git repository is nearly identical. The only difference is that the configure tool is executed from directory gprofng-gui:

$ ../gprofng-gui/configure --prefix=/home/demo/gui-install

The configure command prints messages on the screen, but also produces a config.log file. It is strongly recommended to check this file to make sure the configuration phase was successful. Any error should be resolved and warnings need to be checked. If there are no errors and warnings, the next step is to build the code using the make command.

If the build has been successful, the next thing to do is to use the make install command to install the files. Make sure that the correct write permissions are set on the installation directory, or use the sudo command when executing make install:

$ make
$ make install

The very last steps are to make sure that the bin directory in the installation directory is in the search path as set through the PATH environment variable and to adjust variable MANPATH to include the man page for the GUI. For example /home/demo/gui-install/bin.

$ export PATH=/home/demo/gui-install/bin:$PATH
$ export MANPATH=/home/demo/gui-install/share/man:$MANPATH

To verify that the GUI has been installed successfully, use the following command:

$ gprofng display gui --version

If the installation has been successful, a diagnostic message is printed.

5.1 Start the GUI ¶

The details of the usage information and an overview of the options supported, can be found in the man page for the GUI. For convenience a brief description is provided here. For more details See The gprofng GUI Man Page.

The GUI is invoked through the gprofng display gui command. Among other things, one or more experiments can be included on the command line. All experiments listed will be opened and loaded into the GUI. For example, this command starts the GUI and loads an experiment called experiment_1.er:

$ gprofng display gui experiment_1.er

The GUI main window will be displayed. This includes a summary of the experiments loaded.

Loading multiple experiments is very similar. Simply add the experiments on the command line. By default, the data shown is aggregated across all the experiments that have been loaded, but with the -c option, the GUI starts up in comparison mode. For example, this command loads two experiments in comparison mode, where the first experiment is used as the reference. The data in the second experiment will be shown relative to this reference:

$ gprofng display gui -c experiment_1.er experiment_2.er

Alternatively, the GUI may be started without experiments. This will cause a window to appear that shows previously loaded experiments. If none have been loaded in the past, the list is empty.

Once the GUI is running and one or more experiments have been loaded, it is possible to remove or add experiments from within the GUI. Under the ‘File’ menu, there are entries to manage the experiments. For example to load, or remove, one or more experiments, but also to toggle the mode from aggregation to comparison, and viceversa.

If menu entry ‘Aggregate Experiments …’ is selected, a list with the currently loaded experiments is shown. This list may be modified by adding, or removing experiments. The comparison mode is enabled by selecting ‘Compare Experiments …’. In this menu, the experiments loaded can be modified. The reference experiment may also be changed here.

5.2 The Initial Screen ¶

This is the screen that is shown when the GUI is started. The top bar shows the menus that are available. Below this, there are icons that represent shortcuts to specific features. For example, adding or removing filters is activated by clicking on the funnel icon. Tooltips provide a brief description of each icon.

This is followed by a window with a dashboard overview of the experiment(s) loaded.

The top panel is titled ‘Experiment(s)’, and shows a summary of the experiment(s). By clicking on the little black arrow, more information is displayed.

This info panel is followed by a second panel titled ‘Metrics’ that provides a summary of the metrics collected. This includes the duration of the experiment, or the maximum duration if multiple experiments have been loaded, and the aggregated CPU time. In case hardware events have been collected, the total values will be displayed here too.

The third panel, ‘Metrics Preview’, shows how the metrics will look in the data views.

The metrics that are displayed can also be configured. There is a menu entry called ‘Metrics’ at the top that is a shortcut to one of the settings. If selected, it shows a table with the metrics that should be enabled, or disabled.

The panel on the left hand side lists the various views that are available. For example there is a ‘Functions’ view that provides a function overview, or the ‘Timeline’ to get a color coded execution overview of the application.

This panel also has a very useful entry at the very top. It is titled ‘Views’ and through green colored navigation errors, one can go back and forth between views that have been selected earlier.

It is important to note that by default the list with the views shows a subset of the available views only. By clicking on the last entry (‘More …’), additional views may be enabled, or disabled, by clicking on the checkbox to the left of the view.

The view(s) selected will be added to the list on the left. The (updated) list will be stored transparently as part of the settings for the experiment. In case the settings should be accessible to other experiments, they can be saved in a different location. For this, select ‘Tools’ in the top level menu bar. From there, the ‘Export’ feature can be used to select where the preferences need to be stored. Several choices for the location are supported. Earlier saved preferences may be imported through the ‘Import’ feature.

The initial screen is meant to provide a quick overview and point at the first possible area(s) of interest. From there, further exploration is probably warranted.

7.1 Callers-Callees ¶

This view shows the calling relationships between the functions executed, along with the performance metrics.

The selected function is shown in the center panel. The function(s) in the panel above (the ‘callers’) are those that call the target function. The ones in the panel below (the ‘callees’), are called by this function. On the righthand side, the ‘Selection Details’ window displays more details of the function selected.

7.2 Call Tree ¶

This view displays a dynamic call graph of the program as a tree. It is useful to see the details of branches in the call tree that have the greatest impact on the performance.

Each function call is shown as a node that can be expanded, or collapsed, by clicking on the key-like icon to the left of the node. An expanded function node shows all the function calls made by the function, plus performance metrics for those function calls. When a function is selected, the Selection Details window displays the metrics for the function call and its callees. The percentages given for attributed metrics are the percentages of the total program metrics. The default root of the tree is <Total>, which is a pseudo function that represents 100% of the performance metrics of all the functions executed.

To easily find the branch that is consuming the most time, right-click any node and in the pulldown menu, select ‘Expand Hottest Branch’. In this menu, predefined filters are available to narrow down the view.

7.3 Disassembly ¶

The instructions for the selected function are shown. The metrics that have been measured are displayed to the left. The source line number where an instruction originates from is shown in square brackets.

7.4 Experiments ¶

This view displays more details on the experiment(s) and the load objects that have been used.

For each experiment, a ‘Notes’ and ‘Info’ section are shown. The ‘Notes’ section allows text to be added, or modified. This may be used to annotate the experiment.

Note that such comments can also be added by using the -C option on the gprofng collect app tool.

7.5 Flame Graph ¶

The flame graph is a compact graphical representation of the call tree. The call stacks are organized vertically. Frames include the name a function and the width of the frame is a relative measure of the inclusive CPU time for that function. Just as with the call tree, right-clicking on a frame, shows a pulldown menu with filters and navigation controls. The zoom function at the top may be used to zoom in, or out.

7.6 Functions ¶

One common view to explore is the function overview. By selecting the ‘Functions’ feature, a list with the functions that have been executed, as well as the metrics that have been recorded, is displayed.

By default, the exclusive and inclusive CPU times are displayed, both as a number and a percentage. If hardware events have been collected, these will be shown as well. The data is sorted with respect to the exclusive timings. By clicking on a different column, the data is sorted according to that metric.

Most likely more details are needed. To see more details for a function, select the function name shown under column ‘Name’. This will show several characteristics of the function, including the metrics, in a window to the right.

By double clicking a function name, control is transferred and the view changes to display the source lines of the function, annotated with the performance metrics that are shown to the right. The most expensive source lines are highlighted. Colored markers to the right indicate where the expensive lines are. By clicking on one of those, the display is changed to show the source code fragment with the target line included.

This action automatically adds the Source view to the list in the righthand side panel. This is a persistent change. A next time the same experiment is loaded, this view is included in the list.

The source view can also be selected by clicking on Source/Disassembly in the panel on the lefthand side. This will show a split window with the source code at the top and the disassembly with the instructions underneath. In both windows the source lines and instructions are annotated with the performance metric(s).

7.7 Processes ¶

This view shows a list of processes that were created by the application, along with their metrics. In this view, it is easy to find those processes that used the most resources. Filters may be used to select a particular set of processes. This selection is used in other views.

The processes are represented by process ID (PID) numbers and show the Total CPU time metric by default. Other metrics might also be displayed if the metrics are present in the loaded experiment(s). If other metrics have been selected in the ‘Overview’ view, or by using the ‘Settings’ dialog, those metrics are also displayed.

7.8 Source/Disassembly ¶

This shows two windows, each with their own scrollbar. The top window shows the source code, annotated with the values for the metrics selected. The window below lists the instructions with the metrics to the left. In both cases, the expensive parts are highlighted.

7.9 Threads ¶

This view shows a list of the threads that have been created together with their metrics. The threads are represented by a process plus thread pair and show the Total CPU time. Other metrics might also be displayed if the metrics are present in the loaded experiments. The filter button may be used to filter the data shown.

7.10 Timeline ¶

The timeline view is shown by selecting ‘Timeline’ in the panel on the lefthandside. This displays the color coded dynamic behavior of the application as a function of time.

• The Default View
• More Details
• Customization
• Filters

7.11 More ... ¶

Several other views are available. Through this view, they can be enabled, or already visible views may be disabled. The choices available are documented in the next chapter.

8.1 CPUs ¶

This view shows a list of CPUs that have been used while executing the application. This is shown along with the metrics that have been enabled for the data collection.

The CPUs are represented by a CPU number. By default, the ‘Total CPU time’ is shown. Other metrics might also be displayed by default if the metrics are present in the loaded experiments. Filters may be applied to the data shown.

8.2 Datasize ¶

This view is available for ‘Heap Tracing’, and ‘I/O Tracing’ experiments. They contain data that has a size element, such as the number of bytes.

The data is organized into ranges of data sizes. The metrics for the events whose data falls into a given range are shown. Data without a size element is attributed to data size 0.

This view can be used to filter the data. For example, in an experiment that contains heap tracing data, you could select a size range line that has high metrics for ‘Bytes Leaked’ and add the filter ‘Include only events with selected items’. In other data views, the data is then filtered to only show events that produced memory leaks of the size range that was selected.

8.3 Duration ¶

This view is available for ‘Heap Tracing’, ‘I/O Tracing’, and ‘Synchronization Tracing’ experiments. They contain data that has a duration.

The data is organized into ranges of the duration time. The metrics for the events whose data falls into each range of duration time are shown.

The duration of the function call is recorded for I/O and Synchronization tracing. For heap tracing, the duration is the time between the allocation and release of memory. Data without a duration element is attributed to duration 0.

This view may be used to filter the data. For example, in an experiment that contains heap tracing data, you could select a duration range line that has high metrics for ‘Bytes Allocated’ and add the filter ‘Include only events with selected items’. In other data views, the data is then filtered to show only events whose duration matched the range that was selected. This might reveal memory allocations that have a longer than expected duration.

8.4 Experiment IDs ¶

This view shows a list of processes that were created by the application, along with its metrics. The ‘IDs’ are represented by process ID (‘PID’) numbers and show the ‘Total CPU time’ metric by default.

Other metrics might also be displayed if the metrics are present in the experiment(s) loaded. If other metrics have been selected in the ‘Overview’ view, or by using the ‘Settings’ dialog, those metrics are also displayed.

The metrics values reflect the states recorded at each sample point in the loaded experiment(s). The numbers reflect the value, or percentage, of the metrics that were recorded in each of the loaded experiments.

8.5 GCEvents ¶

This view shows a summary of the Garbage Collection (‘GC’) events that occurred while the program was executing.

8.6 Lines ¶

This view shows a list consisting of source lines and their metrics. Source lines are labeled with the function from which they came, plus the line number and source file name.

Selecting a line shows all the metrics for a given line in the ‘Selection Details’ tab. Selecting the ‘Source’ or ‘Disassembly’ view after selecting a line, positions the display at the appropriate line.

If no line number information is available for a function, or if the source file for the function is not known, all of the function’s Program Counters (‘PCs’) appear aggregated into a single entry for the functions.

PCs from functions that are from load objects whose functions are hidden, appear aggregated as a single entry for the load object.

8.7 PCs ¶

This view is similar to the Lines view, but instead of source lines, lists Program Counters (‘PCs’) and their metrics.

Selecting a line shows all the metrics for that PC in the Summary tab. Selecting the ‘Source’, or ‘Disassembly’ view after selecting a line, positions the display at the appropriate line.

PCs are labeled with the function from which they came and the offset within that function. PCs from functions that are from load objects whose functions are hidden appear aggregated as a single entry for the load object.

8.8 Samples ¶

This view shows a list of (Operating System) sample points and their metrics, which reflect the states recorded at each sample point in the loaded experiments.

The samples are represented by sample numbers and by default show the ‘Total CPU time’. Other metrics might also be displayed if they have been selected in the ‘Overview’ view, or in the ‘Settings’ dialog box. Filters may be applied to the data shown.

8.9 Seconds ¶

This view shows each second of the program run that was captured in the experiment, along with metrics collected in that second.

The ‘Seconds’ view lists the seconds of execution with the ‘Total CPU time’ by default. Other metrics might also be displayed if the metrics are present in the loaded experiments. If other metrics have been selected in the ‘Overview’ view, or by using the ‘Settings’ dialog, those metrics are also displayed. Filters may be applied to the data shown.

The ‘Seconds’ view differs from the ‘Samples’ view in that it shows periodic samples that occur every second beginning at 0 and the interval cannot be changed.

8.10 Source ¶

If the source code is available, this view shows the source lines of the selected function, annotated with performance metrics to the left of the lines.

High metrics are highlighted in yellow to indicate lines that are expensive regarding the metric(s) used. For each of such lines, an orange navigation marker is shown in a margin next to the scrollbar on the right. Non-zero metrics that are below the threshold are not highlighted, but they are flagged with grey navigation markers. The threshold for highlighting metrics can be set in the ‘Settings dialog box’, or in the ‘Source/Disassembly’ view.

To quickly navigate to source lines with metrics, click the yellow markers in the right margin to jump to the lines with metrics. To jump to the next line with metrics, right-click the metrics themselves and select an option such as ‘Next Hot Line’, or ‘Next Non-Zero Metric Line’.

In the column heading for the source code, the full path to the source file is shown, plus the corresponding object file, and the name of the load object In case where the same source file is used to compile more than one object file, the source view shows the performance data for the object file containing the selected function.

If a source file cannot be located, the ‘Resolve’ button may be used to browse to the source file, or type the path to the source, or browse to it. The source code is then displayed from the new location.

Optionally, ‘Archive Source Files Inside Experiment’ can be selected to copy the source files into the experiment.

When double clicking on a function in the ‘Functions view’, the source view is opened. The source file displayed is the default source context for that function. The default source context of a function is the file containing the function’s first instruction. For example, for C code this is the function’s opening brace. Immediately following the first instruction, the annotated source file adds an index line for the function. The source window displays index lines as text in red italics within angle brackets in the form: <Function: f_name>.

A function might have an alternate source context, which is another file that contains instructions attributed to the function. Such instructions might come from include files, or from other functions inlined into the selected function. If there are any alternate source contexts, the beginning of the default source context includes a list of extended index lines that indicate where the alternate source contexts are located: <Function: f, instructions from source file src.h>.

Double-click an index line that refers to another source context to open the file containing that source context at the location associated with the indexed function.

To aid navigation, alternate source contexts also start with a list of index lines that refer back to functions defined in the default source context and other alternate source contexts.

8.11 Statistics ¶

This view shows the totals for various system statistics aggregated over the experiments loaded and samples. These totals are followed by the statistics for the selected samples of each experiment.