pmview(5) — Linux manual page

NAME | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON

PMVIEW(5)                  File Formats Manual                 PMVIEW(5)

NAME         top

       pmview - configuration file format for performance

DESCRIPTION         top

       This man page describes version 2.1 of the pmview configuration
       file format.

       The configuration format supports metrics from multiple hosts or
       archives.  A configuration file can specify metrics without a
       source, with different hosts and different archives.  However, a
       configuration file that contains archives may only have one
       archive for any one host.  When in ``replay'' mode, any metrics
       with host specific sources require an archive to be specified for
       that host on the command line or as a source to a previous
       metric.  The archive must be the same archive (based on a string
       comparison of the archive names) of any archives specified in the
       configuration file for the same host.

       The time controls will list all hosts that are specified on the
       command line and the configuration file in the timezone listing
       (see pmtime(1)).

       The configuration file format is based on a two-dimensional grid
       which can contain a variety of bars, stacks, links, pipes, labels
       and other grids.  The grids resize each column and row to match
       the size of the largest item in that column or row.  A
       configuration file that contains only one object does not require
       a grid. The pmview configuration file starts with an
       identification header in the first non-comment line:

          pmview Version 2.1 [command_line]

       The optional command_line should be the command line with which
       the tool was launched, if the configuration file has been
       generated by another tool.  This is useful for applications that
       are to be restarted automatically on the next login, after the
       user has logged out while pmview was still running.  Care should
       be taken to ensure that the command specified is either a full
       pathname or will be found on the PATH available at login.

       All lines which begin with ``#'' are treated as comments and
       ignored.  Otherwise, all spaces, tabs and newlines are treated as
       white space so multiple commands may be on the same line.

       The syntax for specifying values in the configuration file is
       consistent for all commands, namely:

       color
           A color must be either a X(1) color name, a X(1) numerical
           color, or three normalized real values representing the
           saturation of red, green and blue.  For example, the
           following colors are identical:

               red
               rgbi:1.0/0.0/0.0
               1.0 0.0 0.0

       int An integer.

       metric
           A metric consists of an optional source (host or archive),
           the metric name, an optional instance list immediately after
           name, followed by the maximum (or normalization value).  A
           colon (``:'') is used to separate a host name from the
           metric, and a forward slash (``/'') to separate an archive
           name from the metric.  Instances are enclosed in square
           brackets and comma separated.  Each instance may be enclosed
           in quotes.

           For example, some legal metrics are:

               kernel.all.cpu.idle 4000
               myhost:kernel.all.cpu.idle[cpu0,"cpu3"] 1000.0
               /path/to/myarchive/kernel.all.cpu.idle[cpu1] 1000

           To assist the process of matching instance names, two further
           comparisons are made beyond a simple string comparison.  If
           the instance name contains spaces, only the first word in the
           instance name is required to match the instance, assuming
           that the first word is unique.  If the first word is not
           unique, only the first matching instance will be selected.
           The second comparison occurs if the first word is a number
           with leading zeros.  Any leading zeros will be skipped before
           comparing the first word again.  This permits process ids
           used in the proc metrics to be easily matched, without
           specifying the entire instance name.  For example, to
           visualize the user and system time of init use the metric
           specification

               proc.psusage.utime[1]    1000
               proc.psusage.stime[1]    1000

       name
           A name for an object which may be referred to later in the
           configuration file.  Names must be a single word consisting
           of all alphanumeric characters, as well as underscores,
           dashes and colons.  It is recommended that names do not begin
           with an underscore as this may be interpreted as a keyword.

       pos This is the position of the object within the grid.  The
           syntax of a position is:

          [ [x z] [ [width depth] [alignment] ] ]

              x
           The horizontal coordinate (left to right) of the object,
           starting at 0.  The default x is 0.

              z
           The vertical coordinate (top to bottom) of the object,
           starting at 0.  The default z is 0.

              width
           The number of columns occupied by the object.  The default
           width is 1.

              depth
           The number of rows occupied by the object.  The default depth
           is 1.

              alignment
           The edge or corner that the object is aligned with.  Possible
           alignments include: north, south, east, west, northeast,
           northwest, southeast, southwest and center.  Abbreviations
           like se and SE are also accepted.  The default alignment is
           center.

           The size of an object may not be known as the number of
           instances for some metrics will vary between hosts and PMDA
           configurations.  Therefore, the position of the object can be
           used to specify the likely size of the object, so that the
           position of the surrounding objects is appropriately
           adjusted.

           The following are legal positions:

                     0 5
           The object is centered at grid position 0,5 occupying 1 grid
           square.

                     1 2 north
           The object is aligned with the north edge of position 1,2
           occupying 1 grid square.

                     2 2 2 1 east
           The object is aligned to the eastern edge of position 3,2 and
           occupies 2 grid squares (2,2 and 3,2).

       string
           A string is a series of characters enclosed in double quotes.
           A string may not contain newlines or escaped double quotes.

       There are several parameters that may affect the size, shape and
       color of objects when they are displayed.  These parameters are
       scoped so that they only alter objects defined later in the same
       scope.  Therefore, parameter settings at the top of a
       configuration file affect the entire scene, unless they are
       changed later in the file.  Most of these parameters are also
       resources.

       _barLength int
           The side length of the _bar and _stack blocks.  Default is
           28.

       _barHeight int
           The maximum height of a _bar and _stack blocks.  Default is
           80.

       _baseColor color
           The color of _bar, _grid and _stack base planes.  Default is
           rgbi:0.15/0.15/0.15.

       _baseHeight int
           The height of _bar, _grid and _stack base planes.  Default is
           2.

       _gapWidth int
           The gap between blocks in a _bar object in the X-axis.  The
           default is 8.

       _gapDepth int
           The gap between blocks in a _bar object in the Z-axis.  The
           default is 8.

       _gapLabel int
           The gap between the base of a _bar object, and any metric or
           instance labels.  The default is 6.

       _gridWidth int
           The minimum width of a _grid column.  The default is 20.

       _gridDepth int
           The minimum depth of a _grid row.  The default is 20.

       _labelMargin int
           The margin around a _label object.  The default is 5.

       _labelColor color
           The color of _label and _bar labels.  The default is white.

       _marginWidth int
           The extra width of a _bar, _grid and _stack base plane beyond
           the objects on the plane.  The default is 8.

       _marginDepth int
           The extra depth of a _bar, _grid and _stack base plane beyond
           the objects on the plane.  The default is 8.

       _pipeLength int
           Total length of a _pipe.  The default is the value of
           _barHeight.

       _scale real
           The scale applied to the entire scene.  This parameter may
           not be used within any objects, only at the top of the
           configuration file.  The default is 1.0.

       To simplify the specification of colors, a _colorList and a
       _colorScale may be used to define colors for an object which has
       metrics associated with it, i.e.  _bar, _stack or _pipe.  A color
       list may be defined within an object, or named and defined at the
       top of a configuration file.  A named color list may then be
       referenced within multiple objects:

       _colorList name ( color [color...] )
           Associate the colors with the color list name.  The
           assignment of colors to blocks depends on the type of an
           object.  For example, the color list called foo has the same
           color three times:

           _colorList foo ( red rgbi:1.0/0.0/0.0 1.0 0.0 0.0 )

       _colorScale name color ( color real [color real...] )
           Associate the colors and reals with the color list name.  The
           initial color is the default color of the object.  The object
           will change color to the other colors when the normalized
           value of the object is equal to or greater than each real.
           Therefore, each real must be larger than the previous real,
           and should be in the range 0.0 to 1.0.  This scale gradually
           changes from blue to red:

           _colorScale coldToHot blue ( rgbi:0.5/0.0/1.0 0.3
                                        purple 0.6
                                        rgbi:1.0/0.0/0.5 0.8
                                        red 0.95)

       There are several different object types which could be found in
       a pmview scene: _bar, _stack, _pipe, _grid, _link, and _label.
       There is also _xing which is a special type of the _link.  The
       _bar, _stack and _pipe objects are modulated by metric values, a
       _label is fixed text, _link and _xing are interconnects and a
       _grid is a container of objects, including other _grid objects,
       which controls the layout of the scene.  A _grid object is only
       required if there are two or more objects in the scene.

       _bar, _grid and _stack objects may have base planes which provide
       a point of reference for the blocks as they change height.  A
       label can be applied to the base plane _grid object if it is
       _shown with:

               _baseLabel name|string

       _baseLabel should be used within the scope of the relevant _bar,
       _grid or _stack object.  The first ``\n'' characters in the
       string will be replaced by a new line.  Subsequent ``\n''
       characters will be ignored.

       For a scene to be valid it must contain at least one modulated
       object.

       The objects are defined as:

       _bar [options] ( [metric-list] [color-list] [label-list] )
           A _bar object represents a collection of blocks.  The number
           of blocks depends on the number of metrics and metric
           instances assigned to the object.  By default, the blocks are
           modulated by changing the height of each block.
           Alternatively, blocks may be modulated by changing color, or
           both height and color.  Each color in the color-list is
           assigned to each metric.  Therefore, multiple instances of
           the one metric will have the same color.  The options that
           may be passed to a _bar object are:

           pos The position of the _bar object within the current _grid
               object.

           _col|_row
               Position the blocks so that each instance is in a column
               (_col) or a row (_row).  This implies that each different
               metric is in a separate row or column, respectively.  The
               default is _col.

           _show|_hide
               Is the base plane visible? Default is _show.

           _ymod|_colormod|_colorymod
               Modulate the blocks by adjusting their height (_ymod),
               color (_colormod) or both height and color (_colorymod).

           _cube|_cylinder
               Set the shape of the blocks.  The default is _cube.

           _groupbymetric|_groupbyinst|_groupbyrow||groupbycol
               Set the grouping of blocks when launching other tools.
               For tools like pmchart(1) some views may generate many
               small charts which cannot be drawn entirely within the
               screen.  Another problem is it may be more appropriate to
               generate charts with the same instance in each chart,
               rather then the same metric.  The group specifiers
               control the algorithm used so that a separate chart will
               be drawn for each _metrics specification
               (_groupbymetric), for the first, second etc. instance of
               each _metric (_groupbyinst), or by the rows and columns
               of the _bar object depending on _row or _col.  The
               default is _groupbymetric.

           The options must be specified in this order, although
           preceding options are not required.  Therefore, this is
           legal:

               _bar _hide _cylinder ( ... )

           The metrics, colors and labels are specified within the
           brackets in any order.  Only the metric-list is mandatory.

           metric-list
               A _bar metric list contains a list of metric names,
               normalization values and an optional label for the
               metric:

               _metrics ( metric real [string] [metric real [string]...] )

           color-list
               A _bar color list may be a named color list that was
               defined earlier, or an unnamed color list.  A _colorScale
               list should be used when using _colormod or _colorymod
               modulation.  Therefore, the syntax for color lists within
               a _bar object are any of:

               _colorList name
               _colorList ( color [color...] )
               _colorScale name
               _colorScale color ( color real [color real...] )

           label-list
               In addition to labels for each metric in the metric-list,
               metric and instance labels may be defined using
               _metriclabels and _instlabels statements.  The position
               of the labels around the _bar object depends on the _row
               or _col orientation of metrics and instances, and whether
               the label is read _towards the _bar object, or _away.
               The default is _towards.

               _metriclabels [_away|_towards] ( name|string [name|string...] )
               _instlabels [_away|_towards] ( name|string
               [name|string...] )

       _grid [pos] [_show|_hide] ( objects )
           A _grid object is a container for objects, including other
           _grid objects.  The rows and columns of a _grid object are
           resized to the largest object in the row or column.  If an
           object spans multiple rows and/or columns, those rows and
           columns may be partly resized to contain the object.
           However, the resizing of rows and columns for objects
           occupying multiple rows and columns occurs after resizing for
           objects occupying only one grid square.

           A collision between objects occupying the same squares will
           be reported as an error message and the later object will be
           ignored.

           The options to a _grid object control the position (pos) of
           the _grid object in the parent _grid, and indicate whether to
           _show or _hide the _grid base plane.  By default, the base
           plane is hidden.

           The parameters described above may be specified within the
           brackets of a _grid object, however they only apply to the
           objects within the _grid, not the _grid itself.  For a
           parameter to be applied to a _grid object, it must be
           specified before the _grid object declaration.

       _label [options] string
           A _label object draws the contexts of string at the location,
           orientation and size specified in the options:

           pos The position of the _label object in the current _grid
               object.

           _left|_right|_up|_down
               The orientation of the string.  The direction indicates
               the direction the label is read.  Therefore, _right is
               the default since the string is read from left to right.

           _small|_medium|_large
               The font size.  The default is _medium.

       _link pos [string]
           A _link object draws a straight or L-shaped horizontal round
           ``pipe'' with diameter equal to 80% of the _baseHeight of an
           enclosing _grid.  The properties of the object are defined by
           the options:

           pos sets both the position of the _link on the grid and its
               shape.  _link starts in the column and row on the _grid
               specified by first two numbers in the pos and spans the
               number of columns and rows set by the second two numbers.
               The alignment value is used to decide the orientation of
               the link (links are always aligned at the center): east
               and west links are straight and going from left to right,
               north and south links are straight and going from far end
               of the grid to near end, northeast, northwest, southeast
               and southwest links are L-shaped and connect the
               corresponding points of the compass, i.e. a northeast
               link takes on the general shape of the Latin letter
               ``L''.

           string
               sets the ``tag'' for the _link which will be displayed in
               the text window when the pointer is over the link.

       _pipe pos ( [metric-list] [color-list] [tag] )
           A _pipe object represent a set of cylinders, placed on top of
           each other and oriented parallel to the base plane. The
           diameter of a _pipe is equal to 80% of _baseHeight.  The
           number of blocks is dependent on the number of metric
           instances in the metric-list.  The colors in the color-list
           are assigned in turn to each cylinder in the _pipe.  The
           length of the _pipe is defined by the _pipeLength.

           pos defines the position of the _pipe on the enclosing _grid
               and its orientation with alignment field used to define
               at which end of the pipe to stack the colored cylinders.
               The cylinders are stacked at the corresponding point of
               the compass and the pipe's direction is from the point of
               the compass towards the center of the compass.  Only
               east, west, north, and south are valid values for the
               pipe's alignment.

       The metrics, colors and label may be specified within the
       brackets in any order.  Only the metric-list is mandatory.

       metric-list
           A _pipe metric list contains a list of metric names and
           normalization values:

           _metrics ( metric real [metric real...] )

       color-list
           A _pipe color list may be named color list that was defined
           earlier, or an unnamed color list:

           _colorList name
           _colorList ( color [color...] )

       tag A _pipe may have a ``tag'' for the filler block (unanimated
           block on the ``other'' end of the pipe) which will be
           displayed in the text window when the pointer is over that
           end of the pipe.

           _pipeTag name|string

       _stack [options] ( [metric-list] [color-list] [label] )
           A _stack object represents a set of blocks placed vertically
           on top of each other.  The number of blocks is dependent on
           the number of metric instances in the metric-list.  The
           colors in the color-list are assigned to each block in the
           _stack.  By default, the height of the _stack will be the sum
           of the height of each block.  The options that may be passed
           to a _stack object are:

           pos The position of the _stack object within the current
               _grid object.

           _show|_hide
               Is the base plane visible? Default is _show.

           _utilmod|_fillmod
               Force the height of the stack to always be the maximum
               height.  This is achieved by normalizing the height of
               each block (_utilmod), or by adding a grey block to the
               top of the stack (_fillmod).

           _cube|_cylinder
               Set the shape of the blocks.  The default is _cube.

           The options must be specified in this order, although
           preceding options are not required.  Therefore, this is
           legal:

               _stack 1 1 _north _utilmod ( ... )

           The metrics, colors and label may be specified within the
           brackets in any order.  Only the metric-list is mandatory.

           metric-list
               A _stack metric list contains a list of metric names and
               normalization values:

               _metrics ( metric real [metric real...] )

           color-list
               A _stack color list may be named color list that was
               defined earlier, or an unnamed color list:

               _colorList name
               _colorList ( color [color...] )

           label
               A _fillmod type _stack may have a label for the filler
               block:

               _stackLabel name|string

       _xing col row columns rows dir1 ... dir4
           A _xing is a special kind of link which is used to draw a
           pair of links which cross each other. To convey the visual
           impression that the links do not join, one of the links is
           drawn as a ``broken'' cylinder.  col and row define the
           position on the enclosing grid.  columns and rows define the
           size of the bounding box. The end points of the crossing
           cylinders are placed exactly in the center of the corner
           cells of the bounding box and four small cylinders or stubs
           are used to join the perimeter of the bounding box with the
           end points on the crossing cylinders. Four dir values define
           the orientation of the stubs, starting at the upper left
           corner of the _xing and proceeding clockwise, such that
           respective stubs are used to join the point of the compass
           with the center on the cell (see example).

