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

NAME

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

SYNOPSIS

9       pmchart  [-CLVWz?]  [-a archive] [-A align] [--archive-folio folio] [-c
10       configfile] [-f fontfamily] [-F fontsize] [-g geometry] [-h  host]  [-n
11       pmnsfile]  [-o  outfile]  [-O offset] [-p port] [-s samples] [-S start‐
12       time] [-t interval] [-T endtime] [-v visible] [-Z timezone]  [-geometry
13       geometry] [sources...]
14

DESCRIPTION

16       pmchart  is  a  graphical utility that plots performance metrics values
17       available through the facilities of  the  Performance  Co-Pilot  (PCP).
18       Multiple  charts can be displayed simultaneously, either aligned on the
19       unified time axis (X-axis), and through the use of  multiple  interface
20       Tabs.
21
22       Metric  values  can  be sourced from one or more live hosts (simultane‐
23       ously).  Alternatively, one or more sets of PCP archives can be used as
24       a  source  of historical data.  See PCPIntro(1) for an in-depth discus‐
25       sion of the capabilities of the PCP framework, many of which  are  used
26       by pmchart.
27
28       Many  aspects of the behaviour of pmchart can be customised through the
29       interface.  In particular, the use of "views" (refer to the section de‐
30       scribing  VIEWS  later in this document) allows predefined sets of met‐
31       rics and charting parameters like colors, scaling, titles, legends, and
32       so  on to be stored for later use, or use with different hosts and sets
33       of archives.  In addition, the Preferences dialog allows customisations
34       to  the rest of the pmchart user interface to be saved and restored be‐
35       tween different invocations of the tool.  This allows the default back‐
36       ground  color,  highlight  color, contents and location of the toolbar,
37       and many other aspects to be configured.
38
39       pmchart makes extensive use of the pmtime(1) utility for time  control,
40       refer to the pmtime manual page for further details of its operation.
41

OPTIONS

