Metric values can be sourced from one or more live hosts (simultaneously). Alternatively, one or more sets of PCP archives can be used as a source of historical data. See PCPIntro (1) for an in-depth discussion of the capabilities of the PCP framework, many of which are used by pmchart.
Many aspects of the behaviour of pmchart can be customised through the interface. In particular, the use of "views" (refer to the section describing VIEWS later in this document) allows predefined sets of metrics and charting parameters like colors, scaling, titles, legends, and so on to be stored for later use, or use with different hosts and sets of archives. In addition, the Preferences dialog allows customisations to the rest of the pmchart user interface to be saved and restored between different invocations of the tool. This allows the default background color, highlight color, contents and location of the toolbar, and many other aspects to be configured.
pmchart makes extensive use of the pmtime (1) utility for time control, refer to the pmtime manual page for further details of its operation.
Options which control the default source, timing and layout of the pmchart window are as follows:
The -S , -T , -O and -A options may be used to define a time window to restrict the samples retrieved, set an initial origin within the time window, or specify a "natural" alignment of the sample times; refer to PCPIntro (1) for a complete description of these options.
From a conceptual point of view, there are two classes of view. These views share the same configuration file format - refer to a later section for a complete description of this format. 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 privileges, 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.
Each Tab has a mode of operation (either live or archive - pmchart can support both modes simultaneously), the total number of samples and currently visible points, and a label describing the Tab which is displayed at the top of the pmchart window. New Tabs can be created using the File→Add Tab dialog.
In order to save on vertical screen real estate, note that the user interface element for changing between different Tabs (and its label) are only displayed when more than one Tab exists. A Tab can be dismissed using the File→Close Tab menu, which removes the current Tab and any charts it contained.
When the intended display device is the screen, the File→Export menu option should be used. This allows exporting the charts in a variety of image formats, including PNG, JPEG, GIF, and BMP. The image size can be scaled up or down in any dimension.
Alternatively, when the intended display device is paper, the File→Print menu option can be used. This supports the usual set of printing options (choice of printer, grayscale/color, landscape/portrait, scaling to different paper sizes, etc), and in addition allows printing to the intermediate printer formats of PostScript and Portable Document Format (PDF).
pmchart produces recordings that are compatible with the PCP pmafm (1) replay mechanism, for later playback via a new instance of pmchart . In addition, when recording through pmchart one can also replay the recording immediately, as on termination of the recording (through the Record→Stop menu item), an archive mode Tab will be created with the captured view.
Once recording is active in a Live Tab, the Time Control status button in the bottom left corner of the pmchart window is displayed with a distinctive red dot. At any time during a pmchart recording session, the amount of space used in the filesystem by that recording can be displayed using the Record→Query menu item.
Finally, the Record→Detach menu option provides a mechanism whereby the recording process can be completely divorced from the running pmchart process, and allowed to continue on when pmchart exits. A dialog displaying the current size and estimated rate of growth for the recording is presented. On the other hand, if pmchart is terminated while recording is in process, then the recording process will prompt the user to choose immediate cessation of recording or for it to continue on independently.
All of the record mode services available from pmchart are implemented with the assistance of the base Performance Co-Pilot logging services - refer to pmlogger (1) and pmafm (1) for an extensive description of the capabilities of these tools.
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.
#kmchart
although
pmchart
provides backwards compatibility for the older
pmchart
view formats with an initial line of
#pmchart
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.
host literal
or
host dynamic
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.
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,
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 (").
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.
Of particular note, the $PCP_XCONFIRM_PROG setting is explicitly and unconditionally overridden by pmchart. This is set to the pmconfirm (1), utility, in order that some popup dialogs (particularly in the area of Recording) maintain a consistent look-and-feel with the rest of the pmchart application.