Views

The primary pmchart configuration file is the "view", which allows the metadata associated with one or more charts to be saved in the filesystem. This metadata describes all aspects of the charts, including which PCP metrics and instances are to be used, which hosts, which colors, the chart titles, use of chart legends, and much more.

From a conceptual point of view, there are two classes of view. These views share the same configuration file format, described below. The differences lie in where they are installed and how they are manipulated.

The first class, the "system" view, is simply any view that is installed as part of the pmchart package. These are stored in $PCP_VAR_DIR/config/pmchart. When the File→Open View dialog is displayed, it is these views that are initially listed. The system views cannot be modified by a normal user, and should not be modified even by a user with suitable priviledges, as they will be overwritten during an upgrade.

The second class of view is the "user" view. These views are created on-the-fly using the File→Save View dialog. This is a mechanism for individual users to save their commonly used views. Access to these views is achieved through the File→Open View dialog, as with the system views. Once the dialog is opened, the list of views can be toggled between user and system views by clicking on the two toggle buttons in the top right corner. User views are stored in $HOME/.pcp/pmchart.

The current pmchart configuration file syntax has evolved from the original SGI pmchart syntax.

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 as [stuff] are optional, and user-supplied elements are shown as . 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.

The first line defines the configuration file type and should be
```
    #kmchart
```
although pmchart provides backwards compatibility for original SGI pmchart formats with an initial line of
```
    #pmchart
```
After the first line, lines beginning with "#" as the first non-whitespace character are treated as comments and skipped. Similarly blank lines are skipped.
The next line should be
```
    version <n> 
```
where <n> depends on the configuration file type, and is 1 for kmchart 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 older pmchart configuration files, and is of the form
```
    host literal
```
or
```
    host dynamic
```
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. 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 <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.
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.
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 if it contains the sequence "%i" this will be replaced by the metric instance name (if any).
For pmchart configuration files, the keyword title must be used instead of legend. pmchart supports either keyword.
The color clause is optional for new pmchart configuration files, but it is mandatory for older pmchart configuration files. <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 hexidecimal 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) on X11 platforms.
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 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,
1. is omitted in which case one plot will be created for every instance of the <metricname> metric
2. starts with instance, in which case only the instance named will be plotted
3. 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)
4. 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)
  The original pmchart syntax uses a bizarre notation where <inst> and <pat> extend from the first non-white space character to the end of the input line. For modern pmchart configuration files these elements are either delimited by white space, or enclosed in quotes (").
The optional tab directive can be used to create views with multiple charts which span multiple Tabs. The synax 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.