1PMCHART(1)                  General Commands Manual                 PMCHART(1)
2
3
4

NAME

6       pmchart - strip chart tool for Performance Co-Pilot
7

SYNOPSIS

9       pmchart [-CVWz] [-A align] [-a archive] [-c configfile] [-f fontfamily]
10       [-F fontsize] [-g geometry] [-h host]  [-o  outfile]  [-O  offset]  [-p
11       port]  [-s samples] [-S starttime] [-T endtime] [-t interval] [-v visi‐
12       ble] [-Z timezone] [-geometry geometry] [sources...]
13

DESCRIPTION

15       pmchart is a graphical utility that plots  performance  metrics  values
16       available  through  the  facilities  of the Performance Co-Pilot (PCP).
17       Multiple charts can be displayed simultaneously, either aligned on  the
18       unified  time  axis (X-axis), and through the use of multiple interface
19       Tabs.
20
21       Metric values can be sourced from one or more  live  hosts  (simultane‐
22       ously).  Alternatively, one or more sets of PCP archives can be used as
23       a source of historical data.  See PCPIntro(1) for an  in-depth  discus‐
24       sion  of  the capabilities of the PCP framework, many of which are used
25       by pmchart.
26
27       Many aspects of the behaviour of pmchart can be customised through  the
28       interface.   In  particular,  the  use of "views" (refer to the section
29       describing VIEWS later in this document) allows predefined sets of met‐
30       rics and charting parameters like colors, scaling, titles, legends, and
31       so on to be stored for later use, or use with different hosts and  sets
32       of archives.  In addition, the Preferences dialog allows customisations
33       to the rest of the pmchart user interface  to  be  saved  and  restored
34       between  different  invocations  of  the tool.  This allows the default
35       background color, highlight color, contents and location of  the  tool‐
36       bar, and many other aspects to be configured.
37
38       pmchart  makes extensive use of the pmtime(1) utility for time control,
39       refer to the pmtime manual page for further details of its operation.
40
41       Options which control the default source,  timing  and  layout  of  the
42       pmchart window are as follows:
43
44       -a   Performance  metric  values  are retrieved from the set of Perfor‐
45            mance Co-Pilot (PCP) archive logs identified by  this  option,  by
46            default.  The argument is a comma-separated list of names, each of
47            which may be the base name of an archive or the name of  a  direc‐
48            tory  containing  one  or  more archives. The resulting set of ar‐
49            chives will be the source of the performance metrics.  The initial
50            Tab  created will be an archive mode Tab.  Multiple -a options can
51            be presented, and the resulting list of sets of archives  is  used
52            for  sourcing  metric  values.   Any sources listed on the command
53            line are assumed to be sets of archives if this option is used.
54
55       -c   configfile specifies an initial view to load,  using  the  default
56            source  of  metrics.  Multiple -c views can be specified, and they
57            will all be opened in the default Tab with the default  source  of
58            metrics.
59
60       -C   Used with -c, the view(s) are parsed, any errors are reported, and
61            the tool exits.  This is primarily intended for testing  purposes.
62            If  a  second  -C  option  is  presented, pmchart also connects to
63            pmcd(1) to check the semantics of metrics.
64
65       -f   Specify the default font family to be used in several chart compo‐
66            nents,  such  as  the  chart title, legend, and Y-axis label.  The
67            default value is "Sans Serif".  This setting does not  affect  the
68            rest  of the user interface, where the value is inherited from the
69            environment in which pmchart operates, and  differs  according  to
70            the look-and-feel of each platform.
71
72       -F   Specify  the  default  font point size to be used in several chart
73            components, such as the chart title,  legend,  and  Y-axis  label.
74            The  default is platform dependent, but is either 7, 8 or 9.  This
75            setting does not affect the rest of the user interface.
76
77       -g   Generate image with the specified  geometry  (width  and  height).
78            This  option  is  only useful when used in conjunction with the -o
79            option for generating an  output  image.   The  geometry  argument
80            takes  the form "WxH" (e.g. 240x120).  When NOT using the -o flag,
81            to specify the display window  geometry,  use  -geometry  geometry
82            where  geometry  specifies  the  desired  window width, height and
83            optional placement.
84
85       -h   Current performance metric values are retrieved from the nominated
86            host  machine  by  default.  Multiple -h options can be presented,
87            and the list of hosts is used for  sourcing  metric  values.   Any
88            sources listed on the command line are assumed to be hosts if this
89            option is used.
90
91       -o   Generate an image file named outfile, and then exit.  This is most
92            useful when run with a set of archives and one or more views.  The
93            generated image will be in the format specified as the file exten‐
94            sion (automatically determined from outfile).  If no extension can
95            be determined, then the GIF format is used and the generated  file
96            is  named  with  this extension.  The supported image file formats
97            include: bmp, jpeg, jpg, png, ppm, tif, tiff, xbm, and xpm.
98
99       -p   port number for connection to  an  existing  pmtime  time  control
100            process.
101
102       -s   Specifies  the number of samples that will be retained before dis‐
103            carding old data (replaced by new values at the current time posi‐
104            tion).   This  value can subsequently be modified through the Edit
105            Tab dialog.
106
107       -t   Sets the inital  update  interval  to  something  other  than  the
108            default  1  second.   The  interval  argument  follows  the syntax
109            described in PCPIntro(1), and in  the  simplest  form  may  be  an
110            unsigned integer (the implied units in this case are seconds).
111
112       -v   Sets  the  inital  visible  samples  that will be displayed in all
113            charts in the default Tab.  This value must be less than or  equal
114            to the total number of samples retained (the -s value).
115
116       -V   Display pmchart version number and exit
117
118       -W   Export images using an opaque(white) background
119
120       -Z   By  default, pmtime reports the time of day according to the local
121            timezone on the system  where  pmchart  is  run.   The  -Z  option
122            changes  the timezone to timezone in the format of the environment
123            variable TZ as described in environ(7).
124
125       -z   Change the reporting timezone to the local timezone  at  the  host
126            that  is  the source of the performance metrics, as identified via
127            either the -h or -a options.
128
129       The -S, -T, -O and -A options may be used to define a  time  window  to
130       restrict  the  samples retrieved, set an initial origin within the time
131       window, or specify a "natural" alignment of the sample   times;   refer
132       to PCPIntro(1) for a complete description of these options.
133

