1PMVIEW(5) File Formats Manual PMVIEW(5)
2
6 pmview - configuration file format for performance
7
9 This man page describes version 2.1 of the pmview configuration file
10 format.
11 The configuration format supports metrics from multiple hosts or ar‐
13 chives. A configuration file can specify metrics without a source,
14 with different hosts and different archives. However, a configuration
15 file that contains archives may only have one archive for anyone host.
16 When in ``replay'' mode, any metrics with host specific sources require
17 an archive to be specified for that host on the command line or as a
18 source to a previous metric. The archive must be the same archive
19 (based on a string comparison of the archive names) of any archives
20 specified in the configuration file for the same host.
21 The time controls will list all hosts that are specified on the command
23 line and the configuration file in the timezone listing (see
24 pmtime(1)).
25 The configuration file format is based on a two-dimensional grid which
27 can contain a variety of bars, stacks, links, pipes, labels and other
28 grids. The grids resize each column and row to match the size of the
29 largest item in that column or row. A configuration file that contains
30 only one object does not require a grid. The pmview configuration file
31 starts with an identification header in the first non-comment line:
32 pmview Version 2.1 [command_line]
34 The optional command_line should be the command line with which the
36 tool was launched, if the configuration file has been generated by
37 another tool. This is useful for applications that are to be restarted
38 automatically on the next login, after the user has logged out while
39 pmview was still running. Care should be taken to ensure that the com‐
40 mand specified is either a full pathname or will be found on the PATH
41 available at login.
42 All lines which begin with ``#'' are treated as comments and ignored.
44 Otherwise, all spaces, tabs and newlines are treated as white space so
45 multiple commands may be on the same line.
46 The syntax for specifying values in the configuration file is consis‐
48 tent for all commands, namely:
49 color
51 A color must be either a X(1) color name, a X(1) numerical color,
52 or three normalized real values representing the saturation of red,
53 green and blue. For example, the following colors are identical:
54 red
56 rgbi:1.0/0.0/0.0
57 1.0 0.0 0.0
58 int An integer.
60 metric
62 A metric consists of an optional source (host or archive), the met‐
63 ric name, an optional instance list immediately after name, fol‐
64 lowed by the maximum (or normalization value). A colon (``:'') is
65 used to separate a host name from the metric, and a forward slash
66 (``/'') to separate an archive name from the metric. Instances are
67 enclosed in square brackets and comma separated. Each instance may
68 be enclosed in quotes.
69 For example, some legal metrics are:
71 kernel.all.cpu.idle 4000
73 myhost:kernel.all.cpu.idle[cpu0,"cpu3"] 1000.0
74 /path/to/myarchive/kernel.all.cpu.idle[cpu1] 1000
75 To assist the process of matching instance names, two further com‐
77 parisons are made beyond a simple string comparison. If the
78 instance name contains spaces, only the first word in the instance
79 name is required to match the instance, assuming that the first
80 word is unique. If the first word is not unique, only the first
81 matching instance will be selected. The second comparison occurs
82 if the first word is a number with leading zeros. Any leading
83 zeros will be skipped before comparing the first word again. This
84 permits process ids used in the proc metrics to be easily matched,
85 without specifying the entire instance name. For example, to visu‐
86 alize the user and system time of init use the metric specification
87 proc.psusage.utime[1] 1000
89 proc.psusage.stime[1] 1000
90 name
92 A name for an object which may be referred to later in the configu‐
93 ration file. Names must be a single word consisting of all
94 alphanumeric characters, as well as underscores, dashes and colons.
95 It is recommended that names do not begin with an underscore as
96 this may be interpreted as a keyword.
97 pos This is the position of the object within the grid. The syntax of
99 a position is:
100 [ [x z] [ [width depth] [alignment] ] ]
102 x The horizontal coordinate (left to right) of the object,
104 starting at 0. The default x is 0.
105 z The vertical coordinate (top to bottom) of the object,
107 starting at 0. The default z is 0.
108 width The number of columns occupied by the object. The
110 default width is 1.
111 depth The number of rows occupied by the object. The default
113 depth is 1.
114 alignment
116 The edge or corner that the object is aligned with. Pos‐
117 sible alignments include: north, south, east, west,
118 northeast, northwest, southeast, southwest and center.
119 Abbreviations like se and SE are also accepted. The
120 default alignment is center.
121 The size of an object may not be known as the number of
123 instances for some metrics will vary between hosts and
124 PMDA configurations. Therefore, the position of the
125 object can be used to specify the likely size of the
126 object, so that the position of the surrounding objects
127 is appropriately adjusted.
128 The following are legal positions:
130 0 5 The object is centered at grid position 0,5 occu‐
132 pying 1 grid square.
133 1 2 north
135 The object is aligned with the north edge of posi‐
136 tion 1,2 occupying 1 grid square.
137 2 2 2 1 east
139 The object is aligned to the eastern edge of posi‐
140 tion 3,2 and occupies 2 grid squares (2,2 and
141 3,2).
142 string
144 A string is a series of characters enclosed in double quotes. A
145 string may not contain newlines or escaped double quotes.
146 There are several parameters that may affect the size, shape and color
149 of objects when they are displayed. These parameters are scoped so
150 that they only alter objects defined later in the same scope. There‐
151 fore, parameter settings at the top of a configuration file affect the
152 entire scene, unless they are changed later in the file. Most of these
153 parameters are also resources.
154 _barLength int
156 The side length of the _bar and _stack blocks. Default is 28.
157 _barHeight int
159 The maximum height of a _bar and _stack blocks. Default is 80.
160 _baseColor color
162 The color of _bar, _grid and _stack base planes. Default is
163 rgbi:0.15/0.15/0.15.
164 _baseHeight int
166 The height of _bar, _grid and _stack base planes. Default is 2.
167 _gapWidth int
169 The gap between blocks in a _bar object in the X-axis. The default
170 is 8.
171 _gapDepth int
173 The gap between blocks in a _bar object in the Z-axis. The default
174 is 8.
175 _gapLabel int
177 The gap between the base of a _bar object, and any metric or
178 instance labels. The default is 6.
179 _gridWidth int
181 The minimum width of a _grid column. The default is 20.
182 _gridDepth int
184 The minimum depth of a _grid row. The default is 20.
185 _labelMargin int
187 The margin around a _label object. The default is 5.
188 _labelColor color
190 The color of _label and _bar labels. The default is white.
191 _marginWidth int
193 The extra width of a _bar, _grid and _stack base plane beyond the
194 objects on the plane. The default is 8.
195 _marginDepth int
197 The extra depth of a _bar, _grid and _stack base plane beyond the
198 objects on the plane. The default is 8.
199 _pipeLength int
201 Total length of a _pipe. The default is the value of _barHeight.
202 _scale real
204 The scale applied to the entire scene. This parameter may not be
205 used within any objects, only at the top of the configuration file.
206 The default is 1.0.
207 To simplify the specification of colors, a _colorList and a _colorScale
209 may be used to define colors for an object which has metrics associated
210 with it, i.e. _bar, _stack or _pipe. A color list may be defined
211 within an object, or named and defined at the top of a configuration
212 file. A named color list may then be referenced within multiple
213 objects:
214 _colorList name ( color [color...] )
216 Associate the colors with the color list name. The assignment of
217 colors to blocks depends on the type of an object. For example,
218 the color list called foo has the same color three times:
219 _colorList foo ( red rgbi:1.0/0.0/0.0 1.0 0.0 0.0 )
221 _colorScale name color ( color real [color real...] )
224 Associate the colors and reals with the color list name. The ini‐
225 tial color is the default color of the object. The object will
226 change color to the other colors when the normalized value of the
227 object is equal to or greater than each real. Therefore, each real
228 must be larger than the previous real, and should be in the range
229 0.0 to 1.0. This scale gradually changes from blue to red:
230 _colorScale coldToHot blue ( rgbi:0.5/0.0/1.0 0.3
232 purple 0.6
233 rgbi:1.0/0.0/0.5 0.8
234 red 0.95)
235 There are several different object types which could be found in a
237 pmview scene: _bar, _stack, _pipe, _grid, _link, and _label. There is
238 also _xing which is a special type of the _link. The _bar, _stack and
239 _pipe objects are modulated by metric values, a _label is fixed text,
240 _link and _xing are interconnects and a _grid is a container of
241 objects, including other _grid objects, which controls the layout of
242 the scene. A _grid object is only required if there are two or more
243 objects in the scene.
244 _bar, _grid and _stack objects may have base planes which provide a
246 point of reference for the blocks as they change height. A label can
247 be applied to the base plane _grid object if it is _shown with:
248 _baseLabel name|string
250 _baseLabel should be used within the scope of the relevant _bar, _grid
252 or _stack object. The first ``\n'' characters in the string will be
253 replaced by a new line. Subsequent ``\n'' characters will be ignored.
254 For a scene to be valid it must contain at least one modulated object.
256 The objects are defined as:
258 _bar [options] ( [metric-list] [color-list] [label-list] )
260 A _bar object represents a collection of blocks. The number of
261 blocks depends on the number of metrics and metric instances
262 assigned to the object. By default, the blocks are modulated by
263 changing the height of each block. Alternatively, blocks may be
264 modulated by changing color, or both height and color. Each color
265 in the color-list is assigned to each metric. Therefore, multiple
266 instances of the one metric will have the same color. The options
267 that may be passed to a _bar object are:
268 pos The position of the _bar object within the current _grid
270 object.
271 _col|_row
273 Position the blocks so that each instance is in a column (_col)
274 or a row (_row). This implies that each different metric is in
275 a separate row or column, respectively. The default is _col.
276 _show|_hide
278 Is the base plane visible? Default is _show.
279 _ymod|_colormod|_colorymod
281 Modulate the blocks by adjusting their height (_ymod), color
282 (_colormod) or both height and color (_colorymod).
283 _cube|_cylinder
285 Set the shape of the blocks. The default is _cube.
286 _groupbymetric|_groupbyinst|_groupbyrow||groupbycol
288 Set the grouping of blocks when launching other tools. For
289 tools like pmchart(1) some views may generate many small charts
290 which cannot be drawn entirely within the screen. Another
291 problem is it may be more appropriate to generate charts with
292 the same instance in each chart, rather then the same metric.
293 The group specifiers control the algorithm used so that a sepa‐
294 rate chart will be drawn for each _metrics specification
295 (_groupbymetric), for the first, second etc. instance of each
296 _metric (_groupbyinst), or by the rows and columns of the _bar
297 object depending on _row or _col. The default is _groupbymet‐
298 ric.
299 The options must be specified in this order, although preceding
301 options are not required. Therefore, this is legal:
302 _bar _hide _cylinder ( ... )
304 The metrics, colors and labels are specified within the brackets in
306 any order. Only the metric-list is mandatory.
307 metric-list
309 A _bar metric list contains a list of metric names, normaliza‐
310 tion values and an optional label for the metric:
311 _metrics ( metric real [string] [metric real [string]...] )
313 color-list
316 A _bar color list may be a named color list that was defined
317 earlier, or an unnamed color list. A _colorScale list should
318 be used when using _colormod or _colorymod modulation. There‐
319 fore, the syntax for color lists within a _bar object are any
320 of:
321 _colorList name
323 _colorList ( color [color...] )
324 _colorScale name
325 _colorScale color ( color real [color real...] )
326 label-list
328 In addition to labels for each metric in the metric-list, met‐
329 ric and instance labels may be defined using _metriclabels and
330 _instlabels statements. The position of the labels around the
331 _bar object depends on the _row or _col orientation of metrics
332 and instances, and whether the label is read _towards the _bar
333 object, or _away. The default is _towards.
334 _metriclabels [_away|_towards] ( name|string [name|string...] )
336 _instlabels [_away|_towards] ( name|string
337 [name|string...] )
338 _grid [pos] [_show|_hide] ( objects )
341 A _grid object is a container for objects, including other _grid
342 objects. The rows and columns of a _grid object are resized to the
343 largest object in the row or column. If an object spans multiple
344 rows and/or columns, those rows and columns may be partly resized
345 to contain the object. However, the resizing of rows and columns
346 for objects occupying multiple rows and columns occurs after resiz‐
347 ing for objects occupying only one grid square.
348 A collision between objects occupying the same squares will be
350 reported as an error message and the later object will be ignored.
351 The options to a _grid object control the position (pos) of the
353 _grid object in the parent _grid, and indicate whether to _show or
354 _hide the _grid base plane. By default, the base plane is hidden.
355 The parameters described above may be specified within the brackets
357 of a _grid object, however they only apply to the objects within
358 the _grid, not the _grid itself. For a parameter to be applied to
359 a _grid object, it must be specified before the _grid object decla‐
360 ration.
361 _label [options] string
364 A _label object draws the contexts of string at the location, ori‐
365 entation and size specified in the options:
366 pos The position of the _label object in the current _grid object.
368 _left|_right|_up|_down
370 The orientation of the string. The direction indicates the
371 direction the label is read. Therefore, _right is the default
372 since the string is read from left to right.
373 _small|_medium|_large
375 The font size. The default is _medium.
376 _link pos [string]
379 A _link object draws a straight or L-shaped horizontal round
380 ``pipe'' with diameter equal to 80% of the _baseHeight of an
381 enclosing _grid. The properties of the object are defined by the
382 options:
383 pos sets both the position of the _link on the grid and its shape.
386 _link starts in the column and row on the _grid specified by
387 first two numbers in the pos and spans the number of columns
388 and rows set by the second two numbers. The alignment value is
389 used to decide the orientation of the link (links are always
390 aligned at the center): east and west links are straight and
391 going from left to right, north and south links are straight
392 and going from far end of the grid to near end, northeast,
393 northwest, southeast and southwest links are L-shaped and con‐
394 nect the corresponding points of the compass, i.e. a northeast
395 link takes on the general shape of the Latin letter ``L''.
396 string
398 sets the ``tag'' for the _link which will be displayed in the
399 text window when the pointer is over the link.
400 _pipe pos ( [metric-list] [color-list] [tag] )
404 A _pipe object represent a set of cylinders, placed on top of each
405 other and oriented parallel to the base plane. The diameter of a
406 _pipe is equal to 80% of _baseHeight. The number of blocks is
407 dependent on the number of metric instances in the metric-list.
408 The colors in the color-list are assigned in turn to each cylinder
409 in the _pipe. The length of the _pipe is defined by the _pipe‐
410 Length.
411 pos defines the position of the _pipe on the enclosing _grid and
414 its orientation with alignment field used to define at which
415 end of the pipe to stack the colored cylinders. The cylinders
416 are stacked at the corresponding point of the compass and the
417 pipe's direction is from the point of the compass towards the
418 center of the compass. Only east, west, north, and south are
419 valid values for the pipe's alignment.
420 The metrics, colors and label may be specified within the brackets in
422 any order. Only the metric-list is mandatory.
423 metric-list
425 A _pipe metric list contains a list of metric names and normaliza‐
426 tion values:
427 _metrics ( metric real [metric real...] )
429 color-list
432 A _pipe color list may be named color list that was defined ear‐
433 lier, or an unnamed color list:
434 _colorList name
436 _colorList ( color [color...] )
437 tag A _pipe may have a ``tag'' for the filler block (unanimated block
440 on the ``other'' end of the pipe) which will be displayed in the
441 text window when the pointer is over that end of the pipe.
442 _pipeTag name|string
444 _stack [options] ( [metric-list] [color-list] [label] )
447 A _stack object represents a set of blocks placed vertically on top
448 of each other. The number of blocks is dependent on the number of
449 metric instances in the metric-list. The colors in the color-list
450 are assigned to each block in the _stack. By default, the height
451 of the _stack will be the sum of the height of each block. The
452 options that may be passed to a _stack object are:
453 pos The position of the _stack object within the current _grid
455 object.
456 _show|_hide
458 Is the base plane visible? Default is _show.
459 _utilmod|_fillmod
461 Force the height of the stack to always be the maximum height.
462 This is achieved by normalizing the height of each block
463 (_utilmod), or by adding a grey block to the top of the stack
464 (_fillmod).
465 _cube|_cylinder
467 Set the shape of the blocks. The default is _cube.
468 The options must be specified in this order, although preceding
470 options are not required. Therefore, this is legal:
471 _stack 1 1 _north _utilmod ( ... )
473 The metrics, colors and label may be specified within the brackets
475 in any order. Only the metric-list is mandatory.
476 metric-list
478 A _stack metric list contains a list of metric names and nor‐
479 malization values:
480 _metrics ( metric real [metric real...] )
482 color-list
485 A _stack color list may be named color list that was defined
486 earlier, or an unnamed color list:
487 _colorList name
489 _colorList ( color [color...] )
490 label
493 A _fillmod type _stack may have a label for the filler block:
494 _stackLabel name|string
496 _xing col row columns rows dir1 ... dir4
499 A _xing is a special kind of link which is used to draw a pair of
500 links which cross each other. To convey the visual impression that
501 the links do not join, one of the links is drawn as a ``broken''
502 cylinder. col and row define the position on the enclosing grid.
503 columns and rows define the size of the bounding box. The end
504 points of the crossing cylinders are placed exactly in the center
505 of the corner cells of the bounding box and four small cylinders or
506 stubs are used to join the perimeter of the bounding box with the
507 end points on the crossing cylinders. Four dir values define the
508 orientation of the stubs, starting at the upper left corner of the
509 _xing and proceeding clockwise, such that respective stubs are used
510 to join the point of the compass with the center on the cell (see
511 example).
512
514 This simple example illustrates the use of parameters and different
515 object types:
516 pmview Version 2.1
518 # Use a lighter grey for the base planes
519 _baseColor rgbi:0.5/0.5/0.5
520 # Define colors for CPU object
522 _colorList cpu ( blue2 red2 yellow2 cyan2 green2 )
523 # The top grid object, but hide it from view
525 _grid _hide (
526 # Show the current load in a bar object
528 _bar 0 0 (
529 _baseLabel "Load averages over a\n1, 5 and 15 minute interval"
530 _metrics (
531 kernel.all.load[1] 1 "1"
532 kernel.all.load[5] 1 "5"
533 kernel.all.load[15] 1 "15"
534 )
535 _colorList ( blue blue blue )
536 )
537 # Add a label below the load bars
539 _label 0 1 "Load"
540 # Change the color of the base plane for later objects
542 _baseColor pink
543 # Show the CPU usage over all CPUs in a utilization stack
545 _stack 2 0 _south _utilmod (
546 _baseLabel "CPU Utilization over all CPUs"
547 _metrics (
548 kernel.all.cpu.user 1000
549 kernel.all.cpu.sys 1000
550 kernel.all.cpu.intr 1000
551 kernel.all.cpu.wait.total 1000
552 kernel.all.cpu.idle 1000
553 )
554 _colorList cpu
555 )
556 # Add a label below the CPU stack
558 _label 2 1 "CPU"
559 # Create a separate grid for links and pipes
561 _marginWidth 1
562 _marginDepth 1
563 _gridSpace 12
564 _grid 0 3 5 4 _hide (
565 _pipeLength 12
566 _baseHeight 12
567 # Add a pipe and a link with western orientation
569 _pipe 0 0 west (
570 _pipeTag "West pipe"
571 _metrics (
572 kernel.all.cpu.user 1000
573 kernel.all.cpu.sys 1000
574 kernel.all.cpu.idle 1000
575 )
576 _colorList cpu
577 )
578 _link 0 2 west "West link"
580 # Add xing
582 _xing 1 0 3 3 west east east west
583 # Add a link and a pipe with eastern orientation
585 _pipe 4 0 east (
586 _pipeTag "East Pipe"
587 _metrics (
588 kernel.all.cpu.user 1000
589 kernel.all.cpu.sys 1000
590 kernel.all.cpu.idle 1000
591 )
592 _colorList cpu
593 )
594 _link 4 2 east "East link"
595 )
596 )
597
599 pmview(1).
600Performance Co-Pilot PMVIEW(5)