Provided by: pcp-gui_5.3.6-1build1_amd64 
NAME
pmchart - strip chart tool for Performance Co-Pilot
SYNOPSIS
pmchart [-CLVWz?] [-a archive] [-A align] [--archive-folio folio] [-c configfile] [-f
fontfamily] [-F fontsize] [-g geometry] [-h host] [-n pmnsfile] [-o outfile] [-O offset]
[-p port] [-s samples] [-S starttime] [-t interval] [-T endtime] [-v visible] [-Z
timezone] [-geometry geometry] [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 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
The available command line options are:
-a archive, --archive=archive
Performance metric values are retrieved from the set of Performance Co-Pilot (PCP)
archive logs identified by this option, by default. The argument is a comma-
separated list of names, each of which may be the base name of an archive or the name
of a directory containing one or more archives. The resulting set of archives will
be the source of the performance metrics. The initial Tab created will be an archive
mode Tab. Multiple -a options can be presented, and the resulting list of sets of
archives is used for sourcing metric values. Any sources listed on the command line
are assumed to be sets of archives if this option is used.
-A align, --align=align
Force the initial sample to be aligned on the boundary of a natural time unit align.
Refer to PCPIntro(1) for a complete description of the syntax for align.
--archive-folio=folio
Read metric source archives from the PCP archive folio.
-c configfile, --view=configfile
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, --check
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.
-f family, --font-family=family
Specify the default font family to be used in several chart components, such as the
chart title, legend, and Y-axis label. The default value is "Sans Serif". This
setting does not affect the rest of the user interface, where the value is inherited
from the environment in which pmchart operates, and differs according to the look-
and-feel of each platform.
-F point, --font-size=point
Specify the default font point size to be used in several chart components, such as
the chart title, legend, and Y-axis label. The default is platform dependent, but is
either 7, 8 or 9. This setting does not affect the rest of the user interface.
-g geometry, --geometry=geometry
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). When NOT using the -o
flag, to specify the display window geometry, use -geometry geometry where geometry
specifies the desired window width, height and optional placement.
-h host, --host=host
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.
-H path, --hostsfile=path
Specify the path to a file containing a set of hostnames where pmcd(1) is running ,
rather than using the default localhost.
-K spec, --spec-local=spec
When fetching metrics from a local context (see -L), the -K option may be used to
control the DSO PMDAs that should be made accessible. The spec argument conforms to
the syntax described in pmSpecLocalPMDA(3). More than one -K option may be used.
-L, --local-PMDA
Use a local context to collect metrics from DSO PMDAs on the local host without PMCD.
See also -K.
-n pmnsfile, --namespace=pmnsfile
Load an alternative Performance Metrics Name Space (PMNS(5)) from the file pmnsfile.
-o outfile, --output=outfile
Generate an image file named outfile, and then exit. This is most useful when run
with a set of archives 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.
-O origin, --origin=origin
When reporting archived metrics, start reporting at origin within the time window
(see -S and -T). Refer to PCPIntro(1) for a complete description of the syntax for
origin.
-p port, --guiport=port
port number for connection to an existing pmtime time control process.
-s samples, --samples=samples
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.
-S starttime, --start=starttime
When reporting archived metrics, the report will be restricted to those records
logged at or after starttime. Refer to PCPIntro(1) for a complete description of the
syntax for starttime.
-t interval, --interval=interval
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).
-T endtime, --finish=endtime
When reporting archived metrics, the report will be restricted to those records
logged before or at endtime. Refer to PCPIntro(1) for a complete description of the
syntax for endtime.
-v samples, --visible=samples
Sets the initial 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).
-V, --version
Display pmchart version number and exit
-W, fB--white
Export images using an opaque(white) background
-z, --hostzone
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.
-Z timezone, --timezone=timezone
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(7).
-?, --help
Display usage message and exit.
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 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.
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 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.
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 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).
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 Record→Start
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 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.
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.
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(5).
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
PCPIntro(1), pmafm(1), pmconfirm(1), pmdumptext(1), pminfo(1), pmrep(1), pmtime(1),
pmval(1), pcp.conf(5) and PMNS(5).