|
NAME | SYNOPSIS | DESCRIPTION | COMMAND LINE OPTIONS | WINDOW | EXAMINER VIEWER | METRIC SELECTION | MENUS | TIME CONTROLS | SCALE CONTROLS | TIME INFORMATION | ENVIRONMENT | FILES | PCP ENVIRONMENT | SEE ALSO | DIAGNOSTICS | COLOPHON |
PMVIEW(1) General Commands Manual PMVIEW(1)
pmview - performance metrics 3D visualization back-end
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]
pmview is a generalized 3D performance metrics visualization tool for
the Performance Co-Pilot (PCP(1)).
pmview is the base utility behind performance metrics visualization
tools such as dkvis(1), mpvis(1), osvis(1) and nfsvis(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.
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.
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, or
the name of a directory conytaining archives, previously
created by pmlogger(1). Multiple sets of 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
set of archives from the same host. Any metrics that are not
associated with a specific host or archive in the
configuration file will use the first set of archives 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.
-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(7).
-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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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)).
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.
$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
/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.
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(5).
dkvis(1), insight(1), inventor(1), ivview(1), mpvis(1), nfsvis(1),
osvis(1), oview(1), pcp(1), PCPIntro(1), pmafm(1), pmcd(1),
pmchart(1), pmdumptext(1), pmlogger(1), pmtime(1), pmview(1), X(1),
xconfirm(1), xlv_vis(1), pcp.conf(5), pmview(5), environ(7) 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.
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.
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page, or
you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a mail
to man-pages@man7.org
Performance Co-Pilot PMVIEW(1)
Pages that refer to this page: mkaf(1), pmafm(1), pmdaweblog(1), pmview(1), pmview(5)