VIEWS

135       The  primary pmchart configuration file is the "view", which allows the
136       metadata associated with one or more charts to be saved in the filesys‐
137       tem.   This  metadata  describes  all  aspects of the charts, including
138       which PCP metrics and instances are to be used, which hosts, which col‐
139       ors, the chart titles, use of chart legends, and much more.
140
141       From  a conceptual point of view, there are two classes of view.  These
142       views share the same configuration file format - refer to a later  sec‐
143       tion for a complete description of this format.  The differences lie in
144       where they are installed and how they are manipulated.
145
146       The first class,  the  "system"  view,  is  simply  any  view  that  is
147       installed  as  part  of  the  pmchart  package.   These  are  stored in
148       $PCP_VAR_DIR/config/pmchart.  When the File→Open View  dialog  is  dis‐
149       played,  it is these views that are initially listed.  The system views
150       cannot be modified by a normal user, and should not be modified even by
151       a  user with suitable privileges, as they will be overwritten during an
152       upgrade.
153
154       The second class of view is the "user" view.  These views  are  created
155       on-the-fly  using  the  File→Save View dialog.  This is a mechanism for
156       individual users to save their commonly used views.   Access  to  these
157       views is achieved through the File→Open View dialog, as with the system
158       views.  Once the dialog is opened, the list of  views  can  be  toggled
159       between  user and system views by clicking on the two toggle buttons in
160       the top right corner.  User views are stored in $HOME/.pcp/pmchart.
161