43       The available command line options are:
44
45       -a archive, --archive=archive
46            Performance  metric  values  are retrieved from the set of Perfor‐
47            mance Co-Pilot (PCP) archives identified by this  option,  by  de‐
48            fault.   The  argument is a comma-separated list of names, each of
49            which may be the base name of an archive or the name of  a  direc‐
50            tory  containing  one  or more archives.  The resulting set of ar‐
51            chives will be the source of the performance metrics.  The initial
52            Tab  created will be an archive mode Tab.  Multiple -a options can
53            be presented, and the resulting list of sets of archives  is  used
54            for  sourcing  metric  values.   Any sources listed on the command
55            line are assumed to be sets of archives if this option is used.
56
57       -A align, --align=align
58            Force the initial sample to be aligned on the boundary of a  natu‐
59            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
60            tion of the syntax for align.
61
62       --archive-folio=folio
63            Read metric source archives from the PCP archive folio.
64
65       -c configfile, --view=configfile
66            configfile specifies an initial view to load,  using  the  default
67            source  of  metrics.  Multiple -c views can be specified, and they
68            will all be opened in the default Tab with the default  source  of
69            metrics.
70
71       -c, --check
72            Used with -c, the view(s) are parsed, any errors are reported, and
73            the tool exits.  This is primarily intended for testing  purposes.
74            If  a  second  -C  option  is  presented, pmchart also connects to
75            pmcd(1) to check the semantics of metrics.
76
77       -f family, --font-family=family
78            Specify the default font family to be used in several chart compo‐
79            nents, such as the chart title, legend, and Y-axis label.  The de‐
80            fault value is "Sans Serif".  This setting  does  not  affect  the
81            rest  of the user interface, where the value is inherited from the
82            environment in which pmchart operates, and  differs  according  to
83            the look-and-feel of each platform.
84
85       -F point, --font-size=point
86            Specify  the  default  font point size to be used in several chart
87            components, such as the chart title,  legend,  and  Y-axis  label.
88            The  default is platform dependent, but is either 7, 8 or 9.  This
89            setting does not affect the rest of the user interface.
90
91       -g geometry, --geometry=geometry
92            Generate image with the specified  geometry  (width  and  height).
93            This  option  is  only useful when used in conjunction with the -o
94            option for generating an  output  image.   The  geometry  argument
95            takes  the form "WxH" (e.g. 240x120).  When NOT using the -o flag,
96            to specify the display window  geometry,  use  -geometry  geometry
97            where  geometry specifies the desired window width, height and op‐
98            tional placement.
99
100       -h host, --host=host
101            Current performance metric values are retrieved from the nominated
102            host  machine  by  default.  Multiple -h options can be presented,
103            and the list of hosts is used for  sourcing  metric  values.   Any
104            sources listed on the command line are assumed to be hosts if this
105            option is used.
106
107       -H path, --hostsfile=path
108            Specify the path to a file containing a  set  of  hostnames  where
109            pmcd(1) is running , rather than using the default localhost.
110
111       -K spec, --spec-local=spec
112            When fetching metrics from a local context (see -L), the -K option
113            may be used to control the DSO PMDAs that should be made  accessi‐
114            ble.   The  spec  argument conforms to the syntax described in pm‐
115            SpecLocalPMDA(3).  More than one -K option may be used.
116
117       -L, --local-PMDA
118            Use a local context to collect metrics from DSO PMDAs on the local
119            host without PMCD.  See also -K.
120
121       -n pmnsfile, --namespace=pmnsfile
122            Load  an alternative Performance Metrics Name Space (PMNS(5)) from
123            the file pmnsfile.
124
125       -o outfile, --output=outfile
126            Generate an image file named outfile, and then exit.  This is most
127            useful when run with a set of archives and one or more views.  The
128            generated image will be in the format specified as the file exten‐
129            sion (automatically determined from outfile).  If no extension can
130            be determined, then the GIF format is used and the generated  file
131            is  named  with  this extension.  The supported image file formats
132            include: bmp, jpeg, jpg, png, ppm, tif, tiff, xbm, and xpm.
133
134       -O origin, --origin=origin
135            When reporting archived metrics, start reporting at origin  within
136            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
137            plete description of the syntax for origin.
138
139       -p port, --guiport=port
140            port number for connection to  an  existing  pmtime  time  control
141            process.
142
143       -s samples, --samples=samples
144            Specifies  the number of samples that will be retained before dis‐
145            carding old data (replaced by new values at the current time posi‐
146            tion).   This  value can subsequently be modified through the Edit
147            Tab dialog.
148
149       -S starttime, --start=starttime
150            When reporting archived metrics, the report will be restricted  to
151            those  records logged at or after starttime.  Refer to PCPIntro(1)
152            for a complete description of the syntax for starttime.
153
154       -t interval, --interval=interval
155            Sets the inital update interval to something other  than  the  de‐
156            fault  1  second.   The  interval  argument follows the syntax de‐
157            scribed in PCPIntro(1), and in the simplest form  may  be  an  un‐
158            signed integer (the implied units in this case are seconds).
159
160       -T endtime, --finish=endtime
161            When  reporting archived metrics, the report will be restricted to
162            those records logged before or at endtime.  Refer  to  PCPIntro(1)
163            for a complete description of the syntax for endtime.
164
165       -v samples, --visible=samples
166            Sets  the  initial  visible  samples that will be displayed in all
167            charts in the default Tab.  This value must be less than or  equal
168            to the total number of samples retained (the -s value).
169
170       -V, --version
171            Display pmchart version number and exit
172
173       -W, fB--white
174            Export images using an opaque(white) background
175
176       -z, --hostzone
177            Change  the  reporting  timezone to the local timezone at the host
178            that is the source of the performance metrics, as  identified  via
179            either the -h or -a options.
180
181       -Z timezone, --timezone=timezone
182            By  default, pmtime reports the time of day according to the local
183            timezone on the system  where  pmchart  is  run.   The  -Z  option
184            changes  the timezone to timezone in the format of the environment
185            variable TZ as described in environ(7).
186
187       -?, --help
188            Display usage message and exit.
189

VIEWS

