pmchart loads predefined chart configurations (or "views") from
external files that conform to the following rules. In the
descriptions below keywords (shown in bold) may appear in upper,
lower or mixed case, elements shown in [stuff] are optional, and
user-supplied elements are shown as <other stuff>. A vertical
bar (|) is used where syntactic elements are alternatives.
Quotes (") may be used to enclose lexical elements that may
contain white space, such as titles, labels and instance names.
1. The first line defines the configuration file type and should
be
#kmchart
although pmchart provides backwards compatibility for the
older pmchart view formats with an initial line of
#pmchart
2. After the first line, lines beginning with "#" as the first
non-white space character are treated as comments and skipped.
Similarly blank lines are skipped.
3. The next line should be
version <n> <host-clause>
where <n> depends on the configuration file type, and is 1 for
pmchart else 1.1, 1.2 or 2.0 for pmchart.
The <host-clause> part is optional (and ignored) for pmchart
configuration files, but required for the pmchart
configuration files, and is of the form
host literal
or
host dynamic
4. A configuration contains one or more charts defined as
follows:
chart [title <title>] style <style> <options>
If specified, the title will appear centred and above the
graph area of the chart. The <title> is usually enclosed in
quotes (") and if it contains the sequence "%h" this will be
replaced by the short form of the hostname for the default
source of metrics at the time this chart was loaded.
Alternatively, "%H" can be used to insert the full host name.
If the hostname appears to be an inet or IPv6 address, no
shortening will be attempted; it will be used as-is in both
replacement cases. After the view is loaded, the title
visibility and setting can be manipulated using the Chart
Title text box in the Edit→Chart dialog.
The <style> controls the initial plotting style of the chart,
and should be one of the keywords plot (line graph), bar,
stacking (stacked bar), area or utilization. After the view
is loaded, the plotting style can be changed using the
Edit→Chart Style dropdown list.
The <options> are zero or more of the optional elements:
[scale [from] <ymin> [to] <ymax>] [legend <onoff>]
If scale is specified, the vertical scaling is set for all
plots in the chart to a y-range defined by <ymin> and <ymax>.
Otherwise the vertical axis will be autoscaled based on the
values currently being plotted.
<onoff> is one of the keywords on or off and the legend clause
controls the presence or absence of the plot legend below the
graph area. The default is for the legend to be shown. After
the view is loaded, the legend visibility can be toggled using
the Show Legend button in the Edit→Chart dialog.
5. pmchart supports a global clause to specify the dimensions of
the top-level window (using the width and height keywords),
the number of visible points (points keyword) and the starting
X and Y axis positions on the screen (xpos and ypos keywords).
Each of these global attributes takes an integer value as the
sole qualifier.
6. Each chart has one or more plots associated with it, as
defined by one of the following specifications:
plot
[legend <title>] [color <colorspec>] [host <hostspec>]
metric <metricname>
[ instance <inst> | matching <pat> | not-matching <pat> ]
The keyword plot may be replaced with the keyword optional-
plot, in which case if the source of performance data does not
include the specified performance metric and/or instance, then
this plot is silently dropped from the chart.
If specified, the title will appear in the chart legend. The
<title> is usually enclosed in quotes (") and it may contain
one or more wildcard characters which will be expanded using
metric name, instance name, and host name for the plot. The
wildcards are "%i" (short unique instance name, up to the
first whitespace), "%I" (full instance name), "%h" (short host
name, up to the first dot), %H (full host name), "%m" (metric
name shortened to the final two PMNS components), and "%M"
(full metric name).
For older pmchart configuration files, the keyword title must
be used instead of legend. Nowadays pmchart supports either
keyword.
The color clause is optional for newer pmchart configuration
files, but it was mandatory in the original pmchart
configuration file format. <colorspec> may be one of the
following:
#-cycle
rgbi:rr:gg:bb
#rgb
#rrggbb
#rrrgggbbb
#rrrrggggbbbb
<Xcolor>
where each of r, g and b are hexadecimal digits (0-9 and A-F)
representing respectively the red, green and blue color
components. <Xcolor> is one of the color names from the X
color database, e.g. red or steelblue, see also the output
from showrgb(1).
The "color" #-cycle specifies that pmchart should use the next
in a pallet of colors that it uses cyclically for each chart.
This is the default if the color clause is omitted.
The <hostspec> in the host clause may be a hostname, an IP
address or an asterisk (*); the latter is used to mean the
default source of performance metrics. For older pmchart
configuration files, the host clause must be present, for new
pmchart configuration files it is optional, and if missing the
default source of performance metrics will be used.
The optional instance specification,
(a)
is omitted in which case one plot will be created for every
instance of the <metricname> metric
(b)
starts with instance, in which case only the instance named
<inst> will be plotted
(c)
starts with matching, in which case all instances whose
names match the pattern <pat> will be plotted; the pattern
uses extended regular expression notation in the style of
egrep(1) (refer to the PMCD view for an example)
(d)
starts with not-matching, in which case all instances whose
names do not match the pattern <pat> will be plotted; the
pattern uses extended regular expression notation in the
style of egrep(1) (refer to the Netbytes view for an
example)
pmchart uses a bizarre syntactic notation where <inst> and
<pat> extend from the first non-white space character to the
end of the input line. For pmchart configuration files these
elements are either delimited by white space, or enclosed in
quotes (").
7. The optional tab directive can be used to create views with
multiple charts which span multiple Tabs. The syntax is as
follows:
tab <label> [host <host>] [points <points> [samples <samples>]]
All chart specifications following this keyword will be created
on the new Tab, until the end of the configuration file or until
another tab keyword is encountered.
