- unstable 6.3.1-1+b1
PMVIEW(1) | General Commands Manual | 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¶
pmviewis ageneralized 3D performance metrics visualization tool for thePerformance Co-Pilot(PCP(1)).
pmviewis the base utility behind performance metrics visualization tools such asdkvis(1),mpvis(1),osvis(1)andnfsvis(1),It is also used by a range of related tools that are specific to optionalPerformance Domain Agents(PMDA)and/or PCP add-on products.pmviewmay also be used to construct customized 3D performance displays.
pmviewdisplays performance metrics as colored blocks and cylinders arrangedon monochrome base planes. Each object may represent a single performancemetric, or a stack of several performance metrics. Since the objectsare modulated by the value of the metric they represent, onlynumerical metrics may be visualized. Objects representing a singlemetric may be modulated in terms of height, color, or height andcolor. Objects in a stack may only be height modulated, but the stackcan be normalized to the maximum height. Labels may be added to thescene to help identify groups of metrics.
A configuration file (as specified by the-coption, or read from standard input) is used to specify the position,color, maximum value and labels of metrics and metric instances in thescene. The maximum value acts as a normalization factor and is usedto scale the object height and/or color in proportion to the metricvalues. Metric values which exceed the associated maximum value aredisplayed as solid white objects. If a metric is unavailable, theobject will have minimum height and will be colored grey.
Normally, the tool operates in ``live'' mode where performance metricsare fetched in real-time. The user can view metrics from any hostrunningpmcd(1).pmviewcan also replay archives of performance metrics (seepmlogger(1))and allow the user to interactively control the current replay time and rateusing the VCR paradigm. This is particularly useful for retrospectivecomparisons and for post-mortem analysis of performance problems where a remotesystem is not accessible or a performance analyst is not available on-site.
All metrics in the Performance Metrics Name Space (PMNS) with numeric valuesemantics from any number of hosts or archives may be visualized.pmviewexamines the semantics of the metrics and where sensible, converts metricvalues to a rate before scaling.
COMMANDLINEOPTIONS¶
The-S,-T,-Oand-Aoptions 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 toPCPIntro(1)for a complete description of these options.
The other available options are:
- -a archive[,archive,...]]
- Specify anarchivefrom which metrics can be obtained for a particular host.archiveis the basename of an archive, or the name of a directory conytaining archives,previously created bypmlogger(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 thepmviewwindow. Any errors in the configuration file are displayed.
- -c configfile
- Load the configuration fromconfigfilerather than standard input.
- -h host
- Fetch performance metrics frompmcd(1)onhost,rather than the default localhost. Implies thatpmviewwill run in live mode, so no archives can be specified on the command line orin the configuration file. Only one-hoption may be given.
- -n pmnsfile
- Normallypmviewoperates on the distributed Performance Metrics Name Space (PMNS), however ifthe-noption is specified an alternative local PMNS is loaded from the filepmnsfile.
- -p port
- Connect to the time controls (seepmtime(1))on thisport.Used when a tool launches another tool so that they can connect to thesame time controls.
- -R logconfig
- Uselogconfigas thepmlogger(1)config when recording.
- -r addconfig
- Appendaddconfigonto thepmlogger(1)config generated bypmviewwhen recording.
- -t interval
- The updateintervalused to fetch metrics from the live or archive sources.Theintervalargument follows the syntax described inPCPIntro(1),and in the simplest form may be an unsigned integer (the impliedunits in this case are seconds).The default is 2.0 seconds.
- -x version
- Use the specifiedversionof thepmlaunch(5)specification. The versions currently supported are ``1.0'' and the defaultversion ``2.0''.
- -Z timezone
- By default,pmviewreports the time of day according to the local timezone on the system wherepmviewis run. The-Zoption changes the default timezone totimezonewhich should be in the format of the environment variableTZas described inenviron(7).
- -z
- Change the reporting timezone to the local timezone at the host that is thesource of the performance metrics, as identified via either the-hoption, or the first-aoption.
-geometry geometry
-display display
-name name
-title title
-xrm "resourceName: value"
- Most standardX(1)command line arguments may be used.
WINDOW¶
Thepmviewwindow is comprised of a menu bar, time and scale controls, metric and timevalues, and an ``examiner'' viewer (seeivview(1)),which displays the 3D scene.
EXAMINERVIEWER¶
The left, right and bottom edges of the examiner viewer contain a variety ofthumb wheels and buttons that can be used to adjust the visualization of the3D scene. TheRotxandRotythumb wheels allow the user to rotate the scene about the x and y axes,respectively. Thedollythumb wheel moves the virtual camera closer and further from the scene allowingthe user to examine specific parts in detail or view the entire scene. On theright edge of the viewer are eight buttons which affect the way the user caninteract with the scene.
- Pointer
- Changes the cursor to a pointer which allows blocks to be selected in thescene. See the Metric Selection section below.
- Hand
- Changes the cursor to a hand which allows the scene to be rotated, translatedand dollied using a combination of mouse buttons. The left mouse button canbe used to rotate the scene in the direction of the mouse. Releasing theleft mouse button before the mouse has stopped moving will cause the scene tocontinue to rotate, which can be stopped by pressing the left mouse buttonagain. The middle mouse button will ``pan'' the scene, and both mouse buttonsact 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 hasbeen 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 thehand cursor has been selected. Pressing the ``s'' key while the cursor isover 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 menuof options which affect how the 3D scene is drawn. The options includedrawing the blocks as wire frames, and turning on stereo viewing.
METRICSELECTION¶
When the pointer cursor is active, more information about the 3D scene canbe obtained. Text describing the metric represented by the block under thecursor will be displayed in the top text box of thepmviewwindow. The text contains the source and name of the metric, current value andunits, and the percentage of the expected maximum (or normalization) value.The text box is updated whenever the scene is updated with thelatest metric values or when the cursor is moved over another block in thescene. Moving the cursor over a base plane block, text or the surroundingspace will clear the text box.
Clicking the left mouse button on a block will bind the text box on that metricinstance so that the metric can be monitored while performing other actionswith the mouse. The block will be highlighted with a red wire frame.Clicking the left mouse button on text or the space surrounding the scenewill unselect the object, causing the text box to revert to the originalbehavior of showing the metric underneath the cursor.
Selecting a base plane instead of a modulated block will cause all the blockson that base plane to be selected. When more than one object is selected, thetext box behaves as if nothing is selected, so the metric displayed is themetric currently under the cursor. Multiple selections are also possible bypressing the SHIFT key while selecting an object with the left mouse button.
MENUS¶
There are four menus inpmview'suser interface which allow scenes to be recorded, saved and printed(File),access to the time controls(Options),launching other tools(Launch)andonline help(Help).
- File/Record
- When in ``live'' mode, this option will launchpmlogger(1)processes
to record the current scene into an archive folio (seepmafm(1))so
that it may bereplayed at a later time. This option is not available in
``replay'' mode.
WhenFile/Recordis selected, a file chooser dialog will prompt for the name of the new archivefolio. If the directory to the folio does not exist,pmviewwill attempt to create it. It is usually convenient to keep each folio withinits own directory as there will be several other files associated with thefolio, including the generated archives.
Once a valid folio has been created,pmviewwill launch apmlogger(1)process for each host to collect the metrics required from that host in thecurrent scene. The current selections do not affect the set of metrics thatare recorded.
While recording is in progress, a red dot will appear in the time controlsbutton in the top left-hand corner of thepmviewwindow. TheFile/Recordoption will also change toFile/Stop Recordingas only one recording session is possible at any one time. Selecting blocks orlaunching other tools will have no affect on the recording session.
The record session may be terminated by selectingFile/Stop Recording.This will display dialogs for eachpmlogger(1)instance describing the size and location of the archive files beforeterminating each process. When allpmlogger(1)processes have been terminated, the red dot is removed from the time controlsbutton, and the menu reverts back toFile/Recordto allow another recording session to take place.
If the application exists while recording, a dialog will appear allowing you toterminate eachpmlogger(1)process, or leave it running unattached.
An archive folio may be replayed using the command:``pmafmfolioreplay''.Seepmafm(1)for more details.
It is not uncommon for a front-end script which generates apmviewscene to use metrics that are not contained in the scene. For example,osvis(1)uses severalhinvmetrics to determine the size and layout of some objects. As these metrics arealso needed when replaying the generated archive with the front-end script,a completepmlogger(1)config can be specified(-R)that overrides thepmviewgenerated config, or an additional config can be appended(-r)to thepmviewgenerated config.
- File/Save
- Saves the current scene to a human-readable Open Inventor file (seeinventor(1)).A file dialog will prompt for the location of the file. The default fileextension is ``.iv'' which is recognized byivview(1)and some Web browsers.
- File/Print
- Outputs the current scene to a printer. A print dialog will be displayedallowing a specific printer to be selected.
- File/Quit
- pmviewimmediately exits. If recording was active, dialogs will be displayed foreachpmlogger(1)process so that they may be terminated.
- Options/Show Time Control
- Displays the time controls (seepmtime(1))that are driving this instance ofpmview.The time controls may be shared by other tools, includingpmchart(1),that have been launched by other instances ofpmviewandoview(1).Therefore, this menu item may appear to have no affect if the time controlsare already visible.
- Options/New Time Control
- Disconnect with the current time controls (which may be shared by other tools,seepmtime(1))and use a new time control that is not connected to any other tools. The newtime control will be immediately displayed.
- Launch
- The launch menu is generated from a menu specification file
(seepmlaunch(5)).The menu contains tools that may be launched based
on the sources and names ofthe selected metrics in the scene. For example,
if the selected metrics arefrom 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 metricsand the tools being launched.
On selection of aLaunchmenu itempmviewgenerates state information in thepmlaunch(5)metrics specification format. This provides a description of the selectedmetrics (or if there are no selections, all the metrics) in the scene withoutany geometry information.
Tools which can monitor multiple hosts and user specified metrics may belaunched only once for those metrics (egpmdumptext(1)).Other tools which have a fixed view for one host (egmpvis(1)),may belaunched multiple times, once for each host in the selected metric list. Ifthe launched tools have time controls, they will share thetime controls with the launchingpmview.
The set of launched tools is configurable, and may include IRIX and userapplications. Seepmlaunch(5)for more details.
- Help/...
- Ifpcp.books.helphas been installed, then theinsight(1)books forpmvieware displayed.
TIMECONTROLS¶
In addition to the menu options for time controls, the current direction of thetime controls (seepmtime(1))is shown in a button in the top-left corner of thepmviewwindow. Pressing this button will display the time control and is identicalin behavior toOptions/Show Time Control.
SCALECONTROLS¶
Above the examiner window is a thumb wheel and an editable text box whichallow 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 scalewill increase the height of the bars. Spinning the wheel to the left and/orlowering the text value will decrease the height of the bars. The button tothe right of the thumb wheel will reset the scale so that the bars appear atthe original height for their current value.
TIMEINFORMATION¶
Beside the scale controls is another text box which displays the time of thefetched metrics. The time will change with the time controller (seepmtime(1)).
ENVIRONMENT¶
The default face of the 3D font in thepmviewwindow can be altered viaPMVIEW_FONTenvironment variable which can be set to the base name of a Type1 fontfile 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 andlaunched program
- $HOME/.pcp/pmlaunch/pmlaunchrc
- individual users menu specification
- /usr/lib/X11/app-defaults/PmView
- application resources
- /usr/lib/images/PmView.icon
- icon forpmview
- $PCP_SHARE_DIR/lib/pmview-args
- shell procedures for parsingpmviewcommand 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 prefixPCP_are used to parameterize the file and directory namesused by PCP.On each installation, the file/etc/pcp.confcontains the local values for these variables.The$PCP_CONFvariable may be used to specify an alternativeconfiguration file,as described inpcp.conf(5).
SEEALSO¶
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)andpmlaunch(5).
Relevant information is also available from the on-line PCPTutorial. Provided thepcp.man.tutorialsubsystem from the PCP images has been installed, access theURLfile:$PCP_DOC_DIR/Tutorial/pmview.htmlfrom your web browser.
DIAGNOSTICS¶
Are intended to be self-explanatory. The environment variablePCP_STDERRcan be set to force most startup warnings and errors to be sent to thestandard error stream rather than posted in a dialog.
Performance Co-Pilot |