1PMVIEW(1)                   General Commands Manual                  PMVIEW(1)
2
3
4

NAME

6       pmview - performance metrics 3D visualization back-end
7

SYNOPSIS

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

DESCRIPTION

16       pmview  is  a generalized 3D performance metrics visualization tool for
17       the Performance Co-Pilot (PCP(1)).
18
19       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
25       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
35       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
44       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
53       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

COMMAND LINE OPTIONS

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
64       The other available options are:
65
66       -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
76       -C     Parse  the  configuration  file  and  exit before displaying the
77              pmview window.  Any errors in the configuration  file  are  dis‐
78              played.
79
80       -c configfile
81              Load  the  configuration  from  configfile  rather than standard
82              input.
83
84       -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
90       -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
95       -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
100       -R logconfig
101              Use logconfig as the pmlogger(1) config when recording.
102
103       -r addconfig
104              Append addconfig onto the pmlogger(1) config generated by pmview
105              when recording.
106
107       -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
114       -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
119       -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
126       -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
130       -geometry geometry
131       -display display
132       -name name
133       -title title
134       -xrm "resourceName: value"
135
136              Most standard X(1) command line arguments may be used.
137

WINDOW

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

EXAMINER VIEWER

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
153       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
157       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
167       Question Mark
168           Displays the SGI Help information for the examiner viewer.
169
170       Home
171           Changes  the  scene  back to its original position, unless the home
172           position has been changed by the home pointer button.
173
174       Home Pointer
175           Changes the home position of the scene to be the scene currently in
176           view.
177
178       Eye Resizes  the  scene  so that it completely fits into the 3D viewing
179           area.
180
181       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
186       Perspective Box
187           Switches the display between  perspective  and  orthogonal  projec‐
188           tions.
189
190       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

METRIC SELECTION

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
206       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
214       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
226       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
232           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
239           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
244           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
251           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
259           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
263           An  archive  folio may be replayed using the command: ``pmafm folio
264           replay''.  See pmafm(1) for more details.
265
266           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
275       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
281       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
285       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
290       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
297       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
303       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
312           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
318           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
325           The set of launched tools is configurable, and may include IRIX and
326           user applications.  See pmlaunch(5) for more details.
327
328       Help/...
329           If pcp.books.help has been installed, then the insight(1) books for
330           pmview are displayed.
331

TIME CONTROLS

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

SCALE CONTROLS

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

TIME INFORMATION

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

ENVIRONMENT

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

FILES

360       $PCP_VAR_DIR/pmns/*
361                 default PMNS specification files
362
363       $PCP_VAR_DIR/config/pmlaunch/pmlaunchrc
364                 menu specification file - provides  a  mapping  between  menu
365                 item and launched program
366
367       $HOME/.pcp/pmlaunch/pmlaunchrc
368                 individual users menu specification
369
370       /usr/lib/X11/app-defaults/PmView
371                 application resources
372
373       /usr/lib/images/PmView.icon
374                 icon for pmview
375
376       $PCP_SHARE_DIR/lib/pmview-args
377                 shell  procedures  for parsing pmview command line options in
378                 front end scripts
379
380       /usr/lib/DPS/outline/base/
381                 directory where Inventor normally looks for the  outlines  of
382                 Type1 fonts.
383

PCP ENVIRONMENT

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

SEE ALSO

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
397       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
402

DIAGNOSTICS

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.
407
408
409
410Performance Co-Pilot                                                 PMVIEW(1)
Impressum