diff options
Diffstat (limited to 'man/man1/pmview.1')
| -rw-r--r-- | man/man1/pmview.1 | 590 |
1 files changed, 590 insertions, 0 deletions
diff --git a/man/man1/pmview.1 b/man/man1/pmview.1 new file mode 100644 index 0000000..3f0ceb7 --- /dev/null +++ b/man/man1/pmview.1 @@ -0,0 +1,590 @@ +.TH PMVIEW 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmview\f1 \- performance metrics 3D visualization back-end +.SH SYNOPSIS +\f3pmview\f1 +[\f3\-Cz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1[\f3,\f2archive\f3,\f1...]] +[\f3\-c\f1 \f2configfile\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-n\f1 \f2pmnsfile\f1] +[\f3\-O\f1 \f2origin\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-R\f1 \f2logconfig\f1] +[\f3\-r\f1 \f2addconfig\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-x\f1 \f2version\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f3\-geometry\f1 \f2geometry\f1] +[\f3\-display\f1 \f2display\f1] +[\f3\-name\f1 \f2name\f1] +[\f3\-title\f1 \f2title\f1] +[\f3\-xrm "\f1\f2resourceName\f1\f3:\f2 value\f3"\f1 ...] +[\f2other X11-args\f1] +.SH DESCRIPTION +.B pmview +is a +generalized 3D performance metrics visualization tool for the +Performance Co-Pilot +.RB ( PCP (1)). +.PP +.B pmview +is the base utility behind performance metrics visualization tools such as +.BR dkvis (1), +.BR mpvis (1), +.BR osvis (1) +and +.BR 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. +.B pmview +may also be used to construct customized 3D performance displays. +.PP +.B 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. +.PP +A configuration file (as specified by the +.B \-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. +.PP +Normally, the tool operates in ``live'' mode where performance metrics +are fetched in real-time. The user can view metrics from any host +running +.BR pmcd (1). +.B pmview +can also replay archives of performance metrics (see +.BR 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. +.PP +All metrics in the Performance Metrics Name Space (PMNS) with numeric value +semantics from any number of hosts or archives may be visualized. +.B pmview +examines the semantics of the metrics and where sensible, converts metric +values to a rate before scaling. +.SH COMMAND LINE OPTIONS +The +.BR -S , +.BR -T , +.B -O +and +.B -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 +.BR PCPIntro(1) +for a complete description of these options. +.PP +The other available options are: +.TP +\f3-a\f1 \f2archive\f1[\f3,\f2archive\f3,\f1...]] +Specify an +.I archive +from which metrics can be obtained for a particular host. +.I archive +is the basename of an archive, previously created by +.BR pmlogger (1). +Multiple archives (separated by commas or in different \f3\-a\f1 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. +.TP +.B \-C +Parse the configuration file and exit before displaying the +.B pmview +window. Any errors in the configuration file are displayed. +.TP +\f3\-c\f1 \f2configfile\f1 +Load the configuration from +.I configfile +rather than standard input. +.TP +\f3\-h\f1 \f2host\f1 +Fetch performance metrics from +.BR pmcd (1) +on +.IR host , +rather than the default localhost. Implies that +.B pmview +will run in live mode, so no archives can be specified on the command line or +in the configuration file. Only one +.B \-h +option may be given. +.TP +\f3\-n\f1 \f2pmnsfile\f1 +Normally +.B pmview +operates on the distributed Performance Metrics Name Space (PMNS), however if +the +.B \-n +option is specified an alternative local PMNS is loaded from the file +.IR pmnsfile . +.TP +\f3\-p\f1 \f2port\f1 +Connect to the time controls (see +.BR pmtime (1)) +on this +.BR port . +Used when a tool launches another tool so that they can connect to the +same time controls. +.TP +\f3\-R\f1 \f2logconfig\f1 +Use +.I logconfig +as the +.BR pmlogger (1) +config when recording. +.TP +\f3\-r\f1 \f2addconfig\f1 +Append +.I addconfig +onto the +.BR pmlogger (1) +config generated by +.B pmview +when recording. +.TP +\f3\-t\f1 \f2interval\f1 +The update +.I interval +used to fetch metrics from the live or archive sources. +The +.I interval +argument follows the syntax described in +.BR 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. +.TP +\f3\-x\f1 \f2version\f1 +Use the specified +.I version +of the +.BR pmlaunch (5) +specification. The versions currently supported are ``1.0'' and the default +version ``2.0''. +.TP +\f3\-Z\f1 \f2timezone\f1 +By default, +.B pmview +reports the time of day according to the local timezone on the system where +.B pmview +is run. The +.B \-Z +option changes the default timezone to +.I timezone +which should be in the format of the environment variable +.B TZ +as described in +.BR environ (5). +.TP +\f3\-z\f1 +Change the reporting timezone to the local timezone at the host that is the +source of the performance metrics, as identified via either the +.B \-h +option, or the first +.B \-a +option. +.PP +\f3\-geometry\f1 \f2geometry\f1 +.br +\f3\-display\f1 \f2display\f1 +.br +\f3\-name\f1 \f2name\f1 +.br +\f3\-title\f1 \f2title\f1 +.br +\f3\-xrm\f1 \f3"\f2resourceName: value\f3"\f1 +.IP +Most standard +.BR X (1) +command line arguments may be used. +.SH WINDOW +The +.B pmview +window is comprised of a menu bar, time and scale controls, metric and time +values, and an ``examiner'' viewer (see +.BR ivview (1)), +which displays the 3D scene. +.SH 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 +.I Rotx +and +.I Roty +thumb wheels allow the user to rotate the scene about the x and y axes, +respectively. The +.I 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. +.TP 4n +.I Pointer +Changes the cursor to a pointer which allows blocks to be selected in the +scene. See the Metric Selection section below. +.TP 4n +.I 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. +.TP 4n +.I Question Mark +Displays the SGI Help information for the examiner viewer. +.TP 4n +.I Home +Changes the scene back to its original position, unless the home position has +been changed by the home pointer button. +.TP 4n +.I Home Pointer +Changes the home position of the scene to be the scene currently in view. +.TP 4n +.I Eye +Resizes the scene so that it completely fits into the 3D viewing area. +.TP 4n +.I 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. +.TP 4n +.I Perspective Box +Switches the display between perspective and orthogonal projections. +.PP +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. +.SH 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 +.B 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. +.PP +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. +.PP +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. +.SH MENUS +There are four menus in +.BR pmview 's +user interface which allow scenes to be recorded, saved and printed +.RB ( File ), +access to the time controls +.RB ( Options ), +launching other tools +.RB ( Launch ) +and +online help +.RB ( Help ). +.TP 4n +.B "File/Record" +When in ``live'' mode, this option will launch +.BR pmlogger (1) +processes to record the current scene into an archive folio (see +.BR pmafm(1)) +so that it may be +replayed at a later time. This option is not available in ``replay'' mode. + +When +.B "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, +.B 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, +.B pmview +will launch a +.BR 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 +.B pmview +window. The +.B "File/Record" +option will also change to +.BR "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 +.BR "File/Stop Recording" . +This will display dialogs for each +.BR pmlogger (1) +instance describing the size and location of the archive files before +terminating each process. When all +.BR pmlogger (1) +processes have been terminated, the red dot is removed from the time controls +button, and the menu reverts back to +.B "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 +.BR pmlogger (1) +process, or leave it running unattached. + +An archive folio may be replayed using the command: +.RB `` pmafm +.I folio +.BR replay ''. +See +.BR pmafm (1) +for more details. + +It is not uncommon for a front-end script which generates a +.B pmview +scene to use metrics that are not contained in the scene. For example, +.BR osvis (1) +uses several +.I 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 +.BR pmlogger (1) +config can be specified +.RB ( \-R ) +that overrides the +.B pmview +generated config, or an additional config can be appended +.RB ( \-r ) +to the +.B pmview +generated config. +.TP 4n +.B "File/Save" +Saves the current scene to a human-readable Open Inventor file (see +.BR inventor (1)). +A file dialog will prompt for the location of the file. The default file +extension is ``.iv'' which is recognized by +.BR ivview (1) +and some Web browsers. +.TP 4n +.B "File/Print" +Outputs the current scene to a printer. A print dialog will be displayed +allowing a specific printer to be selected. +.TP 4n +.B "File/Quit" +.B pmview +immediately exits. If recording was active, dialogs will be displayed for +each +.BR pmlogger (1) +process so that they may be terminated. +.TP 4n +.B "Options/Show Time Control" +Displays the time controls (see +.BR pmtime (1)) +that are driving this instance of +.BR pmview . +The time controls may be shared by other tools, including +.BR pmchart (1), +that have been launched by other instances of +.B pmview +and +.BR oview (1). +Therefore, this menu item may appear to have no affect if the time controls +are already visible. +.TP 4n +.B "Options/New Time Control" +Disconnect with the current time controls (which may be shared by other tools, +see +.BR pmtime (1)) +and use a new time control that is not connected to any other tools. The new +time control will be immediately displayed. +.TP 4n +.B "Launch" +The launch menu is generated from a menu specification file (see +.BR 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 +.B Launch +menu item +.BR pmview +generates state information in the +.BR 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 +.BR pmdumptext (1)). +Other tools which have a fixed view for one host (eg +.BR 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 +.BR pmview . + +The set of launched tools is configurable, and may include IRIX and user +applications. See +.BR pmlaunch (5) +for more details. +.TP 4n +.B "Help/..." +If +.I pcp.books.help +has been installed, then the +.BR insight (1) +books for +.B pmview +are displayed. +.SH TIME CONTROLS +In addition to the menu options for time controls, the current direction of the +time controls (see +.BR pmtime (1)) +is shown in a button in the top-left corner of the +.B pmview +window. Pressing this button will display the time control and is identical +in behavior to +.BR "Options/Show Time Control" . +.SH 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. +.SH 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 +.BR pmtime (1)). +.SH ENVIRONMENT +The default face of the 3D font in the +.B pmview +window can be altered via +.I PMVIEW_FONT +environment variable which can be set to the base name of a Type1 font +file in the default Inventor fonts directory. +.SH FILES +.TP 10 +.B "$PCP_VAR_DIR/pmns/*" +default PMNS specification files +.TP +.B "$PCP_VAR_DIR/config/pmlaunch/pmlaunchrc" +menu specification file - provides a mapping between menu item and +launched program +.TP +.B "$HOME/.pcp/pmlaunch/pmlaunchrc" +individual users menu specification +.TP +.B "/usr/lib/X11/app-defaults/PmView" +application resources +.TP +.B "/usr/lib/images/PmView.icon" +icon for +.BR pmview +.TP +.B "$PCP_SHARE_DIR/lib/pmview-args" +shell procedures for parsing +.B pmview +command line options in front end scripts +.TP +.B "/usr/lib/DPS/outline/base/" +directory where Inventor normally looks for the outlines of Type1 fonts. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (4). +.SH SEE ALSO +.BR dkvis (1), +.BR insight (1), +.BR inventor (1), +.BR ivview (1), +.BR mpvis (1), +.BR nfsvis (1), +.BR osvis (1), +.BR oview (1), +.BR pcp (1), +.BR PCPIntro (1), +.BR pmafm (1), +.BR pmcd (1), +.BR pmchart (1), +.BR pmdumptext (1), +.BR pmlogger (1), +.BR pmtime (1), +.BR pmview (1), +.BR X (1), +.BR xconfirm (1), +.BR xlv_vis (1), +.BR pcp.conf (4), +.BR pmview (4), +.BR environ (5) +and +.BR pmlaunch (5). +.P +Relevant information is also available from the on-line PCP +Tutorial. Provided the +.B pcp.man.tutorial +subsystem from the PCP images has been installed, access the +URL +.B file:$PCP_DOC_DIR/Tutorial/pmview.html +from your web browser. + +.SH DIAGNOSTICS +Are intended to be self-explanatory. The environment variable +.B 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. |