1PMCHART(1) General Commands Manual PMCHART(1)
2
6 pmchart - strip chart tool for Performance Co-Pilot
7
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
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 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 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 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
43 The available command line options are:
44 -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 -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 --archive-folio=folio
63 Read metric source archives from the PCP archive folio.
64 -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 -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 -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 -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 -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 -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 -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 -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 -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 -n pmnsfile, --namespace=pmnsfile
122 Load an alternative Performance Metrics Name Space (PMNS(5)) from
123 the file pmnsfile.
124 -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 -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 -p port, --guiport=port
140 port number for connection to an existing pmtime time control
141 process.
142 -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 -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 -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 -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 -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 -V, --version
171 Display pmchart version number and exit
172 -W, fB--white
174 Export images using an opaque(white) background
175 -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 -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 -?, --help
188 Display usage message and exit.
189
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 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 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 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
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 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 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
240 A static copy of the currently displayed vertical series of charts can
241 be captured in two ways.
242 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 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
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 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 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 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 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
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 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 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 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 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 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 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 <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 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 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 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 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 For older pmchart configuration files, the keyword title must be
381 used instead of legend. Nowadays pmchart supports either keyword.
382 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 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 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 The optional instance specification,
410 (a)
412 is omitted in which case one plot will be created for every in‐
413 stance of the <metricname> metric
414 (b)
416 starts with instance, in which case only the instance named
417 <inst> will be plotted
418 (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 (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 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 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 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
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 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
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).
460Performance Co-Pilot PMCHART(1)