# pmview

## NAME



           **pmview** - configuration file format for performance views
    


## DESCRIPTION



           This man page describes version 2.1 of the pmview(1) 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 one of the 20-or so **Qt** color names
               (refer to the QColor class at
               https://doc.qt.io/qt-5/qcolor.html#predefined-colors), or an
               **HTML** hexadecimal color value (enclosed in quotes, e.g.
               "#ff6347"), or three normalized _real_ values representing the
               saturation of red, green and blue.  For example, the following
               colors are identical:
    
                   red
                   "#ff0000"
                   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
               "#262626" (i.e. gray15).
    
           **_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 _color_ s 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 "#ff0000" 1.0 0.0 0.0 )
    
           **_colorScale** _name color_ **(**_color real_ [_color real_...] **)**
               Associate the _color_ s and _real_ s 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 ( "#7f00ff" 0.3
                                            purple 0.6
                                            "#ff007f" 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



           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 "#7f7f7f"
    
              # 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 "#fba2f5" # 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"
                  )
              )
    


* * *