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] [-c configfile] [-f fontfam‐
10       ily] [-F fontsize] [-g geometry] [-h host] [-o outfile] [-O offset] [-p
11       port]  [-s samples] [-S starttime] [-t interval] [-T endtime] [-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

OPTIONS

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

VIEWS

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

TABS

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

IMAGES and PRINTING

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

RECORDING

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

CONFIGURATION FILE SYNTAX

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

PCP ENVIRONMENT

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

SEE ALSO

453       pmtime(1),    pmconfirm(1),   pmdumptext(1),   PCPIntro(1),   pmafm(1),
454       pmrep(1), pmval(1), pmcd(1),  pminfo(1),  pcp.conf(5),  pcp.env(5)  and
455       PMNS(5).
456
457
458
459Performance Co-Pilot                                                PMCHART(1)
Impressum