TABS

163       pmchart provides the common user interface concept of the Tab, which is
164       most  prevalent  in  modern web browsers.  Tabs allow pmchart to update
165       many more charts than the available screen real estate allows, by  pro‐
166       viding a user interface mechanism to stack (and switch between) differ‐
167       ent vertical sets of charts.  Switching between  Tabs  is  achieved  by
168       clicking on the Tab labels, which are located along the top of the dis‐
169       play beneath the Menu and Tool bars).
170
171       Each Tab has a mode of operation (either live or archive - pmchart  can
172       support  both  modes  simultaneously),  the total number of samples and
173       currently visible points, and a label describing the Tab which is  dis‐
174       played at the top of the pmchart window.  New Tabs can be created using
175       the File→Add Tab dialog.
176
177       In order to save on vertical screen real estate,  note  that  the  user
178       interface  element  for changing between different Tabs (and its label)
179       are only displayed when more than one Tab exists.  A Tab  can  be  dis‐
180       missed using the File→Close Tab menu, which removes the current Tab and
181       any charts it contained.
182

IMAGES and PRINTING

184       A static copy of the currently displayed vertical series of charts  can
185       be captured in two ways.
186
187       When  the  intended  display device is the screen, the File→Export menu
188       option should be used.  This allows exporting the charts in  a  variety
189       of  image  formats,  including PNG, JPEG, GIF, and BMP.  The image size
190       can be scaled up or down in any dimension.
191
192       Alternatively,  when  the  intended  display  device  is   paper,   the
193       File→Print  menu  option  can  be used.  This supports the usual set of
194       printing options (choice of  printer,  grayscale/color,  landscape/por‐
195       trait,  scaling  to different paper sizes, etc), and in addition allows
196       printing to the intermediate printer formats of PostScript and Portable
197       Document Format (PDF).
198

RECORDING

200       It  is  possible  to make a recording of a set of displayed charts, for
201       later playback through pmchart or any of the other Performance Co-Pilot
202       tools.   The  Record→Start functionality is simple to configure through
203       the user interface, and allows fine-tuning  of  the  recording  process
204       (including  record frequencies that differ to the pmchart update inter‐
205       val, alternate file locations, etc).
206
207       pmchart produces recordings that are compatible with the  PCP  pmafm(1)
208       replay mechanism, for later playback via a new instance of pmchart.  In
209       addition, when recording  through  pmchart  one  can  also  replay  the
210       recording  immediately, as on termination of the recording (through the
211       Record→Stop menu item), an archive mode Tab will be  created  with  the
212       captured view.
213
214       Once  recording is active in a Live Tab, the Time Control status button
215       in the bottom left corner of the pmchart window  is  displayed  with  a
216       distinctive  red  dot.  At any time during a pmchart recording session,
217       the amount of space used in the filesystem by  that  recording  can  be
218       displayed using the Record→Query menu item.
219
220       Finally, the Record→Detach menu option provides a mechanism whereby the
221       recording process can be completely divorced from the  running  pmchart
222       process,  and allowed to continue on when pmchart exits.  A dialog dis‐
223       playing the current size and estimated rate of growth for the recording
224       is  presented.   On  the  other  hand,  if  pmchart is terminated while
225       recording is in process, then the recording  process  will  prompt  the
226       user  to  choose immediate cessation of recording or for it to continue
227       on independently.
228
229       All of the record mode services available from pmchart are  implemented
230       with the assistance of the base Performance Co-Pilot logging services -
231       refer to pmlogger(1) and pmafm(1) for an extensive description  of  the
232       capabilities of these tools.
233

CONFIGURATION FILE SYNTAX