191       The primary pmchart configuration file is the "view", which allows  the
192       metadata associated with one or more charts to be saved in the filesys‐
193       tem.  This metadata describes all  aspects  of  the  charts,  including
194       which PCP metrics and instances are to be used, which hosts, which col‐
195       ors, the chart titles, use of chart legends, and much more.
196
197       From a conceptual point of view, there are two classes of view.   These
198       views  share the same configuration file format - refer to a later sec‐
199       tion for a complete description of this format.  The differences lie in
200       where they are installed and how they are manipulated.
201
202       The  first  class,  the  "system"  view, is simply any view that is in‐
203       stalled  as  part  of  the  pmchart  package.   These  are  stored   in
204       $PCP_VAR_DIR/config/pmchart.   When  the  File→Open View dialog is dis‐
205       played, it is these views that are initially listed.  The system  views
206       cannot be modified by a normal user, and should not be modified even by
207       a user with suitable privileges, as they will be overwritten during  an
208       upgrade.
209
210       The  second  class of view is the "user" view.  These views are created
211       on-the-fly using the File→Save View dialog.  This is  a  mechanism  for
212       individual  users  to  save their commonly used views.  Access to these
213       views is achieved through the File→Open View dialog, as with the system
214       views.  Once the dialog is opened, the list of views can be toggled be‐
215       tween user and system views by clicking on the two  toggle  buttons  in
216       the top right corner.  User views are stored in $HOME/.pcp/pmchart.
217

TABS

219       pmchart provides the common user interface concept of the Tab, which is
220       most prevalent in modern web browsers.  Tabs allow  pmchart  to  update
221       many  more charts than the available screen real estate allows, by pro‐
222       viding a user interface mechanism to stack (and switch between) differ‐
223       ent  vertical  sets  of  charts.  Switching between Tabs is achieved by
224       clicking on the Tab labels, which are located along the top of the dis‐
225       play beneath the Menu and Tool bars).
226
227       Each  Tab has a mode of operation (either live or archive - pmchart can
228       support both modes simultaneously), the total  number  of  samples  and
229       currently  visible points, and a label describing the Tab which is dis‐
230       played at the top of the pmchart window.  New Tabs can be created using
231       the File→Add Tab dialog.
232
233       In order to save on vertical screen real estate, note that the user in‐
234       terface element for changing between different Tabs (and its label) are
235       only  displayed  when more than one Tab exists.  A Tab can be dismissed
236       using the File→Close Tab menu, which removes the current  Tab  and  any
237       charts it contained.
238

IMAGES and PRINTING

240       A  static copy of the currently displayed vertical series of charts can
241       be captured in two ways.
242
243       When the intended display device is the screen,  the  File→Export  menu
244       option  should  be used.  This allows exporting the charts in a variety
245       of image formats, including PNG, JPEG, GIF, and BMP.   The  image  size
246       can be scaled up or down in any dimension.
247
248       Alternatively,   when   the  intended  display  device  is  paper,  the
249       File→Print menu option can be used.  This supports  the  usual  set  of
250       printing  options  (choice  of printer, grayscale/color, landscape/por‐
251       trait, scaling to different paper sizes, etc), and in  addition  allows
252       printing to the intermediate printer formats of PostScript and Portable
253       Document Format (PDF).
254

RECORDING

256       It is possible to make a recording of a set of  displayed  charts,  for
257       later playback through pmchart or any of the other Performance Co-Pilot
258       tools.  The Record→Start functionality is simple to  configure  through
259       the  user  interface,  and  allows fine-tuning of the recording process
260       (including record frequencies that differ to the pmchart update  inter‐
261       val, alternate file locations, etc).
262
263       pmchart  produces  recordings that are compatible with the PCP pmafm(1)
264       replay mechanism, for later playback via a new instance of pmchart.  In
265       addition,  when  recording  through  pmchart  one  can  also replay the
266       recording immediately, as on termination of the recording (through  the
267       Record→Stop  menu  item),  an archive mode Tab will be created with the
268       captured view.
269
270       Once recording is active in a Live Tab, the Time Control status  button
271       in  the  bottom  left  corner of the pmchart window is displayed with a
272       distinctive red dot.  At any time during a pmchart  recording  session,
273       the  amount  of  space  used in the filesystem by that recording can be
274       displayed using the Record→Query menu item.
275
276       Finally, the Record→Detach menu option provides a mechanism whereby the
277       recording  process  can be completely divorced from the running pmchart
278       process, and allowed to continue on when pmchart exits.  A dialog  dis‐
279       playing the current size and estimated rate of growth for the recording
280       is presented.  On the  other  hand,  if  pmchart  is  terminated  while
281       recording  is  in  process,  then the recording process will prompt the
282       user to choose immediate cessation of recording or for it  to  continue
283       on independently.
284
285       All  of the record mode services available from pmchart are implemented
286       with the assistance of the base Performance Co-Pilot logging services -
287       refer  to  pmlogger(1) and pmafm(1) for an extensive description of the
288       capabilities of these tools.
289

