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 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 "#ff0000" 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 ( "#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:

_bar _hide _cylinder ( ... )

_metrics ( metric real [string] [metric real [string]...] )

_colorList name
_colorList ( color [color...] )
_colorScale name
_colorScale color ( color real [color real...] )

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

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

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

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:

_stack 1 1 _north _utilmod ( ... )

_metrics ( metric real [metric real...] )

_colorList name
_colorList ( color [color...] )

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

SEE ALSO

pmview(1).