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

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 hardware threads.

       -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 hardware threads 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 hardware thread 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 hardware thread. 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>.