NAME
pmview+ - performance metrics 3D visualization back-end
SYNOPSIS
pmview+ [-Cz] [-A align] [-a archive[,archive,...]] [-c configfile] [-h
host] [-n pmnsfile] [-O origin] [-p port] [-R logconfig] [-r addconfig]
[-S starttime] [-t interval] [-T endtime] [-x version] [-Z timezone]
[-geometry geometry] [-display display] [-name name] [-title title] [-xrm
"resourceName: value" ...] [other X11-args]
DESCRIPTION
pmview+ is an extension of pmview(1) - a generalized 3D performance
metrics visualization tool for the Performance Co-Pilot (PCP(1)). It is
compatible with pmview (with an exception that version 1 configuration
files are not supported) while adding support for ``plumbing'', i.e.
interconnects between the bases of pmview's grids. Interconnects could be
represented either as unanimated links, or animated pipes with associated
metrics.
pmview+ is used by oview(1) to display information about Origin 3000
servers. pmview+ is the base utility behind performance metrics
visualization tools such as dkvis(1), mpvis(1), osvis(1), nfsvis(1),
nodevis(1), routervis(1), xbowvis(1) and xlv_vis(1). It is also used by
a range of related tools that are specific to optional Performance Domain
Agents (PMDA) and/or PCP add-on products. pmview+ may also be used to
construct customized 3D performance displays.
pmview+ displays performance metrics as colored blocks and cylinders
arranged on monochrome base planes. Each object may represent a single
performance metric, or a stack of several performance metrics. Since the
objects are modulated by the value of the metric they represent, only
numerical metrics may be visualized. Objects representing a single
metric may be modulated in terms of height, color, or height and color.
Objects in a stack may only be height modulated, but the stack can be
normalized to the maximum height. Labels may be added to the scene to
help identify groups of metrics.
A configuration file (as specified by the -c option, or read from
standard input) is used to specify the position, color, maximum value and
labels of metrics and metric instances in the scene. The maximum value
acts as a normalization factor and is used to scale the object height
and/or color in proportion to the metric values. Metric values which
exceed the associated maximum value are displayed as solid white objects.
If a metric is unavailable, the object will have minimum height and will
be colored grey.
Normally, the tool operates in ``live'' mode where performance metrics
are fetched in real-time. The user can view metrics from any host
running pmcd(1). pmview+ can also replay archives of performance metrics
(see pmlogger(1)) and allow the user to interactively control the current
replay time and rate using the VCR paradigm. This is particularly useful
for retrospective comparisons and for post-mortem analysis of performance
problems where a remote system is not accessible or a performance analyst
is not available on-site.
Page 1
1
PMVIEW+(1)PMVIEW+(1)
All metrics in the Performance Metrics Name Space (PMNS) with numeric
value semantics from any number of hosts or archives may be visualized.
pmview+ examines the semantics of the metrics and where sensible,
converts metric values to a rate before scaling.
COMMAND LINE OPTIONS
The -S, -T, -O and -A options may be used to define a time window to
restrict the samples retrieved, set an initial origin within the time
window, or specify a ``natural'' alignment of the sample times; refer to
PCPIntro(1) for a complete description of these options.
The other available options are:
-a archive[,archive,...]]
Specify an archive from which metrics can be obtained for a
particular host. archive is the basename of an archive, previously
created by pmlogger(1). Multiple archives (separated by commas or
in different -a options) from different hosts may be given, but an
error will occur if there is more than one archive from the same
host. Any metrics that are not associated with a specific host or
archive in the configuration file will use the first archive as
their source.
-C Parse the configuration file and exit before displaying the pmview+
window. Any errors in the configuration file are displayed.
-c configfile
Load the configuration from configfile rather than standard input.
-h host
Fetch performance metrics from pmcd(1) on host, rather than the
default localhost. Implies that pmview+ will run in live mode, so
no archives can be specified on the command line or in the
configuration file. Only one -h option may be given.
-n pmnsfile
Normally pmview+ operates on the distributed Performance Metrics
Name Space (PMNS), however if the -n option is specified an
alternative local PMNS is loaded from the file pmnsfile.
-p port
Connect to the time controls (see pmtime(1)) on this port. Used
when a tool launches another tool so that they can connect to the
same time controls.
-R logconfig
Use logconfig as the pmlogger(1) config when recording.
-r addconfig
Append addconfig onto the pmlogger(1) config generated by pmview+
when recording.
Page 2
PMVIEW+(1)PMVIEW+(1)-t interval
The update interval used to fetch metrics from the live or archive
sources. The interval argument follows the syntax described in
PCPIntro(1), and in the simplest form may be an unsigned integer
(the implied units in this case are seconds). The default is 2.0
seconds.
-x version
Use the specified version of the pmlaunch(5) specification. The
versions currently supported are ``1.0'' and the default version
``2.0''.
-Z timezone
By default, pmview+ reports the time of day according to the local
timezone on the system where pmview+ is run. The -Z option changes
the default timezone to timezone which should be in the format of
the environment variable TZ as described in environ(5).
-z Change the reporting timezone to the local timezone at the host that
is the source of the performance metrics, as identified via either
the -h option, or the first -a option.
-geometry geometry
-display display
-name name
-title title
-xrm "resourceName: value"
Most standard X(1) command line arguments may be used.
WINDOW
The pmview+ window is comprised of a menu bar, time and scale controls,
metric and time values, and an ``examiner'' viewer (see ivview(1)), which
displays the 3D scene.
EXAMINER VIEWER
The left, right and bottom edges of the examiner viewer contain a variety
of thumb wheels and buttons that can be used to adjust the visualization
of the 3D scene. The Rotx and Roty thumb wheels allow the user to rotate
the scene about the x and y axes, respectively. The dolly thumb wheel
moves the virtual camera closer and further from the scene allowing the
user to examine specific parts in detail or view the entire scene. On
the right edge of the viewer are eight buttons which affect the way the
user can interact with the scene.
Pointer
Changes the cursor to a pointer which allows blocks to be selected in
the scene. See the Metric Selection section below.
Hand
Changes the cursor to a hand which allows the scene to be rotated,
translated and dollied using a combination of mouse buttons. The
Page 3
PMVIEW+(1)PMVIEW+(1)
left mouse button can be used to rotate the scene in the direction of
the mouse. Releasing the left mouse button before the mouse has
stopped moving will cause the scene to continue to rotate, which can
be stopped by pressing the left mouse button again. The middle mouse
button will ``pan'' the scene, and both mouse buttons act as a dolly
for the virtual camera.
Question Mark
Displays the SGI Help information for the examiner viewer.
Home
Changes the scene back to its original position, unless the home
position has been changed by the home pointer button.
Home Pointer
Changes the home position of the scene to be the scene currently in
view.
Eye Resizes the scene so that it completely fits into the 3D viewing
area.
Cross-hairs
Moves the object under the cursor to the center of the viewing area,
if the hand cursor has been selected. Pressing the ``s'' key while
the cursor is over an object has the same effect.
Perspective Box
Switches the display between perspective and orthogonal projections.
Pressing the right mouse button within the scene window will bring up a
menu of options which affect how the 3D scene is drawn. The options
include drawing the blocks as wire frames, and turning on stereo viewing.
METRIC SELECTION
When the pointer cursor is active, more information about the 3D scene
can be obtained. Text describing the metric represented by the block
under the cursor will be displayed in the top text box of the pmview+
window. The text contains the source and name of the metric, current
value and units, and the percentage of the expected maximum (or
normalization) value. The text box is updated whenever the scene is
updated with the latest metric values or when the cursor is moved over
another block in the scene. Moving the cursor over a base plane block,
text or the surrounding space will clear the text box.
Clicking the left mouse button on a block will bind the text box on that
metric instance so that the metric can be monitored while performing
other actions with the mouse. The block will be highlighted with a red
wire frame. Clicking the left mouse button on text or the space
surrounding the scene will unselect the object, causing the text box to
revert to the original behavior of showing the metric underneath the
cursor.
Page 4
PMVIEW+(1)PMVIEW+(1)
Selecting a base plane instead of a modulated block will cause all the
blocks on that base plane to be selected. When more than one object is
selected, the text box behaves as if nothing is selected, so the metric
displayed is the metric currently under the cursor. Multiple selections
are also possible by pressing the SHIFT key while selecting an object
with the left mouse button.
MENUS
There are four menus in pmview+'s user interface which allow scenes to be
recorded, saved and printed (File), access to the time controls
(Options), launching other tools (Launch) and online help (Help).
File/Record
When in ``live'' mode, this option will launch pmlogger(1) processes
to record the current scene into an archive folio (see pmafm(1)) so
that it may be replayed at a later time. This option is not
available in ``replay'' mode.
When File/Record is selected, a file chooser dialog will prompt for
the name of the new archive folio. If the directory to the folio
does not exist, pmview+ will attempt to create it. It is usually
convenient to keep each folio within its own directory as there will
be several other files associated with the folio, including the
generated archives.
Once a valid folio has been created, pmview+ will launch a
pmlogger(1) process for each host to collect the metrics required
from that host in the current scene. The current selections do not
affect the set of metrics that are recorded.
While recording is in progress, a red dot will appear in the time
controls button in the top left-hand corner of the pmview+ window.
The File/Record option will also change to File/Stop Recording as
only one recording session is possible at any one time. Selecting
blocks or launching other tools will have no affect on the recording
session.
The record session may be terminated by selecting File/Stop
Recording. This will display dialogs for each pmlogger(1) instance
describing the size and location of the archive files before
terminating each process. When all pmlogger(1) processes have been
terminated, the red dot is removed from the time controls button, and
the menu reverts back to File/Record to allow another recording
session to take place.
If the application exists while recording, a dialog will appear
allowing you to terminate each pmlogger(1) process, or leave it
running unattached.
An archive folio may be replayed using the command: ``pmafm folio
replay''. See pmafm(1) for more details.
Page 5
PMVIEW+(1)PMVIEW+(1)
It is not uncommon for a front-end script which generates a pmview+
scene to use metrics that are not contained in the scene. For
example, osvis(1) uses several hinv metrics to determine the size and
layout of some objects. As these metrics are also needed when
replaying the generated archive with the front-end script, a complete
pmlogger(1) config can be specified (-R) that overrides the pmview+
generated config, or an additional config can be appended (-r) to the
pmview+ generated config.
File/Save
Saves the current scene to a human-readable Open Inventor file (see
inventor(1)). A file dialog will prompt for the location of the
file. The default file extension is ``.iv'' which is recognized by
ivview(1) and some Web browsers.
File/Print
Outputs the current scene to a printer. A print dialog will be
displayed allowing a specific printer to be selected.
File/Quit
pmview+ immediately exits. If recording was active, dialogs will be
displayed for each pmlogger(1) process so that they may be
terminated.
Options/Show Time Control
Displays the time controls (see pmtime(1)) that are driving this
instance of pmview+. The time controls may be shared by other tools,
including pmchart(1), that have been launched by other instances of
pmview+ and oview(1). Therefore, this menu item may appear to have
no affect if the time controls are already visible.
Options/New Time Control
Disconnect with the current time controls (which may be shared by
other tools, see pmtime(1)) and use a new time control that is not
connected to any other tools. The new time control will be
immediately displayed.
Launch
The launch menu is generated from a menu specification file (see
pmlaunch(5)). The menu contains tools that may be launched based on
the sources and names of the selected metrics in the scene. For
example, if the selected metrics are from three different hosts, then
three copies of a tool may be launched, one for each host. The
behavior of a launch depends on the selected metrics and the tools
being launched.
On selection of a Launch menu item pmview+ generates state
information in the pmlaunch(5) metrics specification format. This
provides a description of the selected metrics (or if there are no
selections, all the metrics) in the scene without any geometry
information.
Page 6
PMVIEW+(1)PMVIEW+(1)
Tools which can monitor multiple hosts and user specified metrics may
be launched only once for those metrics (eg pmdumptext(1)). Other
tools which have a fixed view for one host (eg mpvis(1)), may be
launched multiple times, once for each host in the selected metric
list. If the launched tools have time controls, they will share the
time controls with the launching pmview+.
The set of launched tools is configurable, and may include IRIX and
user applications. See pmlaunch(5) for more details.
Help/...
If pcp.books.help has been installed, then the insight(1) books for
pmview+ are displayed.
TIME CONTROLS
In addition to the menu options for time controls, the current direction
of the time controls (see pmtime(1)) is shown in a button in the top-left
corner of the pmview+ window. Pressing this button will display the time
control and is identical in behavior to Options/Show Time Control.
SCALE CONTROLS
Above the examiner window is a thumb wheel and an editable text box which
allow the user to apply a multiplier to all values represented in the
scene. Spinning the wheel to the right and/or increasing the text value
for the scale will increase the height of the bars. Spinning the wheel
to the left and/or lowering the text value will decrease the height of
the bars. The button to the right of the thumb wheel will reset the
scale so that the bars appear at the original height for their current
value.
TIME INFORMATION
Beside the scale controls is another text box which displays the time of
the fetched metrics. The time will change with the time controller (see
pmtime(1)).
ENVIRONMENT
The default face of the 3D font in the pmview+ window can be altered via
PMVIEW_FONT environment variable which can be set to the base name of a
Type1 font file in the default Inventor fonts directory.
FILES
$PCP_VAR_DIR/pmns/*
default PMNS specification files
$PCP_VAR_DIR/config/pmlaunch/pmlaunchrc
menu specification file - provides a mapping between menu item
and launched program
$HOME/.pcp/pmlaunch/pmlaunchrc
individual users menu specification
Page 7
PMVIEW+(1)PMVIEW+(1)
/usr/lib/X11/app-defaults/PmView+
application resources
/usr/lib/images/PmView+.icon
icon for pmview+
$PCP_SHARE_DIR/lib/pmview-args
shell procedures for parsing pmview+ command line options in
front end scripts
/usr/lib/DPS/outline/base/
directory where Inventor normally looks for the outlines of
Type1 fonts.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the
file and directory names used by PCP. On each installation, the file
/etc/pcp.conf contains the local values for these variables. The
$PCP_CONF variable may be used to specify an alternative configuration
file, as described in pcp.conf(4).
SEE ALSOdkvis(1), insight(1), inventor(1), ivview(1), mpvis(1), nfsvis(1),
nodevis(1), osvis(1), oview(1), pcp(1), PCPIntro(1), pmafm(1), pmcd(1),
pmchart(1), pmdumptext(1), pmlogger(1), pmtime(1), pmview(1),
routervis(1), X(1), xbowvis(1), xconfirm(1), xlv_vis(1), pcp.conf(4),
pmview+(4), environ(5) and pmlaunch(5).
Relevant information is also available from the on-line PCP Tutorial.
Provided the pcp.man.tutorial subsystem from the PCP images has been
installed, access the URL file:$PCP_DOC_DIR/Tutorial/pmview.html from
your web browser.
DIAGNOSTICS
Are intended to be self-explanatory. The environment variable PCP_STDERR
can be set to force most startup warnings and errors to be sent to the
standard error stream rather than posted in a dialog.
Page 8