235       pmchart  loads predefined chart configurations (or "views") from exter‐
236       nal files that conform to the following  rules.   In  the  descriptions
237       below  keywords  (shown  in  bold)  may appear in upper, lower or mixed
238       case, elements shown in [stuff] are optional,  and  user-supplied  ele‐
239       ments  are  shown  as  <other stuff>.  A vertical bar (|) is used where
240       syntactic elements are alternatives.  Quotes (") may be used to enclose
241       lexical  elements  that may contain white space, such as titles, labels
242       and instance names.
243
244       1. The first line defines the configuration file type and should be
245               #kmchart
246          although pmchart provides  backwards  compatibility  for  the  older
247          pmchart view formats with an initial line of
248               #pmchart
249
250       2. After  the  first  line,  lines beginning with "#" as the first non-
251          white space character are treated as comments  and  skipped.   Simi‐
252          larly blank lines are skipped.
253
254       3. The next line should be
255               version <n> <host-clause>
256          where  <n>  depends  on  the  configuration  file type, and is 1 for
257          pmchart else 1.1, 1.2 or 2.0 for pmchart.
258          The <host-clause> part is optional (and ignored) for pmchart config‐
259          uration files, but required for the pmchart configuration files, and
260          is of the form
261               host literal
262          or
263               host dynamic
264
265       4. A configuration contains one or more charts defined as follows:
266               chart [title <title>] style <style> <options>
267          If specified, the title will appear centred and above the graph area
268          of  the chart.  The <title> is usually enclosed in quotes (") and if
269          it contains the sequence "%h" this will be  replaced  by  the  short
270          form  of  the hostname for the default source of metrics at the time
271          this chart was loaded.  Alternatively, "%H" can be  used  to  insert
272          the  full  host name.  If the hostname appears to be an inet or IPv6
273          address, no shortening will be attempted; it will be used  as-is  in
274          both  replacement  cases.  After the view is loaded, the title visi‐
275          bility and setting can be manipulated using the Chart Title text box
276          in the Edit→Chart dialog.
277
278          The  <style>  controls  the initial plotting style of the chart, and
279          should be one of the  keywords  plot  (line  graph),  bar,  stacking
280          (stacked  bar),  area or utilization.  After the view is loaded, the
281          plotting style can be changed using the  Edit→Chart  Style  dropdown
282          list.
283
284          The <options> are zero or more of the optional elements:
285               [scale [from] <ymin> [to] <ymax>] [legend <onoff>]
286          If  scale is specified, the vertical scaling is set for all plots in
287          the chart to a y-range defined by <ymin> and <ymax>.  Otherwise  the
288          vertical axis will be autoscaled based on the values currently being
289          plotted.
290
291          <onoff> is one of the keywords on or off and the legend clause  con‐
292          trols  the  presence  or  absence of the plot legend below the graph
293          area.  The default is for the legend to be shown.  After the view is
294          loaded,  the  legend visibility can be toggled using the Show Legend
295          button in the Edit→Chart dialog.
296
297       5. pmchart supports a global clause to specify the  dimensions  of  the
298          top-level  window  (using the width and height keywords), the number
299          of visible points (points keyword) and the starting  X  and  Y  axis
300          positions  on  the  screen  (xpos and ypos keywords).  Each of these
301          global attributes takes an integer value as the sole qualifier.
302
303       6. Each chart has one or more plots associated with it, as  defined  by
304          one of the following specifications:
305               plot
306                   [legend <title>] [color <colorspec>] [host <hostspec>]
307                   metric <metricname>
308                   [ instance <inst> | matching <pat> | not-matching <pat> ]
309
310          The  keyword plot may be replaced with the keyword optional-plot, in
311          which case if the source of performance data does  not  include  the
312          specified  performance  metric  and/or  instance,  then this plot is
313          silently dropped from the chart.
314
315          If specified, the title  will  appear  in  the  chart  legend.   The
316          <title>  is usually enclosed in quotes (") and it may contain one or
317          more wildcard characters which will be expanded using  metric  name,
318          instance  name,  and host name for the plot.  The wildcards are "%i"
319          (short unique instance name, up to the first whitespace), "%I" (full
320          instance  name),  "%h"  (short  host  name, up to the first dot), %H
321          (full host name), "%m" (metric name shortened to the final two  PMNS
322          components), and "%M" (full metric name).
323
324          For  older  pmchart  configuration  files, the keyword title must be
325          used instead of legend.  Nowadays pmchart supports either keyword.
326
327          The color clause is optional for newer pmchart configuration  files,
328          but it was mandatory in the original pmchart configuration file for‐
329          mat.  <colorspec> may be one of the following:
330               #-cycle
331               rgbi:rr:gg:bb
332               #rgb
333               #rrggbb
334               #rrrgggbbb
335               #rrrrggggbbbb
336               <Xcolor>
337          where each of r, g and b are hexadecimal digits (0-9 and A-F) repre‐
338          senting  respectively  the  red,  green  and  blue color components.
339          <Xcolor> is one of the color names from the X color  database,  e.g.
340          red or steelblue, see also the output from showrgb(1).
341
342          The  "color" #-cycle specifies that pmchart should use the next in a
343          pallet of colors that it uses cyclically for each  chart.   This  is
344          the default if the color clause is omitted.
345
346          The  <hostspec>  in the host clause may be a hostname, an IP address
347          or an asterisk (*); the latter is used to mean the default source of
348          performance  metrics.   For  older  pmchart configuration files, the
349          host clause must be present, for new pmchart configuration files  it
350          is  optional,  and if missing the default source of performance met‐
351          rics will be used.
352
353          The optional instance specification,
354
355          (a)
356             is omitted in which case one  plot  will  be  created  for  every
357             instance of the <metricname> metric
358
359          (b)
360             starts  with  instance,  in  which  case  only the instance named
361             <inst> will be plotted
362
363          (c)
364             starts with matching, in which case  all  instances  whose  names
365             match  the  pattern  <pat>  will  be  plotted;  the  pattern uses
366             extended regular expression notation in  the  style  of  egrep(1)
367             (refer to the PMCD view for an example)
368
369          (d)
370             starts with not-matching, in which case all instances whose names
371             do   not match the pattern <pat> will  be  plotted;  the  pattern
372             uses  extended  regular  expression  notation  in  the  style  of
373             egrep(1) (refer to the Netbytes view for an example)
374
375          pmchart uses a bizarre syntactic notation  where  <inst>  and  <pat>
376          extend  from  the  first non-white space character to the end of the
377          input line.  For pmchart  configuration  files  these  elements  are
378          either delimited by white space, or enclosed in quotes (").
379
380       7. The optional tab directive can be used to create views with multiple
381          charts which span multiple Tabs.  The syntax is as follows:
382               tab <label> [host <host>] [points <points> [samples <samples>]]
383
384          All chart specifications following this keyword will be created
385          on the new Tab, until the end of the configuration file or until
386          another tab keyword is encountered.
387

PCP ENVIRONMENT

389       Environment variables with the prefix PCP_ are used to parameterize the
390       file  and  directory names used by PCP.  On each installation, the file
391       /etc/pcp.conf contains the  local  values  for  these  variables.   The
392       $PCP_CONF  variable may be used to specify an alternative configuration
393       file, as described in pcp.conf(5).
394
395       Of particular note, the $PCP_XCONFIRM_PROG setting  is  explicitly  and
396       unconditionally  overridden  by  pmchart.   This  is  set to the pmcon‐
397       firm(1), utility, in order that some popup dialogs (particularly in the
398       area of Recording) maintain a consistent look-and-feel with the rest of
399       the pmchart application.
400

SEE ALSO

402       pmtime(1),   pmconfirm(1),   pmdumptext(1),   PCPIntro(1),    pmafm(1),
403       pmrep(1),  pmval(1),  pmcd(1),  pminfo(1),  pcp.conf(5), pcp.env(5) and
404       pmns(5).
405
406
407
408Performance Co-Pilot                                                PMCHART(1)
Impressum