Ubuntu Manpage: likwid-perfscope - Frontend for the timeline mode of likwid-perfctr(1) that generates pictures on-the-fly

NAME

       likwid-perfscope - Frontend for the timeline mode of likwid-perfctr(1) that generates pictures on-the-fly
       from the measurements

SYNOPSIS

       likwid-perfscope  [-hvadp]  [-c  <cpu_list>]  [-C  <cpu_list>]  [-t   <frequency>]   [-r   <value>]   [-g
       <eventset_and_plotconfig>] [--host <hostname>] <executable>

DESCRIPTION

       likwid-perfscope  is  a  command  line  application  written in Lua that uses the timeline daemon mode of
       likwid-perfctr(1) to create on-the-fly pictures with the current measurements. It uses the feedGnuplot(1)
       script to send the current data to gnuplot. Since the plot windows are normally closed directly after the
       execution of the monitored applications, likwid-perfscope waits until Ctrl+c is pressed.

OPTIONS

       -h,--help
              Prints a help message to standard output, then exits.

       -v,--version
              Prints version information to standard output, then exits.

       -C  <cpu_list>
              Measures on given CPUs in <cpu_list>. See likwid-pin(1) for further information about the syntax.

       -C  <cpu_list>
              Measures the given group on given CPUs in <cpu_list>. See likwid-pin(1)  for  further  information
              about the syntax. The application is pinned to that cores.

       -a,--all
              List preconfigured event and plot configurations

       -d,--dump
              Print the measurements of likwid-perfctr(1) to stdout.

       -t,--time  <frequency>
              Reads  the  current performance values every <frequency>. Available suffixes are 's', 'ms' or 'us,
              e.g. 500ms. Default value is 1s.

       -g,--group  <eventset_and_plotconfig>
              Defines the events and counters that should be read. Possible values can be gathered from  likwid-
              perfctr(1).   You  can  give  multiple  -g  options on the commandline. They will be measured in a
              round-robin fashion and one plot generated per option. Moreover,  the  -g  option  accepts  config
              options for feedGnuplot(1), see section EVENTSETS

       -r,--range  <value>
              Plot only the last <value> values. Often referred to as sliding window.

       -p,--plotdump
              Use  the  dumping  feature of feedGnuplot to print out the plot configuration and its data at each
              timestep.  Can be used to create file-based plots afterwards.

       --host  <hostname>
              Instead of performing likwid-perfctr on the local machine, execute it on a remote machine and plot
              data  locally.  Uses ssh and you probably need to enter the password before starting. You can also
              give something like user@host.

EVENTSETS

       In contrast to the -g option for likwid-perfctr the -g option for likwid-perfscope is extended to  accept
       configuration  options  for  feedGnuplot.   There  are  some predefined plot configurations embedded into
       likwid-perfscope which can be listed with the -a command line option. They  are  filtered  to  show  only
       configs  that  are  available for your current system.  If you need to measure and plot custom events you
       can set the plotting options as last entry in your eventset. The plotting config options can be set as  a
       ':' separated list. If you select preconfigured group, you can overwrite single fields in the config like
       changing the title or the matching. The folling options are available:

       1.  title=<string>, TITLE=<string>

       Use the given title for the plot, use "" to enclose text with spaces and escape characters which could be
       interpreted by the shell. ':' are not allowed!

       2.  xtitle=<string>, XTITLE=<string>

       Use  the given title for the x-axis of the plot, use "" to enclose text with spaces and escape characters
       which could be interpreted by the shell. ':' are not allowed!

       3.  ytitle=<string>, YTITLE=<string>

       Use the given title for the left y-axis of the plot, use ""  to  enclose  text  with  spaces  and  escape
       characters which could be interpreted by the shell. ':' are not allowed!

       4.  <string>=<string>

       All option string items that is not recognized as keyword like TITLE are used as formulas for the output.
       You can set multiple of those items in one option string. Each is calculated and integrated in the output
       plot. The first <string> is used as legend entry. The second <string> is the formula for the function.

       5.  y2title=<string>, Y2TITLE=<string>, y2title=<id-string>, Y2TITLE=<id-string>

       Use the given title for the right y-axis of the plot. If no id is set, the last y2-axis is related to the
       last formula. If id is set, the formula with the id is used for the y2-axis. The id starts with  index  1
       for  the  first  formula.  Use  ""  to  enclose  text  with  spaces  and escape characters which could be
       interpreted by the shell with '´. ':' are not allowed!

EXAMPLE

1. Measure and print a preconfigured plotting configuration:

likwid-perfscope -g L3 -C 0-2 -t 1s ./a.out

This measures the L3 bandwidth with likwid-perfctr every second on CPU cores 0,1,2 and use the plotting
configuration L3. The plot will have a title and the axes are labeled properly.

2. Measure and print a preconfigured plotting configuration:

likwid-perfscope -g L2:TITLE="My Title" -C 0 -t 1s ./a.out

This measures the L2 bandwidth with likwid-perfctr every second on CPU core 0 and use the plotting
configuration L2. The title of the output plot is changed to the custom title "My Title".

3. Custom event set with plotting configuration:

likwid-perfscope -g INSTR_RETIRED_ANY:FIXC0,CPU_CLK_UNHALTED_CORE:FIXC1,
CPI=FIXC0/FIXC1:YTITLE="Cycles per Instruction" -C 0 --time 500ms ./a.out

Executes likwid-perfctr on the first core. The values for the events INSTR_RETIRED_ANY and
CPU_CLK_UNHALTED_CORE are read every 500ms. The raw values are transformed using the formula FIXC0/FIXC1
and forwarded to gnuplot using the feedGnuplot(1) script with the curve name 'CPI' in the legend. The y-
axis is labeled with the string "Cycles per Instruction". IP 4. 5 Custom event set with plotting
configuration:

likwid-perfscope -g L3,CPI=FIXC0/FIXC1:Y2TITLE="2-Cycles per Instruction" -C 0 --time 500ms ./a.out

This measures the L3 bandwidth for CPU 0 every 500 ms. Additionally, a second curve is plotted with the
function FIXC0/FIXC1 with the legend entry CPI. The right y-axis is labeled with 'Cycles per
Instruction' and is associated to the second formula. The first formula is hidden in the L3 plot group.
Since the CPI formula is the last in the list, the curve id is not needed in the Y2TITLE as this is the
default behavior.

AUTHOR

       Written by Thomas Gruber <thomas.roehl@googlemail.com>.

BUGS

       Report Bugs on <https://github.com/RRZE-HPC/likwid/issues>.