NAME
pmchart, kmchart - strip chart tool for Performance Co-Pilot
SYNOPSIS
pmchart [-CVWz] [-A align] [-a archive] [-c configfile] [-g geometry]
[-h host] [-o outfile] [-O offset] [-p port] [-s samples] [-S
starttime] [-T endtime] [-t interval] [-v visible] [-Z timezone]
[sources...]
DESCRIPTION
pmchart is a graphical utility that plots performance metrics values
available through the facilities of the Performance Co-Pilot (PCP).
Multiple charts can be displayed simultaneously, either aligned on the
unified time axis (X-axis), and through the use of multiple interface
Tabs.
Metric values can be sourced from one or more live hosts
(simultaneously). Alternatively, one or more 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
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:
-a Performance metric values are retrieved from the Performance Co-
Pilot (PCP) archive log file identified by the base name archive,
by default. The initial Tab created will be an archive mode Tab.
Multiple -a options can be presented, and the list of archives is
used for sourcing metric values. Any sources listed on the
command line are assumed to be archives if this option is used.
-c configfile specifies an initial view to load, using the default
source of metrics. Multiple -c views can be specified, and they
will all be opened in the default Tab with the default source of
metrics.
-C Used with -c, the view(s) are parsed, any errors are reported, and
the tool exits. This is primarily intended for testing purposes.
If a second -C option is presented, pmchart also connects to
pmcd(1) to check the semantics of metrics.
-g Generate image with the specified geometry (width and height).
This option is only useful when used in conjunction with the -o
option for generating an output image. The geometry argument
takes the form "WxH" (e.g. 240x120).
-h Current performance metric values are retrieved from the nominated
host machine by default. Multiple -h options can be presented,
and the list of hosts is used for sourcing metric values. Any
sources listed on the command line are assumed to be hosts if this
option is used.
-o Generate an image file named outfile, and then exit. This is most
useful when run with an archive and one or more views. The
generated image will be in the format specified as the file
extension (automatically determined from outfile). If no
extension can be determined, then the GIF format is used and the
generated file is named with this extension. The supported image
file formats include: bmp, jpeg, jpg, png, ppm, tif, tiff, xbm,
and xpm.
-p port number for connection to an existing pmtime time control
process.
-s Specifies the number of samples that will be retained before
discarding old data (replaced by new values at the current time
position). This value can subsequently be modified through the
Edit Tab dialog.
-t Sets the inital update interval to something other than the
default 1 second. The interval argument follows the syntax
described in PCPIntro(1), and in the simplest form may be an
unsigned integer (the implied units in this case are seconds).
-v Sets the inital visible samples that will be displayed in all
charts in the default Tab. This value must be less than or equal
to the total number of samples retained (the -s value).
-Z By default, pmtime reports the time of day according to the local
timezone on the system where pmchart is run. The -Z option
changes the timezone to timezone in the format of the environment
variable TZ as described in environ(5).
-z Change the reporting timezone to the local timezone at the host
that is the source of the performance metrics, as identified via
either the -h or -a options.
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.
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 - 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 FileOpen 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 FileSave View dialog. This is a mechanism for
individual users to save their commonly used views. Access to these
views is achieved through the FileOpen 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.
TABS
pmchart provides the common user interface concept of the Tab, which is
most prevalent in modern web browsers. Tabs allow pmchart to update
many more charts than the available screen real estate allows, by
providing a user interface mechanism to stack (and switch between)
different vertical sets of charts. Switching between Tabs is achieved
by clicking on the Tab labels, which are located along the top of the
display beneath the Menu and Tool bars).
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 FileAdd 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 FileClose Tab menu, which removes the current Tab
and any charts it contained.
IMAGES and PRINTING
A static copy of the currently displayed vertical series of charts can
be captured in two ways.
When the intended display device is the screen, the FileExport 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
FilePrint 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).
RECORDING
It is possible to make a recording of a set of displayed charts, for
later playback through pmchart or any of the other Performance Co-Pilot
tools. The RecordStart functionality is simple to configure through
the user interface, and allows fine-tuning of the recording process
(including record frequencies that differ to the pmchart update
interval, alternate file locations, etc).
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
RecordStop 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 RecordQuery menu item.
Finally, the RecordDetach 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.
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. After the view is loaded, the title
visibility and setting can be manipulated using the Chart Title text
box in the EditChart 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 EditChart Style dropdown
list.
The <options> are zero or more of the optional elements:
[scale [from] <ymin> [to] <ymax>] [legend <onoff>]
If scale is specfied, 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 EditChart 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 if it contains the
sequence "%i" this will be replaced by the metric instance name (if
any).
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 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).
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.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the
file and directory names used by PCP. On each installation, the file
/etc/pcp.conf contains the local values for these variables. The
$PCP_CONF variable may be used to specify an alternative configuration
file, as described in pcp.conf(4).
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.
SEE ALSO
pmtime(1), pmconfirm(1), pmdumptext(1), PCPIntro(1), pmafm(1),
pmval(1), pmcd(1), pminfo(1), pcp.conf(4), pcp.env(4) and pmns(4).