NAME

       pmview+  -  configuration file format for performance met­
       rics 3D visualization back-end


DESCRIPTION

       This man page describes version 2.1 of pmview+  configura­
       tion file format, which is the extention of pmview(1) con­
       figuration format version 2.1.

       The configuration format supports  metrics  from  multiple
       hosts  or archives.  A configuration file can specify met­
       rics without a source, with different hosts and  different
       archives.   However,  a  configuration  file that contains
       archives may only have one archive for anyone 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  com­
       parison 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-dimen­
       sional  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+ con­
       figuration 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 appli­
       cations 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:

           A color must be either  a  X(1)  color  name,  a  X(1)
           numerical  color, or three normalized real values rep­
           resenting 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 sep­
           arate 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.

           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, north­
                     west,  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 configura­
                     tions.   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  posi­
                            tion 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


       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.

           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

       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 modu­
       lated 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.  There­
           fore, 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 col­
               umn, 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.

               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 (_groupby­
               metric), 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 _color­
               mod or _colorymod modulation.  Therefore, the syn­
               tax  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  met­
               ric-list,   metric  and  instance  labels  may  be
               defined using _metriclabels and _instlabels state­
               ments.  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


               _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.  There­
               fore, _right is the default since  the  string  is
               read from left to right.

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

           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, north­
               west, southeast and southwest links  are  L-shaped
               and  connect  the corresponding points of the com­
               pass, 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 dis­
               played 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.

           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 (unan­
           imated  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 ver­
           tically 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  cur­
               rent _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 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

       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 )

          _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
               )


               # 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

       pmview(1) and pmview+(1).


Man(1) output converted with man2html