NAME

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


DESCRIPTION

       opmview supports three configuration  file  formats,  1.0,
       2.0  and  2.1. Support for version 1.0 configuration files
       may be deprecated in a future release and should be  modi­
       fied  to  use  the  2.1 format. Version 2.0 is a subset of
       version  2.1,  although  version  2.0  scenes  may  appear
       slightly different when compared with the previous release
       of opmview.  All new configurations should use the Version
       2.1 syntax.


MULTIPLE HOSTS AND ARCHIVES

       All  configuration  formats  support 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)).


CONFIGURATION - VERSION 2.1

       The  configuration  file  format  is based on a two-dimen­
       sional grid which can contain a variety  of  bar,  stacks,
       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 opmview configuration
       file is identified by the first line:

          pmview Version 2.1 [command_line]

       Configuration  files  which  lack  this version string are
       assumed to be Version 1.0 files which  will  produce  many
       strange errors as the formats are completely different.

       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 opmview was
       still running.  Care should be taken to  ensure  that  the

       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 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.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, 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

                            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 after 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.

           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.

       _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 _bar and
       _stack objects.  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
           _bar  or  _stack  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 four different object types in a opmview scene:
       _bar, _grid, _label  and  _stack.   The  _bar  and  _stack
       objects  are modulated by metric values, a _label is fixed

       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 brackets of the rele­
       vant  _bar,  _grid  or  _stack  object.   The first ``\n''
       sequence in the string will be replaced by a newline  when
       the  label  is  displayed  in the text box, but subsequent
       ``\n'' sequences will be left untranslated.

       A valid scene must contain at least  one  _bar  or  _stack
       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.   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.

               The  grouping  of  blocks  when  launching.   When
               launching  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  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 _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 _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 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 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:



EXAMPLE - VERSION 2.1

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


CONFIGURATION - VERSION 2.0

       Version 2.0 syntax is a subset of Version 2.1. The follow­
       ing  keywords  are  still supported but have been replaced
       with new keywords.

              Replaced by _baseHeight.

       _barXMargin
              Replaced by _marginWidth.

       _barYMargin
              Replaced by _marginDepth.

       _colorlist
              Replaced by _colorList.

       _gridHeight
              Replaced by _baseHeight.

       _gridSpace
              Replaced by _gridWidth and _gridDepth.

       _labeledBar
              Replaced by _bar as all _bar objects may have  met­
              ric and instance labels.

       _stackBaseHeight
              Replaced by _baseHeight.

       _stackHeight
              Replaced by _barHeight.

       _stackXMargin
              Replaced by _marginWidth.

       _stackYMargin
              Replaced by _marginDepth.

       _util  Replaced by _stack with a _utilmod type.

       All  keywords  that  did  not begin with an underscore now
       begin with  an  underscore.   This  includes  the  compass
       directions,  up,  down, left, right, small, medium, large,
       show, hide, row, col, away and towards.

       The other notable difference is the extension of the  _bar
       and  _stack syntax to allow for new modulated objects, and
       the simplification of the _label syntax.  The Version  2.0
       syntax  for  _bar,  _stack  and  _label  objects  is still
       accepted by opmview in this release.

       Most notably, a _label may still be specified as:

               _label pos (
                    _direction left|right|up|down
                    _size small|medium|large
                    _text name_or_string
               )

       The original configuration format is still  supported  but
       may  be deprecated in a later release.  All configurations
       using this format should be rewritten


RESOURCES

       The parameters described in the  Configuration  -  Version
       2.1   section  are  also  resources  in  /var/lib/X11/app-
       defaults/PmView.  The default values  may  be  altered  in
       this  file,  in  a personalized .Xdefaults file, or on the
       command line using the X(1) option -xrm.   Any  parameters
       in  a configuration file will be used in preference to the
       resource settings.


SEE ALSO

       opmview(1), pmview+(1) and pmview+(4).


Man(1) output converted with man2html