---

   pmchart    ( 1 )

---

Синтаксис конфигурационного файла (Configuration file syntax)

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.