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