1PMVIEW(1) General Commands Manual PMVIEW(1)
2
6 pmview - performance metrics 3D visualization back-end
7
9 pmview [-Cz] [-A align] [-a archive[,archive,...]] [-c configfile] [-h
10 host] [-n pmnsfile] [-O origin] [-p port] [-R logconfig] [-r addconfig]
11 [-S starttime] [-t interval] [-T endtime] [-x version] [-Z timezone]
12 [-geometry geometry] [-display display] [-name name] [-title title]
13 [-xrm "resourceName: value" ...] [other X11-args]
14
16 pmview is a generalized 3D performance metrics visualization tool for
17 the Performance Co-Pilot (PCP(1)).
18 pmview is the base utility behind performance metrics visualization
20 tools such as dkvis(1), mpvis(1), osvis(1) and nfsvis(1), It is also
21 used by a range of related tools that are specific to optional Perfor‐
22 mance Domain Agents (PMDA) and/or PCP add-on products. pmview may also
23 be used to construct customized 3D performance displays.
24 pmview displays performance metrics as colored blocks and cylinders
26 arranged on monochrome base planes. Each object may represent a single
27 performance metric, or a stack of several performance metrics. Since
28 the objects are modulated by the value of the metric they represent,
29 only numerical metrics may be visualized. Objects representing a sin‐
30 gle metric may be modulated in terms of height, color, or height and
31 color. Objects in a stack may only be height modulated, but the stack
32 can be normalized to the maximum height. Labels may be added to the
33 scene to help identify groups of metrics.
34 A configuration file (as specified by the -c option, or read from stan‐
36 dard input) is used to specify the position, color, maximum value and
37 labels of metrics and metric instances in the scene. The maximum value
38 acts as a normalization factor and is used to scale the object height
39 and/or color in proportion to the metric values. Metric values which
40 exceed the associated maximum value are displayed as solid white
41 objects. If a metric is unavailable, the object will have minimum
42 height and will be colored grey.
43 Normally, the tool operates in ``live'' mode where performance metrics
45 are fetched in real-time. The user can view metrics from any host run‐
46 ning pmcd(1). pmview can also replay archives of performance metrics
47 (see pmlogger(1)) and allow the user to interactively control the cur‐
48 rent replay time and rate using the VCR paradigm. This is particularly
49 useful for retrospective comparisons and for post-mortem analysis of
50 performance problems where a remote system is not accessible or a per‐
51 formance analyst is not available on-site.
52 All metrics in the Performance Metrics Name Space (PMNS) with numeric
54 value semantics from any number of hosts or archives may be visualized.
55 pmview examines the semantics of the metrics and where sensible, con‐
56 verts metric values to a rate before scaling.
57
59 The -S, -T, -O and -A options may be used to define a time window to
60 restrict the samples retrieved, set an initial origin within the time
61 window, or specify a ``natural'' alignment of the sample times; refer
62 to PCPIntro(1) for a complete description of these options.
63 The other available options are:
65 -a archive[,archive,...]]
67 Specify an archive from which metrics can be obtained for a par‐
68 ticular host. archive is the basename of an archive, previously
69 created by pmlogger(1). Multiple archives (separated by commas
70 or in different -a options) from different hosts may be given,
71 but an error will occur if there is more than one archive from
72 the same host. Any metrics that are not associated with a spe‐
73 cific host or archive in the configuration file will use the
74 first archive as their source.
75 -C Parse the configuration file and exit before displaying the
77 pmview window. Any errors in the configuration file are dis‐
78 played.
79 -c configfile
81 Load the configuration from configfile rather than standard
82 input.
83 -h host
85 Fetch performance metrics from pmcd(1) on host, rather than the
86 default localhost. Implies that pmview will run in live mode,
87 so no archives can be specified on the command line or in the
88 configuration file. Only one -h option may be given.
89 -n pmnsfile
91 Normally pmview operates on the distributed Performance Metrics
92 Name Space (PMNS), however if the -n option is specified an
93 alternative local PMNS is loaded from the file pmnsfile.
94 -p port
96 Connect to the time controls (see pmtime(1)) on this port. Used
97 when a tool launches another tool so that they can connect to
98 the same time controls.
99 -R logconfig
101 Use logconfig as the pmlogger(1) config when recording.
102 -r addconfig
104 Append addconfig onto the pmlogger(1) config generated by pmview
105 when recording.
106 -t interval
108 The update interval used to fetch metrics from the live or ar‐
109 chive sources. The interval argument follows the syntax
110 described in PCPIntro(1), and in the simplest form may be an
111 unsigned integer (the implied units in this case are seconds).
112 The default is 2.0 seconds.
113 -x version
115 Use the specified version of the pmlaunch(5) specification. The
116 versions currently supported are ``1.0'' and the default version
117 ``2.0''.
118 -Z timezone
120 By default, pmview reports the time of day according to the
121 local timezone on the system where pmview is run. The -Z option
122 changes the default timezone to timezone which should be in the
123 format of the environment variable TZ as described in envi‐
124 ron(7).
125 -z Change the reporting timezone to the local timezone at the host
127 that is the source of the performance metrics, as identified via
128 either the -h option, or the first -a option.
129 -geometry geometry
131 -display display
132 -name name
133 -title title
134 -xrm "resourceName: value"
135 Most standard X(1) command line arguments may be used.
137
139 The pmview window is comprised of a menu bar, time and scale controls,
140 metric and time values, and an ``examiner'' viewer (see ivview(1)),
141 which displays the 3D scene.
142
144 The left, right and bottom edges of the examiner viewer contain a vari‐
145 ety of thumb wheels and buttons that can be used to adjust the visual‐
146 ization of the 3D scene. The Rotx and Roty thumb wheels allow the user
147 to rotate the scene about the x and y axes, respectively. The dolly
148 thumb wheel moves the virtual camera closer and further from the scene
149 allowing the user to examine specific parts in detail or view the
150 entire scene. On the right edge of the viewer are eight buttons which
151 affect the way the user can interact with the scene.
152 Pointer
154 Changes the cursor to a pointer which allows blocks to be selected
155 in the scene. See the Metric Selection section below.
156 Hand
158 Changes the cursor to a hand which allows the scene to be rotated,
159 translated and dollied using a combination of mouse buttons. The
160 left mouse button can be used to rotate the scene in the direction
161 of the mouse. Releasing the left mouse button before the mouse has
162 stopped moving will cause the scene to continue to rotate, which
163 can be stopped by pressing the left mouse button again. The middle
164 mouse button will ``pan'' the scene, and both mouse buttons act as
165 a dolly for the virtual camera.
166 Question Mark
168 Displays the SGI Help information for the examiner viewer.
169 Home
171 Changes the scene back to its original position, unless the home
172 position has been changed by the home pointer button.
173 Home Pointer
175 Changes the home position of the scene to be the scene currently in
176 view.
177 Eye Resizes the scene so that it completely fits into the 3D viewing
179 area.
180 Cross-hairs
182 Moves the object under the cursor to the center of the viewing
183 area, if the hand cursor has been selected. Pressing the ``s'' key
184 while the cursor is over an object has the same effect.
185 Perspective Box
187 Switches the display between perspective and orthogonal projec‐
188 tions.
189 Pressing the right mouse button within the scene window will bring up a
191 menu of options which affect how the 3D scene is drawn. The options
192 include drawing the blocks as wire frames, and turning on stereo view‐
193 ing.
194
196 When the pointer cursor is active, more information about the 3D scene
197 can be obtained. Text describing the metric represented by the block
198 under the cursor will be displayed in the top text box of the pmview
199 window. The text contains the source and name of the metric, current
200 value and units, and the percentage of the expected maximum (or normal‐
201 ization) value. The text box is updated whenever the scene is updated
202 with the latest metric values or when the cursor is moved over another
203 block in the scene. Moving the cursor over a base plane block, text or
204 the surrounding space will clear the text box.
205 Clicking the left mouse button on a block will bind the text box on
207 that metric instance so that the metric can be monitored while perform‐
208 ing other actions with the mouse. The block will be highlighted with a
209 red wire frame. Clicking the left mouse button on text or the space
210 surrounding the scene will unselect the object, causing the text box to
211 revert to the original behavior of showing the metric underneath the
212 cursor.
213 Selecting a base plane instead of a modulated block will cause all the
215 blocks on that base plane to be selected. When more than one object is
216 selected, the text box behaves as if nothing is selected, so the metric
217 displayed is the metric currently under the cursor. Multiple selec‐
218 tions are also possible by pressing the SHIFT key while selecting an
219 object with the left mouse button.
220
222 There are four menus in pmview's user interface which allow scenes to
223 be recorded, saved and printed (File), access to the time controls
224 (Options), launching other tools (Launch) and online help (Help).
225 File/Record
227 When in ``live'' mode, this option will launch pmlogger(1) pro‐
228 cesses to record the current scene into an archive folio (see
229 pmafm(1)) so that it may be replayed at a later time. This option
230 is not available in ``replay'' mode.
231 When File/Record is selected, a file chooser dialog will prompt for
233 the name of the new archive folio. If the directory to the folio
234 does not exist, pmview will attempt to create it. It is usually
235 convenient to keep each folio within its own directory as there
236 will be several other files associated with the folio, including
237 the generated archives.
238 Once a valid folio has been created, pmview will launch a pmlog‐
240 ger(1) process for each host to collect the metrics required from
241 that host in the current scene. The current selections do not
242 affect the set of metrics that are recorded.
243 While recording is in progress, a red dot will appear in the time
245 controls button in the top left-hand corner of the pmview window.
246 The File/Record option will also change to File/Stop Recording as
247 only one recording session is possible at any one time. Selecting
248 blocks or launching other tools will have no affect on the record‐
249 ing session.
250 The record session may be terminated by selecting File/Stop Record‐
252 ing. This will display dialogs for each pmlogger(1) instance
253 describing the size and location of the archive files before termi‐
254 nating each process. When all pmlogger(1) processes have been ter‐
255 minated, the red dot is removed from the time controls button, and
256 the menu reverts back to File/Record to allow another recording
257 session to take place.
258 If the application exists while recording, a dialog will appear
260 allowing you to terminate each pmlogger(1) process, or leave it
261 running unattached.
262 An archive folio may be replayed using the command: ``pmafm folio
264 replay''. See pmafm(1) for more details.
265 It is not uncommon for a front-end script which generates a pmview
267 scene to use metrics that are not contained in the scene. For
268 example, osvis(1) uses several hinv metrics to determine the size
269 and layout of some objects. As these metrics are also needed when
270 replaying the generated archive with the front-end script, a com‐
271 plete pmlogger(1) config can be specified (-R) that overrides the
272 pmview generated config, or an additional config can be appended
273 (-r) to the pmview generated config.
274 File/Save
276 Saves the current scene to a human-readable Open Inventor file (see
277 inventor(1)). A file dialog will prompt for the location of the
278 file. The default file extension is ``.iv'' which is recognized by
279 ivview(1) and some Web browsers.
280 File/Print
282 Outputs the current scene to a printer. A print dialog will be
283 displayed allowing a specific printer to be selected.
284 File/Quit
286 pmview immediately exits. If recording was active, dialogs will be
287 displayed for each pmlogger(1) process so that they may be termi‐
288 nated.
289 Options/Show Time Control
291 Displays the time controls (see pmtime(1)) that are driving this
292 instance of pmview. The time controls may be shared by other
293 tools, including pmchart(1), that have been launched by other
294 instances of pmview and oview(1). Therefore, this menu item may
295 appear to have no affect if the time controls are already visible.
296 Options/New Time Control
298 Disconnect with the current time controls (which may be shared by
299 other tools, see pmtime(1)) and use a new time control that is not
300 connected to any other tools. The new time control will be immedi‐
301 ately displayed.
302 Launch
304 The launch menu is generated from a menu specification file (see
305 pmlaunch(5)). The menu contains tools that may be launched based
306 on the sources and names of the selected metrics in the scene. For
307 example, if the selected metrics are from three different hosts,
308 then three copies of a tool may be launched, one for each host.
309 The behavior of a launch depends on the selected metrics and the
310 tools being launched.
311 On selection of a Launch menu item pmview generates state informa‐
313 tion in the pmlaunch(5) metrics specification format. This pro‐
314 vides a description of the selected metrics (or if there are no
315 selections, all the metrics) in the scene without any geometry
316 information.
317 Tools which can monitor multiple hosts and user specified metrics
319 may be launched only once for those metrics (eg pmdumptext(1)).
320 Other tools which have a fixed view for one host (eg mpvis(1)), may
321 be launched multiple times, once for each host in the selected met‐
322 ric list. If the launched tools have time controls, they will
323 share the time controls with the launching pmview.
324 The set of launched tools is configurable, and may include IRIX and
326 user applications. See pmlaunch(5) for more details.
327 Help/...
329 If pcp.books.help has been installed, then the insight(1) books for
330 pmview are displayed.
331
333 In addition to the menu options for time controls, the current direc‐
334 tion of the time controls (see pmtime(1)) is shown in a button in the
335 top-left corner of the pmview window. Pressing this button will dis‐
336 play the time control and is identical in behavior to Options/Show Time
337 Control.
338
340 Above the examiner window is a thumb wheel and an editable text box
341 which allow the user to apply a multiplier to all values represented in
342 the scene. Spinning the wheel to the right and/or increasing the text
343 value for the scale will increase the height of the bars. Spinning the
344 wheel to the left and/or lowering the text value will decrease the
345 height of the bars. The button to the right of the thumb wheel will
346 reset the scale so that the bars appear at the original height for
347 their current value.
348
350 Beside the scale controls is another text box which displays the time
351 of the fetched metrics. The time will change with the time controller
352 (see pmtime(1)).
353
355 The default face of the 3D font in the pmview window can be altered via
356 PMVIEW_FONT environment variable which can be set to the base name of a
357 Type1 font file in the default Inventor fonts directory.
358
360 $PCP_VAR_DIR/pmns/*
361 default PMNS specification files
362 $PCP_VAR_DIR/config/pmlaunch/pmlaunchrc
364 menu specification file - provides a mapping between menu
365 item and launched program
366 $HOME/.pcp/pmlaunch/pmlaunchrc
368 individual users menu specification
369 /usr/lib/X11/app-defaults/PmView
371 application resources
372 /usr/lib/images/PmView.icon
374 icon for pmview
375 $PCP_SHARE_DIR/lib/pmview-args
377 shell procedures for parsing pmview command line options in
378 front end scripts
379 /usr/lib/DPS/outline/base/
381 directory where Inventor normally looks for the outlines of
382 Type1 fonts.
383
385 Environment variables with the prefix PCP_ are used to parameterize the
386 file and directory names used by PCP. On each installation, the file
387 /etc/pcp.conf contains the local values for these variables. The
388 $PCP_CONF variable may be used to specify an alternative configuration
389 file, as described in pcp.conf(5).
390
392 dkvis(1), insight(1), inventor(1), ivview(1), mpvis(1), nfsvis(1),
393 osvis(1), oview(1), pcp(1), PCPIntro(1), pmafm(1), pmcd(1), pmchart(1),
394 pmdumptext(1), pmlogger(1), pmtime(1), pmview(1), X(1), xconfirm(1),
395 xlv_vis(1), pcp.conf(5), pmview(5), environ(7) and pmlaunch(5).
396 Relevant information is also available from the on-line PCP Tutorial.
398 Provided the pcp.man.tutorial subsystem from the PCP images has been
399 installed, access the URL file:$PCP_DOC_DIR/Tutorial/pmview.html from
400 your web browser.
401
404 Are intended to be self-explanatory. The environment variable
405 PCP_STDERR can be set to force most startup warnings and errors to be
406 sent to the standard error stream rather than posted in a dialog.
407Performance Co-Pilot PMVIEW(1)