|
NAME | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON |
PMVIEW(5) File Formats Manual PMVIEW(5)
pmview - configuration file format for performance
This man page describes version 2.1 of the pmview configuration file
format.
The configuration format supports metrics from multiple hosts or
archives. A configuration file can specify metrics without a source,
with different hosts and different archives. However, a
configuration file that contains archives may only have one archive
for any one host. When in ``replay'' mode, any metrics with host
specific sources require an archive to be specified for that host on
the command line or as a source to a previous metric. The archive
must be the same archive (based on a string comparison of the archive
names) of any archives specified in the configuration file for the
same host.
The time controls will list all hosts that are specified on the
command line and the configuration file in the timezone listing (see
pmtime(1)).
The configuration file format is based on a two-dimensional grid
which can contain a variety of bars, stacks, links, pipes, labels and
other grids. The grids resize each column and row to match the size
of the largest item in that column or row. A configuration file that
contains only one object does not require a grid. The pmview
configuration file starts with an identification header in the first
non-comment line:
pmview Version 2.1 [command_line]
The optional command_line should be the command line with which the
tool was launched, if the configuration file has been generated by
another tool. This is useful for applications that are to be
restarted automatically on the next login, after the user has logged
out while pmview was still running. Care should be taken to ensure
that the command specified is either a full pathname or will be found
on the PATH available at login.
All lines which begin with ``#'' are treated as comments and ignored.
Otherwise, all spaces, tabs and newlines are treated as white space
so multiple commands may be on the same line.
The syntax for specifying values in the configuration file is
consistent for all commands, namely:
color
A color must be either a X(1) color name, a X(1) numerical color,
or three normalized real values representing the saturation of
red, green and blue. For example, the following colors are
identical:
red
rgbi:1.0/0.0/0.0
1.0 0.0 0.0
int An integer.
metric
A metric consists of an optional source (host or archive), the
metric name, an optional instance list immediately after name,
followed by the maximum (or normalization value). A colon
(``:'') is used to separate a host name from the metric, and a
forward slash (``/'') to separate an archive name from the
metric. Instances are enclosed in square brackets and comma
separated. Each instance may be enclosed in quotes.
For example, some legal metrics are:
kernel.all.cpu.idle 4000
myhost:kernel.all.cpu.idle[cpu0,"cpu3"] 1000.0
/path/to/myarchive/kernel.all.cpu.idle[cpu1] 1000
To assist the process of matching instance names, two further
comparisons are made beyond a simple string comparison. If the
instance name contains spaces, only the first word in the
instance name is required to match the instance, assuming that
the first word is unique. If the first word is not unique, only
the first matching instance will be selected. The second
comparison occurs if the first word is a number with leading
zeros. Any leading zeros will be skipped before comparing the
first word again. This permits process ids used in the proc
metrics to be easily matched, without specifying the entire
instance name. For example, to visualize the user and system
time of init use the metric specification
proc.psusage.utime[1] 1000
proc.psusage.stime[1] 1000
name
A name for an object which may be referred to later in the
configuration file. Names must be a single word consisting of
all alphanumeric characters, as well as underscores, dashes and
colons. It is recommended that names do not begin with an
underscore as this may be interpreted as a keyword.
pos This is the position of the object within the grid. The syntax
of a position is:
[ [x z] [ [width depth] [alignment] ] ]
x The horizontal coordinate (left to right) of the
object, starting at 0. The default x is 0.
z The vertical coordinate (top to bottom) of the object,
starting at 0. The default z is 0.
width The number of columns occupied by the object. The
default width is 1.
depth The number of rows occupied by the object. The default
depth is 1.
alignment
The edge or corner that the object is aligned with.
Possible alignments include: north, south, east, west,
northeast, northwest, southeast, southwest and center.
Abbreviations like se and SE are also accepted. The
default alignment is center.
The size of an object may not be known as the number of
instances for some metrics will vary between hosts and
PMDA configurations. Therefore, the position of the
object can be used to specify the likely size of the
object, so that the position of the surrounding objects
is appropriately adjusted.
The following are legal positions:
0 5 The object is centered at grid position 0,5
occupying 1 grid square.
1 2 north
The object is aligned with the north edge of
position 1,2 occupying 1 grid square.
2 2 2 1 east
The object is aligned to the eastern edge of
position 3,2 and occupies 2 grid squares (2,2
and 3,2).
string
A string is a series of characters enclosed in double quotes. A
string may not contain newlines or escaped double quotes.
There are several parameters that may affect the size, shape and
color of objects when they are displayed. These parameters are
scoped so that they only alter objects defined later in the same
scope. Therefore, parameter settings at the top of a configuration
file affect the entire scene, unless they are changed later in the
file. Most of these parameters are also resources.
_barLength int
The side length of the _bar and _stack blocks. Default is 28.
_barHeight int
The maximum height of a _bar and _stack blocks. Default is 80.
_baseColor color
The color of _bar, _grid and _stack base planes. Default is
rgbi:0.15/0.15/0.15.
_baseHeight int
The height of _bar, _grid and _stack base planes. Default is 2.
_gapWidth int
The gap between blocks in a _bar object in the X-axis. The
default is 8.
_gapDepth int
The gap between blocks in a _bar object in the Z-axis. The
default is 8.
_gapLabel int
The gap between the base of a _bar object, and any metric or
instance labels. The default is 6.
_gridWidth int
The minimum width of a _grid column. The default is 20.
_gridDepth int
The minimum depth of a _grid row. The default is 20.
_labelMargin int
The margin around a _label object. The default is 5.
_labelColor color
The color of _label and _bar labels. The default is white.
_marginWidth int
The extra width of a _bar, _grid and _stack base plane beyond the
objects on the plane. The default is 8.
_marginDepth int
The extra depth of a _bar, _grid and _stack base plane beyond the
objects on the plane. The default is 8.
_pipeLength int
Total length of a _pipe. The default is the value of _barHeight.
_scale real
The scale applied to the entire scene. This parameter may not be
used within any objects, only at the top of the configuration
file. The default is 1.0.
To simplify the specification of colors, a _colorList and a
_colorScale may be used to define colors for an object which has
metrics associated with it, i.e. _bar, _stack or _pipe. A color
list may be defined within an object, or named and defined at the top
of a configuration file. A named color list may then be referenced
within multiple objects:
_colorList name ( color [color...] )
Associate the colors with the color list name. The assignment of
colors to blocks depends on the type of an object. For example,
the color list called foo has the same color three times:
_colorList foo ( red rgbi:1.0/0.0/0.0 1.0 0.0 0.0 )
_colorScale name color ( color real [color real...] )
Associate the colors and reals with the color list name. The
initial color is the default color of the object. The object
will change color to the other colors when the normalized value
of the object is equal to or greater than each real. Therefore,
each real must be larger than the previous real, and should be in
the range 0.0 to 1.0. This scale gradually changes from blue to
red:
_colorScale coldToHot blue ( rgbi:0.5/0.0/1.0 0.3
purple 0.6
rgbi:1.0/0.0/0.5 0.8
red 0.95)
There are several different object types which could be found in a
pmview scene: _bar, _stack, _pipe, _grid, _link, and _label. There
is also _xing which is a special type of the _link. The _bar, _stack
and _pipe objects are modulated by metric values, a _label is fixed
text, _link and _xing are interconnects and a _grid is a container of
objects, including other _grid objects, which controls the layout of
the scene. A _grid object is only required if there are two or more
objects in the scene.
_bar, _grid and _stack objects may have base planes which provide a
point of reference for the blocks as they change height. A label can
be applied to the base plane _grid object if it is _shown with:
_baseLabel name|string
_baseLabel should be used within the scope of the relevant _bar,
_grid or _stack object. The first ``\n'' characters in the string
will be replaced by a new line. Subsequent ``\n'' characters will be
ignored.
For a scene to be valid it must contain at least one modulated
object.
The objects are defined as:
_bar [options] ( [metric-list] [color-list] [label-list] )
A _bar object represents a collection of blocks. The number of
blocks depends on the number of metrics and metric instances
assigned to the object. By default, the blocks are modulated by
changing the height of each block. Alternatively, blocks may be
modulated by changing color, or both height and color. Each
color in the color-list is assigned to each metric. Therefore,
multiple instances of the one metric will have the same color.
The options that may be passed to a _bar object are:
pos The position of the _bar object within the current _grid
object.
_col|_row
Position the blocks so that each instance is in a column
(_col) or a row (_row). This implies that each different
metric is in a separate row or column, respectively. The
default is _col.
_show|_hide
Is the base plane visible? Default is _show.
_ymod|_colormod|_colorymod
Modulate the blocks by adjusting their height (_ymod), color
(_colormod) or both height and color (_colorymod).
_cube|_cylinder
Set the shape of the blocks. The default is _cube.
_groupbymetric|_groupbyinst|_groupbyrow||groupbycol
Set the grouping of blocks when launching other tools. For
tools like pmchart(1) some views may generate many small
charts which cannot be drawn entirely within the screen.
Another problem is it may be more appropriate to generate
charts with the same instance in each chart, rather then the
same metric. The group specifiers control the algorithm used
so that a separate chart will be drawn for each _metrics
specification (_groupbymetric), for the first, second etc.
instance of each _metric (_groupbyinst), or by the rows and
columns of the _bar object depending on _row or _col. The
default is _groupbymetric.
The options must be specified in this order, although preceding
options are not required. Therefore, this is legal:
_bar _hide _cylinder ( ... )
The metrics, colors and labels are specified within the brackets
in any order. Only the metric-list is mandatory.
metric-list
A _bar metric list contains a list of metric names,
normalization values and an optional label for the metric:
_metrics ( metric real [string] [metric real [string]...] )
color-list
A _bar color list may be a named color list that was defined
earlier, or an unnamed color list. A _colorScale list should
be used when using _colormod or _colorymod modulation.
Therefore, the syntax for color lists within a _bar object
are any of:
_colorList name
_colorList ( color [color...] )
_colorScale name
_colorScale color ( color real [color real...] )
label-list
In addition to labels for each metric in the metric-list,
metric and instance labels may be defined using _metriclabels
and _instlabels statements. The position of the labels
around the _bar object depends on the _row or _col
orientation of metrics and instances, and whether the label
is read _towards the _bar object, or _away. The default is
_towards.
_metriclabels [_away|_towards] ( name|string [name|string...] )
_instlabels [_away|_towards] ( name|string
[name|string...] )
_grid [pos] [_show|_hide] ( objects )
A _grid object is a container for objects, including other _grid
objects. The rows and columns of a _grid object are resized to
the largest object in the row or column. If an object spans
multiple rows and/or columns, those rows and columns may be
partly resized to contain the object. However, the resizing of
rows and columns for objects occupying multiple rows and columns
occurs after resizing for objects occupying only one grid square.
A collision between objects occupying the same squares will be
reported as an error message and the later object will be
ignored.
The options to a _grid object control the position (pos) of the
_grid object in the parent _grid, and indicate whether to _show
or _hide the _grid base plane. By default, the base plane is
hidden.
The parameters described above may be specified within the
brackets of a _grid object, however they only apply to the
objects within the _grid, not the _grid itself. For a parameter
to be applied to a _grid object, it must be specified before the
_grid object declaration.
_label [options] string
A _label object draws the contexts of string at the location,
orientation and size specified in the options:
pos The position of the _label object in the current _grid
object.
_left|_right|_up|_down
The orientation of the string. The direction indicates the
direction the label is read. Therefore, _right is the
default since the string is read from left to right.
_small|_medium|_large
The font size. The default is _medium.
_link pos [string]
A _link object draws a straight or L-shaped horizontal round
``pipe'' with diameter equal to 80% of the _baseHeight of an
enclosing _grid. The properties of the object are defined by the
options:
pos sets both the position of the _link on the grid and its
shape. _link starts in the column and row on the _grid
specified by first two numbers in the pos and spans the
number of columns and rows set by the second two numbers. The
alignment value is used to decide the orientation of the link
(links are always aligned at the center): east and west links
are straight and going from left to right, north and south
links are straight and going from far end of the grid to near
end, northeast, northwest, southeast and southwest links are
L-shaped and connect the corresponding points of the compass,
i.e. a northeast link takes on the general shape of the Latin
letter ``L''.
string
sets the ``tag'' for the _link which will be displayed in the
text window when the pointer is over the link.
_pipe pos ( [metric-list] [color-list] [tag] )
A _pipe object represent a set of cylinders, placed on top of
each other and oriented parallel to the base plane. The diameter
of a _pipe is equal to 80% of _baseHeight. The number of blocks
is dependent on the number of metric instances in the metric-
list. The colors in the color-list are assigned in turn to each
cylinder in the _pipe. The length of the _pipe is defined by the
_pipeLength.
pos defines the position of the _pipe on the enclosing _grid and
its orientation with alignment field used to define at which
end of the pipe to stack the colored cylinders. The cylinders
are stacked at the corresponding point of the compass and the
pipe's direction is from the point of the compass towards the
center of the compass. Only east, west, north, and south are
valid values for the pipe's alignment.
The metrics, colors and label may be specified within the brackets in
any order. Only the metric-list is mandatory.
metric-list
A _pipe metric list contains a list of metric names and
normalization values:
_metrics ( metric real [metric real...] )
color-list
A _pipe color list may be named color list that was defined
earlier, or an unnamed color list:
_colorList name
_colorList ( color [color...] )
tag A _pipe may have a ``tag'' for the filler block (unanimated block
on the ``other'' end of the pipe) which will be displayed in the
text window when the pointer is over that end of the pipe.
_pipeTag name|string
_stack [options] ( [metric-list] [color-list] [label] )
A _stack object represents a set of blocks placed vertically on
top of each other. The number of blocks is dependent on the
number of metric instances in the metric-list. The colors in the
color-list are assigned to each block in the _stack. By default,
the height of the _stack will be the sum of the height of each
block. The options that may be passed to a _stack object are:
pos The position of the _stack object within the current _grid
object.
_show|_hide
Is the base plane visible? Default is _show.
_utilmod|_fillmod
Force the height of the stack to always be the maximum
height. This is achieved by normalizing the height of each
block (_utilmod), or by adding a grey block to the top of the
stack (_fillmod).
_cube|_cylinder
Set the shape of the blocks. The default is _cube.
The options must be specified in this order, although preceding
options are not required. Therefore, this is legal:
_stack 1 1 _north _utilmod ( ... )
The metrics, colors and label may be specified within the
brackets in any order. Only the metric-list is mandatory.
metric-list
A _stack metric list contains a list of metric names and
normalization values:
_metrics ( metric real [metric real...] )
color-list
A _stack color list may be named color list that was defined
earlier, or an unnamed color list:
_colorList name
_colorList ( color [color...] )
label
A _fillmod type _stack may have a label for the filler block:
_stackLabel name|string
_xing col row columns rows dir1 ... dir4
A _xing is a special kind of link which is used to draw a pair of
links which cross each other. To convey the visual impression
that the links do not join, one of the links is drawn as a
``broken'' cylinder. col and row define the position on the
enclosing grid. columns and rows define the size of the bounding
box. The end points of the crossing cylinders are placed exactly
in the center of the corner cells of the bounding box and four
small cylinders or stubs are used to join the perimeter of the
bounding box with the end points on the crossing cylinders. Four
dir values define the orientation of the stubs, starting at the
upper left corner of the _xing and proceeding clockwise, such
that respective stubs are used to join the point of the compass
with the center on the cell (see example).
This simple example illustrates the use of parameters and different
object types:
pmview Version 2.1
# Use a lighter grey for the base planes
_baseColor rgbi:0.5/0.5/0.5
# Define colors for CPU object
_colorList cpu ( blue2 red2 yellow2 cyan2 green2 )
# The top grid object, but hide it from view
_grid _hide (
# Show the current load in a bar object
_bar 0 0 (
_baseLabel "Load averages over a\n1, 5 and 15 minute interval"
_metrics (
kernel.all.load[1] 1 "1"
kernel.all.load[5] 1 "5"
kernel.all.load[15] 1 "15"
)
_colorList ( blue blue blue )
)
# Add a label below the load bars
_label 0 1 "Load"
# Change the color of the base plane for later objects
_baseColor pink
# Show the CPU usage over all CPUs in a utilization stack
_stack 2 0 _south _utilmod (
_baseLabel "CPU Utilization over all CPUs"
_metrics (
kernel.all.cpu.user 1000
kernel.all.cpu.sys 1000
kernel.all.cpu.intr 1000
kernel.all.cpu.wait.total 1000
kernel.all.cpu.idle 1000
)
_colorList cpu
)
# Add a label below the CPU stack
_label 2 1 "CPU"
# Create a separate grid for links and pipes
_marginWidth 1
_marginDepth 1
_gridSpace 12
_grid 0 3 5 4 _hide (
_pipeLength 12
_baseHeight 12
# Add a pipe and a link with western orientation
_pipe 0 0 west (
_pipeTag "West pipe"
_metrics (
kernel.all.cpu.user 1000
kernel.all.cpu.sys 1000
kernel.all.cpu.idle 1000
)
_colorList cpu
)
_link 0 2 west "West link"
# Add xing
_xing 1 0 3 3 west east east west
# Add a link and a pipe with eastern orientation
_pipe 4 0 east (
_pipeTag "East Pipe"
_metrics (
kernel.all.cpu.user 1000
kernel.all.cpu.sys 1000
kernel.all.cpu.idle 1000
)
_colorList cpu
)
_link 4 2 east "East link"
)
)
pmview(1).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page, or
you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a mail
to man-pages@man7.org
Performance Co-Pilot PMVIEW(5)
Pages that refer to this page: pmview(1)