pmview(1)
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 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.
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, 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.
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
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. 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.
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.
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
/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(5).
SEE ALSO
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.
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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
