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