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] [-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
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 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 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 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
42 The available command line options are:
43 -a archive, --archive=archive
45 Performance metric values are retrieved from the set of Perfor‐
46 mance Co-Pilot (PCP) archive logs identified by this option, by
47 default. The argument is a comma-separated list of names, each of
48 which may be the base name of an archive or the name of a direc‐
49 tory containing one or more archives. The resulting set of ar‐
50 chives will be the source of the performance metrics. The initial
51 Tab created will be an archive mode Tab. Multiple -a options can
52 be presented, and the resulting list of sets of archives is used
53 for sourcing metric values. Any sources listed on the command
54 line are assumed to be sets of archives if this option is used.
55 -A align, --align=align
57 Force the initial sample to be aligned on the boundary of a natu‐
58 ral time unit align. Refer to PCPIntro(1) for a complete descrip‐
59 tion of the syntax for align.
60 -c configfile, --view=configfile
62 configfile specifies an initial view to load, using the default
63 source of metrics. Multiple -c views can be specified, and they
64 will all be opened in the default Tab with the default source of
65 metrics.
66 -c, --check
68 Used with -c, the view(s) are parsed, any errors are reported, and
69 the tool exits. This is primarily intended for testing purposes.
70 If a second -C option is presented, pmchart also connects to
71 pmcd(1) to check the semantics of metrics.
72 -f family, --font-family=family
74 Specify the default font family to be used in several chart compo‐
75 nents, such as the chart title, legend, and Y-axis label. The
76 default value is "Sans Serif". This setting does not affect the
77 rest of the user interface, where the value is inherited from the
78 environment in which pmchart operates, and differs according to
79 the look-and-feel of each platform.
80 -F point, --font-size=point
82 Specify the default font point size to be used in several chart
83 components, such as the chart title, legend, and Y-axis label.
84 The default is platform dependent, but is either 7, 8 or 9. This
85 setting does not affect the rest of the user interface.
86 -g geometry, --geometry=geometry
88 Generate image with the specified geometry (width and height).
89 This option is only useful when used in conjunction with the -o
90 option for generating an output image. The geometry argument
91 takes the form "WxH" (e.g. 240x120). When NOT using the -o flag,
92 to specify the display window geometry, use -geometry geometry
93 where geometry specifies the desired window width, height and
94 optional placement.
95 -h host, --host=host
97 Current performance metric values are retrieved from the nominated
98 host machine by default. Multiple -h options can be presented,
99 and the list of hosts is used for sourcing metric values. Any
100 sources listed on the command line are assumed to be hosts if this
101 option is used.
102 -H path, --hostsfile=path
104 Specify the path to a file containing a set of hostnames where
105 pmcd(1) is running , rather than using the default localhost.
106 -K spec, --spec-local=spec
108 When fetching metrics from a local context (see -L), the -K option
109 may be used to control the DSO PMDAs that should be made accessi‐
110 ble. The spec argument conforms to the syntax described in
111 pmSpecLocalPMDA(3). More than one -K option may be used.
112 -L, --local-PMDA
114 Use a local context to collect metrics from DSO PMDAs on the local
115 host without PMCD. See also -K.
116 -o outfile, --output=outfile
118 Generate an image file named outfile, and then exit. This is most
119 useful when run with a set of archives and one or more views. The
120 generated image will be in the format specified as the file exten‐
121 sion (automatically determined from outfile). If no extension can
122 be determined, then the GIF format is used and the generated file
123 is named with this extension. The supported image file formats
124 include: bmp, jpeg, jpg, png, ppm, tif, tiff, xbm, and xpm.
125 -O origin, --origin=origin
127 When reporting archived metrics, start reporting at origin within
128 the time window (see -S and -T). Refer to PCPIntro(1) for a com‐
129 plete description of the syntax for origin.
130 -p port, --port=port
132 port number for connection to an existing pmtime time control
133 process.
134 -s samples, --samples=samples
136 Specifies the number of samples that will be retained before dis‐
137 carding old data (replaced by new values at the current time posi‐
138 tion). This value can subsequently be modified through the Edit
139 Tab dialog.
140 -S starttime, --start=starttime
142 When reporting archived metrics, the report will be restricted to
143 those records logged at or after starttime. Refer to PCPIntro(1)
144 for a complete description of the syntax for starttime.
145 -t interval, --interval=interval
147 Sets the inital update interval to something other than the
148 default 1 second. The interval argument follows the syntax
149 described in PCPIntro(1), and in the simplest form may be an
150 unsigned integer (the implied units in this case are seconds).
151 -T endtime, --finish=endtime
153 When reporting archived metrics, the report will be restricted to
154 those records logged before or at endtime. Refer to PCPIntro(1)
155 for a complete description of the syntax for endtime.
156 -v samples, --visible=samples
158 Sets the initial visible samples that will be displayed in all
159 charts in the default Tab. This value must be less than or equal
160 to the total number of samples retained (the -s value).
161 -V, --version
163 Display pmchart version number and exit
164 -W, fB--white
166 Export images using an opaque(white) background
167 -z, --hostzone
169 Change the reporting timezone to the local timezone at the host
170 that is the source of the performance metrics, as identified via
171 either the -h or -a options.
172 The -S, -T, -O and -A options may be used to define a time window to
174 restrict the samples retrieved, set an initial origin within the time
175 window, or specify a "natural" alignment of the sample times; refer
176 to PCPIntro(1) for a complete description of these options.
177 -Z timezone, --timezone=timezone
179 By default, pmtime reports the time of day according to the
180 local timezone on the system where pmchart is run. The -Z
181 option changes the timezone to timezone in the format of the
182 environment variable TZ as described in environ(7).
183
185 The primary pmchart configuration file is the "view", which allows the
186 metadata associated with one or more charts to be saved in the filesys‐
187 tem. This metadata describes all aspects of the charts, including
188 which PCP metrics and instances are to be used, which hosts, which col‐
189 ors, the chart titles, use of chart legends, and much more.
190 From a conceptual point of view, there are two classes of view. These
192 views share the same configuration file format - refer to a later sec‐
193 tion for a complete description of this format. The differences lie in
194 where they are installed and how they are manipulated.
195 The first class, the "system" view, is simply any view that is
197 installed as part of the pmchart package. These are stored in
198 $PCP_VAR_DIR/config/pmchart. When the File→Open View dialog is dis‐
199 played, it is these views that are initially listed. The system views
200 cannot be modified by a normal user, and should not be modified even by
201 a user with suitable privileges, as they will be overwritten during an
202 upgrade.
203 The second class of view is the "user" view. These views are created
205 on-the-fly using the File→Save View dialog. This is a mechanism for
206 individual users to save their commonly used views. Access to these
207 views is achieved through the File→Open View dialog, as with the system
208 views. Once the dialog is opened, the list of views can be toggled
209 between user and system views by clicking on the two toggle buttons in
210 the top right corner. User views are stored in $HOME/.pcp/pmchart.
211
213 pmchart provides the common user interface concept of the Tab, which is
214 most prevalent in modern web browsers. Tabs allow pmchart to update
215 many more charts than the available screen real estate allows, by pro‐
216 viding a user interface mechanism to stack (and switch between) differ‐
217 ent vertical sets of charts. Switching between Tabs is achieved by
218 clicking on the Tab labels, which are located along the top of the dis‐
219 play beneath the Menu and Tool bars).
220 Each Tab has a mode of operation (either live or archive - pmchart can
222 support both modes simultaneously), the total number of samples and
223 currently visible points, and a label describing the Tab which is dis‐
224 played at the top of the pmchart window. New Tabs can be created using
225 the File→Add Tab dialog.
226 In order to save on vertical screen real estate, note that the user
228 interface element for changing between different Tabs (and its label)
229 are only displayed when more than one Tab exists. A Tab can be dis‐
230 missed using the File→Close Tab menu, which removes the current Tab and
231 any charts it contained.
232
234 A static copy of the currently displayed vertical series of charts can
235 be captured in two ways.
236 When the intended display device is the screen, the File→Export menu
238 option should be used. This allows exporting the charts in a variety
239 of image formats, including PNG, JPEG, GIF, and BMP. The image size
240 can be scaled up or down in any dimension.
241 Alternatively, when the intended display device is paper, the
243 File→Print menu option can be used. This supports the usual set of
244 printing options (choice of printer, grayscale/color, landscape/por‐
245 trait, scaling to different paper sizes, etc), and in addition allows
246 printing to the intermediate printer formats of PostScript and Portable
247 Document Format (PDF).
248
250 It is possible to make a recording of a set of displayed charts, for
251 later playback through pmchart or any of the other Performance Co-Pilot
252 tools. The Record→Start functionality is simple to configure through
253 the user interface, and allows fine-tuning of the recording process
254 (including record frequencies that differ to the pmchart update inter‐
255 val, alternate file locations, etc).
256 pmchart produces recordings that are compatible with the PCP pmafm(1)
258 replay mechanism, for later playback via a new instance of pmchart. In
259 addition, when recording through pmchart one can also replay the
260 recording immediately, as on termination of the recording (through the
261 Record→Stop menu item), an archive mode Tab will be created with the
262 captured view.
263 Once recording is active in a Live Tab, the Time Control status button
265 in the bottom left corner of the pmchart window is displayed with a
266 distinctive red dot. At any time during a pmchart recording session,
267 the amount of space used in the filesystem by that recording can be
268 displayed using the Record→Query menu item.
269 Finally, the Record→Detach menu option provides a mechanism whereby the
271 recording process can be completely divorced from the running pmchart
272 process, and allowed to continue on when pmchart exits. A dialog dis‐
273 playing the current size and estimated rate of growth for the recording
274 is presented. On the other hand, if pmchart is terminated while
275 recording is in process, then the recording process will prompt the
276 user to choose immediate cessation of recording or for it to continue
277 on independently.
278 All of the record mode services available from pmchart are implemented
280 with the assistance of the base Performance Co-Pilot logging services -
281 refer to pmlogger(1) and pmafm(1) for an extensive description of the
282 capabilities of these tools.
283
285 pmchart loads predefined chart configurations (or "views") from exter‐
286 nal files that conform to the following rules. In the descriptions
287 below keywords (shown in bold) may appear in upper, lower or mixed
288 case, elements shown in [stuff] are optional, and user-supplied ele‐
289 ments are shown as <other stuff>. A vertical bar (|) is used where
290 syntactic elements are alternatives. Quotes (") may be used to enclose
291 lexical elements that may contain white space, such as titles, labels
292 and instance names.
293 1. The first line defines the configuration file type and should be
295 #kmchart
296 although pmchart provides backwards compatibility for the older
297 pmchart view formats with an initial line of
298 #pmchart
299 2. After the first line, lines beginning with "#" as the first non-
301 white space character are treated as comments and skipped. Simi‐
302 larly blank lines are skipped.
303 3. The next line should be
305 version <n> <host-clause>
306 where <n> depends on the configuration file type, and is 1 for
307 pmchart else 1.1, 1.2 or 2.0 for pmchart.
308 The <host-clause> part is optional (and ignored) for pmchart config‐
309 uration files, but required for the pmchart configuration files, and
310 is of the form
311 host literal
312 or
313 host dynamic
314 4. A configuration contains one or more charts defined as follows:
316 chart [title <title>] style <style> <options>
317 If specified, the title will appear centred and above the graph area
318 of the chart. The <title> is usually enclosed in quotes (") and if
319 it contains the sequence "%h" this will be replaced by the short
320 form of the hostname for the default source of metrics at the time
321 this chart was loaded. Alternatively, "%H" can be used to insert
322 the full host name. If the hostname appears to be an inet or IPv6
323 address, no shortening will be attempted; it will be used as-is in
324 both replacement cases. After the view is loaded, the title visi‐
325 bility and setting can be manipulated using the Chart Title text box
326 in the Edit→Chart dialog.
327 The <style> controls the initial plotting style of the chart, and
329 should be one of the keywords plot (line graph), bar, stacking
330 (stacked bar), area or utilization. After the view is loaded, the
331 plotting style can be changed using the Edit→Chart Style dropdown
332 list.
333 The <options> are zero or more of the optional elements:
335 [scale [from] <ymin> [to] <ymax>] [legend <onoff>]
336 If scale is specified, the vertical scaling is set for all plots in
337 the chart to a y-range defined by <ymin> and <ymax>. Otherwise the
338 vertical axis will be autoscaled based on the values currently being
339 plotted.
340 <onoff> is one of the keywords on or off and the legend clause con‐
342 trols the presence or absence of the plot legend below the graph
343 area. The default is for the legend to be shown. After the view is
344 loaded, the legend visibility can be toggled using the Show Legend
345 button in the Edit→Chart dialog.
346 5. pmchart supports a global clause to specify the dimensions of the
348 top-level window (using the width and height keywords), the number
349 of visible points (points keyword) and the starting X and Y axis
350 positions on the screen (xpos and ypos keywords). Each of these
351 global attributes takes an integer value as the sole qualifier.
352 6. Each chart has one or more plots associated with it, as defined by
354 one of the following specifications:
355 plot
356 [legend <title>] [color <colorspec>] [host <hostspec>]
357 metric <metricname>
358 [ instance <inst> | matching <pat> | not-matching <pat> ]
359 The keyword plot may be replaced with the keyword optional-plot, in
361 which case if the source of performance data does not include the
362 specified performance metric and/or instance, then this plot is
363 silently dropped from the chart.
364 If specified, the title will appear in the chart legend. The
366 <title> is usually enclosed in quotes (") and it may contain one or
367 more wildcard characters which will be expanded using metric name,
368 instance name, and host name for the plot. The wildcards are "%i"
369 (short unique instance name, up to the first whitespace), "%I" (full
370 instance name), "%h" (short host name, up to the first dot), %H
371 (full host name), "%m" (metric name shortened to the final two PMNS
372 components), and "%M" (full metric name).
373 For older pmchart configuration files, the keyword title must be
375 used instead of legend. Nowadays pmchart supports either keyword.
376 The color clause is optional for newer pmchart configuration files,
378 but it was mandatory in the original pmchart configuration file for‐
379 mat. <colorspec> may be one of the following:
380 #-cycle
381 rgbi:rr:gg:bb
382 #rgb
383 #rrggbb
384 #rrrgggbbb
385 #rrrrggggbbbb
386 <Xcolor>
387 where each of r, g and b are hexadecimal digits (0-9 and A-F) repre‐
388 senting respectively the red, green and blue color components.
389 <Xcolor> is one of the color names from the X color database, e.g.
390 red or steelblue, see also the output from showrgb(1).
391 The "color" #-cycle specifies that pmchart should use the next in a
393 pallet of colors that it uses cyclically for each chart. This is
394 the default if the color clause is omitted.
395 The <hostspec> in the host clause may be a hostname, an IP address
397 or an asterisk (*); the latter is used to mean the default source of
398 performance metrics. For older pmchart configuration files, the
399 host clause must be present, for new pmchart configuration files it
400 is optional, and if missing the default source of performance met‐
401 rics will be used.
402 The optional instance specification,
404 (a)
406 is omitted in which case one plot will be created for every
407 instance of the <metricname> metric
408 (b)
410 starts with instance, in which case only the instance named
411 <inst> will be plotted
412 (c)
414 starts with matching, in which case all instances whose names
415 match the pattern <pat> will be plotted; the pattern uses
416 extended regular expression notation in the style of egrep(1)
417 (refer to the PMCD view for an example)
418 (d)
420 starts with not-matching, in which case all instances whose names
421 do not match the pattern <pat> will be plotted; the pattern
422 uses extended regular expression notation in the style of
423 egrep(1) (refer to the Netbytes view for an example)
424 pmchart uses a bizarre syntactic notation where <inst> and <pat>
426 extend from the first non-white space character to the end of the
427 input line. For pmchart configuration files these elements are
428 either delimited by white space, or enclosed in quotes (").
429 7. The optional tab directive can be used to create views with multiple
431 charts which span multiple Tabs. The syntax is as follows:
432 tab <label> [host <host>] [points <points> [samples <samples>]]
433 All chart specifications following this keyword will be created
435 on the new Tab, until the end of the configuration file or until
436 another tab keyword is encountered.
437
439 Environment variables with the prefix PCP_ are used to parameterize the
440 file and directory names used by PCP. On each installation, the file
441 /etc/pcp.conf contains the local values for these variables. The
442 $PCP_CONF variable may be used to specify an alternative configuration
443 file, as described in pcp.conf(5).
444 Of particular note, the $PCP_XCONFIRM_PROG setting is explicitly and
446 unconditionally overridden by pmchart. This is set to the pmcon‐
447 firm(1), utility, in order that some popup dialogs (particularly in the
448 area of Recording) maintain a consistent look-and-feel with the rest of
449 the pmchart application.
450
452 pmtime(1), pmconfirm(1), pmdumptext(1), PCPIntro(1), pmafm(1),
453 pmrep(1), pmval(1), pmcd(1), pminfo(1), pcp.conf(5), pcp.env(5) and
454 PMNS(5).
455Performance Co-Pilot PMCHART(1)