CONFIGURATION FILE SYNTAX

291       pmchart loads predefined chart configurations (or "views") from  exter‐
292       nal files that conform to the following rules.  In the descriptions be‐
293       low keywords (shown in bold) may appear in upper, lower or mixed  case,
294       elements  shown in [stuff] are optional, and user-supplied elements are
295       shown as <other stuff>.  A vertical bar (|) is used where syntactic el‐
296       ements are alternatives.  Quotes (") may be used to enclose lexical el‐
297       ements that may contain white space, such as  titles,  labels  and  in‐
298       stance names.
299
300       1. The first line defines the configuration file type and should be
301               #kmchart
302          although  pmchart provides backwards compatibility for the older pm‐
303          chart view formats with an initial line of
304               #pmchart
305
306       2. After the first line, lines beginning with "#"  as  the  first  non-
307          white  space  character  are treated as comments and skipped.  Simi‐
308          larly blank lines are skipped.
309
310       3. The next line should be
311               version <n> <host-clause>
312          where <n> depends on the configuration file type, and is 1  for  pm‐
313          chart else 1.1, 1.2 or 2.0 for pmchart.
314          The <host-clause> part is optional (and ignored) for pmchart config‐
315          uration files, but required for the pmchart configuration files, and
316          is of the form
317               host literal
318          or
319               host dynamic
320
321       4. A configuration contains one or more charts defined as follows:
322               chart [title <title>] style <style> <options>
323          If specified, the title will appear centred and above the graph area
324          of the chart.  The <title> is usually enclosed in quotes (") and  if
325          it  contains  the  sequence  "%h" this will be replaced by the short
326          form of the hostname for the default source of metrics at  the  time
327          this  chart  was  loaded.  Alternatively, "%H" can be used to insert
328          the full host name.  If the hostname appears to be an inet  or  IPv6
329          address,  no  shortening will be attempted; it will be used as-is in
330          both replacement cases.  After the view is loaded, the  title  visi‐
331          bility and setting can be manipulated using the Chart Title text box
332          in the Edit→Chart dialog.
333
334          The <style> controls the initial plotting style of  the  chart,  and
335          should  be  one  of  the  keywords  plot (line graph), bar, stacking
336          (stacked bar), area or utilization.  After the view is  loaded,  the
337          plotting  style  can  be changed using the Edit→Chart Style dropdown
338          list.
339
340          The <options> are zero or more of the optional elements:
341               [scale [from] <ymin> [to] <ymax>] [legend <onoff>]
342          If scale is specified, the vertical scaling is set for all plots  in
343          the  chart to a y-range defined by <ymin> and <ymax>.  Otherwise the
344          vertical axis will be autoscaled based on the values currently being
345          plotted.
346
347          <onoff>  is one of the keywords on or off and the legend clause con‐
348          trols the presence or absence of the plot  legend  below  the  graph
349          area.  The default is for the legend to be shown.  After the view is
350          loaded, the legend visibility can be toggled using the  Show  Legend
351          button in the Edit→Chart dialog.
352
353       5. pmchart  supports  a  global clause to specify the dimensions of the
354          top-level window (using the width and height keywords),  the  number
355          of visible points (points keyword) and the starting X and Y axis po‐
356          sitions on the screen (xpos  and  ypos  keywords).   Each  of  these
357          global attributes takes an integer value as the sole qualifier.
358
359       6. Each  chart  has one or more plots associated with it, as defined by
360          one of the following specifications:
361               plot
362                   [legend <title>] [color <colorspec>] [host <hostspec>]
363                   metric <metricname>
364                   [ instance <inst> | matching <pat> | not-matching <pat> ]
365
366          The keyword plot may be replaced with the keyword optional-plot,  in
367          which  case  if  the source of performance data does not include the
368          specified performance metric and/or  instance,  then  this  plot  is
369          silently dropped from the chart.
370
371          If  specified,  the title will appear in the chart legend.  The <ti‐
372          tle> is usually enclosed in quotes (") and it  may  contain  one  or
373          more  wildcard  characters which will be expanded using metric name,
374          instance name, and host name for the plot.  The wildcards  are  "%i"
375          (short unique instance name, up to the first whitespace), "%I" (full
376          instance name), "%h" (short host name, up  to  the  first  dot),  %H
377          (full  host name), "%m" (metric name shortened to the final two PMNS
378          components), and "%M" (full metric name).
379
380          For older pmchart configuration files, the  keyword  title  must  be
381          used instead of legend.  Nowadays pmchart supports either keyword.
382
383          The  color clause is optional for newer pmchart configuration files,
384          but it was mandatory in the original pmchart configuration file for‐
385          mat.  <colorspec> may be one of the following:
386               #-cycle
387               rgbi:rr:gg:bb
388               #rgb
389               #rrggbb
390               #rrrgggbbb
391               #rrrrggggbbbb
392               <Xcolor>
393          where each of r, g and b are hexadecimal digits (0-9 and A-F) repre‐
394          senting respectively the  red,  green  and  blue  color  components.
395          <Xcolor>  is  one of the color names from the X color database, e.g.
396          red or steelblue, see also the output from showrgb(1).
397
398          The "color" #-cycle specifies that pmchart should use the next in  a
399          pallet  of  colors  that it uses cyclically for each chart.  This is
400          the default if the color clause is omitted.
401
402          The <hostspec> in the host clause may be a hostname, an  IP  address
403          or an asterisk (*); the latter is used to mean the default source of
404          performance metrics.  For older  pmchart  configuration  files,  the
405          host  clause must be present, for new pmchart configuration files it
406          is optional, and if missing the default source of  performance  met‐
407          rics will be used.
408
409          The optional instance specification,
410
411          (a)
412             is  omitted  in which case one plot will be created for every in‐
413             stance of the <metricname> metric
414
415          (b)
416             starts with instance, in  which  case  only  the  instance  named
417             <inst> will be plotted
418
419          (c)
420             starts  with  matching,  in  which case all instances whose names
421             match the pattern <pat> will be plotted;  the  pattern  uses  ex‐
422             tended  regular expression notation in the style of egrep(1) (re‐
423             fer to the PMCD view for an example)
424
425          (d)
426             starts with not-matching, in which case all instances whose names
427             do    not  match  the  pattern <pat> will be plotted; the pattern
428             uses  extended  regular  expression  notation  in  the  style  of
429             egrep(1) (refer to the Netbytes view for an example)
430
431          pmchart uses a bizarre syntactic notation where <inst> and <pat> ex‐
432          tend from the first non-white space character to the end of the  in‐
433          put line.  For pmchart configuration files these elements are either
434          delimited by white space, or enclosed in quotes (").
435
436       7. The optional tab directive can be used to create views with multiple
437          charts which span multiple Tabs.  The syntax is as follows:
438               tab <label> [host <host>] [points <points> [samples <samples>]]
439
440          All chart specifications following this keyword will be created
441          on the new Tab, until the end of the configuration file or until
442          another tab keyword is encountered.
443

PCP ENVIRONMENT

445       Environment variables with the prefix PCP_ are used to parameterize the
446       file and directory names used by PCP.  On each installation,  the  file
447       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
448       $PCP_CONF variable may be used to specify an alternative  configuration
449       file, as described in pcp.conf(5).
450
451       Of  particular  note,  the $PCP_XCONFIRM_PROG setting is explicitly and
452       unconditionally overridden by pmchart.   This  is  set  to  the  pmcon‐
453       firm(1), utility, in order that some popup dialogs (particularly in the
454       area of Recording) maintain a consistent look-and-feel with the rest of
455       the pmchart application.
456

SEE ALSO

458       PCPIntro(1),  pmafm(1),  pmconfirm(1),  pmdumptext(1),  pminfo(1),  pm‐
459       rep(1), pmtime(1), pmval(1), pcp.conf(5) and PMNS(5).
460
461
462
463Performance Co-Pilot                                                PMCHART(1)
Impressum