NAME

gprofng-display-text - Display the performance data in plain text format

ManPageEnd

SYNOPSIS

gprofng display text [OPTION(S)] [COMMANDS] [-script SCRIPT-FILE] EXPERIMENT(S)

ManPageEnd

DESCRIPTION

Print a plain text version of the various displays supported by gprofng.

The input consists of one or more experiment directories.  Through commands, the user controls the output.

There is a rich set of commands to control the display of the data.  The NOTES section lists the most common ones.  The gprofng user guide lists all the commands supported.

Commands specified on the command line need to be prepended with the dash ('-') symbol.

In this example, a function overview will be shown, followed by the source code listing of function my-func, annotated with the performance metrics that have been recorded during the data collection and stored in experiment directory my-exp.er:

     $ gprofng display text -functions -source my-func my-exp.er

Instead of, or in addition to, specifying these commands on the command line, commands may also be included in a file called the SCRIPT-FILE.

Note that the commands are processed and interpreted from left to right, so the order matters.

If this tool is invoked without options, commands, or a script file, it starts in interpreter mode.  The user can then issue the commands interactively.  The session is terminated with the exit command in the interpreter.

ManPageEnd

OPTIONS

--version
     Options, --version

     Print the version number and exit.

--help
     Options, --help

     Print usage information and exit.

-script SCRIPT-FILE
     Options,  -script Commands, script

     Execute the commands stored in the script file.  This feature may be combined with commands specified at the command line.

ManPageEnd

NOTES

Many commands are supported.  Below, the more common ones are listed in mostly alphabetical order, because sometimes it is more logical to swap the order of two entries.

callers-callees
     Options,  -callers-callees Commands, callers-callees In a callers-callees panel, it is shown which function(s) call the target function (the callers) and what functions it is calling (the callees). This command prints the callers-callees panel for each of the functions, in the order specified by the function sort metric.

calltree
     Options,  -calltree Commands, calltree Display the dynamic call graph from the experiment, showing the hierarchical metrics at each level.

compare {on | off | delta | ratio}
     Options,  -compare Commands, compare By default, the results for multiple experiments are aggregated.  This command changes this to enable the comparison of experiments for certain views (e.g. the function view).  The first experiment specified is defined to be the reference.  The following options are supported:

     on
          For each experiment specified on the command line, print the values for the metrics that have been activated for the experiment.

     off
          Disable the comparison of experiments.  This is the default.

     delta
          Print the values for the reference experiment.  The results for the other experiments are shown as a delta relative to the reference (current-reference).

     ratio
          Print the values for the reference experiment.  The results for the other experiments are shown as a ratio relative to the reference (current/reference).

disasm FUNCTION-NAME
     Options,  -disasm Commands, disasm List the source code and instructions for the function specified.  The instructions are annotated with the metrics used.

fsingle FUNCTION-NAME [n]
     Options,  -fsingle Commands, fsingle Write a summary panel for the specified function.  The optional parameter N is needed for those cases where several functions have the same name.

fsummary
     Options,  -fsummary Commands, fsummary Write a summary panel for each function in the function list.

functions
     Options,  -functions Commands, functions Display a list of all functions executed.  For each function the used metrics (e.g. the CPU time) are shown.

header
     Options,  -header Commands, header Shows several operational characteristics of the experiment(s) specified on the command line.

limit N
     Options,  -limit Commands, limit Limit the output to N lines.

lines
     Options,  -lines Commands, lines Write a list of source lines and their metrics, ordered by the current sort metric.

metric_list
     Options,  -metric_list Commands, metric_list Display the currently selected metrics in the function view and a list of all the metrics available for the target experiment(s).

metrics METRIC-SPEC
     Options,  -metrics Commands, metrics Define the metrics to be displayed in the function and callers-callees overviews.

     The METRIC-SPEC can either be the keyword default to restore the default metrics selection, or a colon separated list with metrics.

     Hardware event counters, hwc metric A special metric is hwc.  It automatically expands to the active set of hardware event counters used in the experiment(s).

     Hardware event counters, IPC metric Hardware event counters, CPI metric If both instructions and clock cycles have been measured, the CPI and IPC metrics can be used to see the Clockcycles Per Instruction and Instructions Per Clockcyle values, respectively.

     The gprofng user guide has more details how to define metrics.

name {short | long | mangled}[:{soname | nosoname}]
     Options,  -name Commands, name Specify whether to use the short, long, or mangled form of function names. Optionally, the load object that the function is part of can be included in the output by adding the soname keyword.  It can also be ommitted (nosoname), which is the default.

     Whether there is an actual difference between these types of names depends on the language.

     Note that there should be no (white)space to the left and right of the colon (:).

     This option should not be confused with the keyword name in a metric definition, which is used to specify that the names of functions should be shown in the function overview.

overview
     Options,  -overview Commands, overview Shows a summary of the recorded performance data for the experiment(s) specified on the command line.

pcs
     Options,  -pcs Commands, pcs Write a list of program counters (PCs) and their metrics, ordered by the current sort metric.

sort METRIC-SPEC
     Options,  -sort Commands, sort Sort the function list on the METRIC-SPEC given.

     Sort, Reverse order The data can be sorted in reverse order by prepending the metric definition with a minus (-) sign.

     For example sort -e.totalcpu.

     Sort, Reset to default A default metric for the sort operation has been defined and since this is a persistent command, this default can be restored with default as the key (sort default).

source FUNCTION-NAME
     Options,  -source Commands, source List the source code for the function specified, annotated with the metrics used.

viewmode {user | expert | machine}
     Options,  -viewmode Commands, viewmode This command is only relevant for Java programs.  For all other languages supported, the viewmode setting has no effect.

     The following options are supported:

     user
          Show the Java call stacks for Java threads, but do not show housekeeping threads.  The function view includes a function called <JVM-System>. This represents the aggregated time from non-Java threads. In case the JVM software does not report a Java call stack, time is reported against the function <no Java callstack recorded>.

     expert
          Show the Java call stacks for Java threads when the user Java code is executed, and machine call stacks when JVM code is executed, or when the JVM software does not report a Java call stack.  Show the machine call stacks for housekeeping threads.

     machine
          Show the actual native call stacks for all threads.  This is the view mode for C, C++, and Fortran.

ManPageEnd

SEE ALSO

gprofng(1), gprofng-archive(1), gprofng-collect-app(1), gprofng-display-html(1), gprofng-display-src(1)

The user guide for gprofng is maintained as a Texinfo manual.  If the info and gprofng programs are correctly installed, the command info gprofng should give access to this document.

ManPageEnd

COPYRIGHT

Copyright © 2022-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

ManPageEnd