EXAMPLE         top

       This simple example illustrates the use of parameters and
       different object types:

          pmview Version 2.1
          # Use a lighter grey for the base planes
          _baseColor rgbi:0.5/0.5/0.5

          # Define colors for CPU object
          _colorList cpu ( blue2 red2 yellow2 cyan2 green2 )

          # The top grid object, but hide it from view
          _grid _hide (

          # Show the current load in a bar object
             _bar 0 0 (
                 _baseLabel "Load averages over a\n1, 5 and 15 minute interval"
                 _metrics (
                    kernel.all.load[1] 1 "1"
                    kernel.all.load[5] 1 "5"
                    kernel.all.load[15] 1 "15"
               )
               _colorList ( blue blue blue )
              )

          # Add a label below the load bars
              _label 0 1 "Load"

          # Change the color of the base plane for later objects
              _baseColor pink

          # Show the CPU usage over all CPUs in a utilization stack
              _stack 2 0 _south _utilmod (
               _baseLabel "CPU Utilization over all CPUs"
               _metrics (
                    kernel.all.cpu.user 1000
                    kernel.all.cpu.sys 1000
                    kernel.all.cpu.intr 1000
                    kernel.all.cpu.wait.total 1000
                    kernel.all.cpu.idle 1000
               )
               _colorList cpu
              )

          # Add a label below the CPU stack
              _label 2 1 "CPU"

          # Create a separate grid for links and pipes
              _marginWidth 1
              _marginDepth 1
              _gridSpace  12
              _grid 0 3 5 4 _hide (
               _pipeLength 12
               _baseHeight 12

               # Add  a pipe and a link with western orientation
               _pipe 0 0 west (
                   _pipeTag "West pipe"
                   _metrics (
                    kernel.all.cpu.user 1000
                    kernel.all.cpu.sys 1000
                    kernel.all.cpu.idle 1000
                   )
                   _colorList cpu
               )

               _link 0 2 west "West link"

               # Add xing
               _xing 1 0 3 3 west east east west

               # Add a link and a pipe with eastern orientation
               _pipe 4 0 east (
                   _pipeTag "East Pipe"
                   _metrics (
                    kernel.all.cpu.user 1000
                    kernel.all.cpu.sys 1000
                    kernel.all.cpu.idle 1000
                   )
                   _colorList cpu
               )
               _link 4 2 east "East link"
              )
          )

SEE ALSO         top

       pmview(1).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http:https://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

Performance Co-Pilot                                           PMVIEW(5)

Pages that refer to this page: pmview(1)