oview4sn0(1)
oview4sn0 - visualize the performance of Origin 2000 server
As shipped in IRIX 6.5.19. Added in IRIX 6.5.15.
NAME oview4sn0 - visualize the performance of Origin 2000 server SYNOPSIS oview4sn0 [-Cz] [-A align] [-a archive] [-c configfile] [-h host] [-l level] [-n pmnsfile] [-O origin] [-p port] [-S starttime] [-T endtime] [-t interval] [-x version] [-Z timezone] [-geometry geometry] [-display display] [-name name] [-title title] [-xrm "resourceName: value" ...] [other X11-flags] DESCRIPTION oview4sn0 is a graphical tool for the Performance Co-Pilot (see PCPIntro(1)) that supports a dynamic display of Origin 2000 server topology and performance. oview4sn0 can display performance information about CPUs, nodes and routers in Origin 2000 systems connected in no-router, star, planar, cube or hypercube configurations. Configurations with more than 16 routers (i.e. more than 64 CPUs) are currently not supported by oview4sn0. Normally, oview4sn0 operates in ``live'' mode where performance metrics are fetched in real-time. The target host can be changed from the default localhost to another SGI 2000 system running pmcd(1) with the -h option. Performance metric archives, previously collected by pmlogger(1), may be replayed by using the -a option. This allows 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. By default, the interconnection topology of the metric source is automatically determined by oview_layout(1). This application generates a configuration file describing the connections between routers which oview4sn0 translates into a three-dimensional scene. Alternatively, a hand-crafted configuration can be passed to oview4sn0 using the -c option or piped on stdin. VISUALIZATION Routers are represented in the scene by octahedrons connected to other routers and nodes by cylindrical router links. Nodes are represented by short cylinders and CPUs are blocks on the ends of each node. To avoid cluttering the scene, CPUs and nodes may not be shown by default. The -l option and the Options menu can be used when oview4sn0 is launched or while it is running to selectively ``sprout'' nodes and CPUs. The cylindrical link between routers and nodes show the receive utilization of the associated router or node port. This is visualized as colored bands which grow toward the mid-point of the link as the utilization increases. The receive bypass and the receive queued utilization are shown as violet and yellow bands, respectively. The routers change color proportional to the average receive utilization of all connected links to the router. The default thresholds for each color change are: cyan insignificant router utilization 0 <= utilization < 1% light cyan light router utilization 1% <= utilization < 5% yellow medium router utilization 5% <= utilization < 20% orange high router utilization 20% <= utilization < 40% red saturated router utilization utilization >= 40% CPUS use a stack of blue, red and cyan colored blocks to show the user, system and wait utilization of each CPU, respectively. A grey block on top of the colored blocks, if visible, represents the unused CPU capacity. All default colors and color scale thresholds are configurable by modifying the application defaults file /var/lib/X11/app-defaults/OView, your personal .Xdefaults file, or by using the X(1) command line option -xrm. The resources supported by oview are described in the Application Resources section below. Other tools can be launched from the Launch menu so that specific areas of performance may be explored in more detail. 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 Performance metric information is retrospectively retrieved from the Performance Co-Pilot (PCP) archive, previously generated by pmlogger(1). The archive should contain sufficient metrics for oview4sn0 to determine the interconnection topology and modulate the scene. $PCP_VAR_DIR/config/pmlogger/config.oview contains the minimal set of metrics for pmlogger(1) to generate an archive for oview4sn0. -C Terminate after parsing the configuration, without displaying a window. This option can be used to validate an oview4sn0 configuration without displaying the visualization. However, oview4sn0 still requires a connection to an X(1) display. -c configfile Generate the scene from the topology description in configfile, rather than launching oview_layout(1) to automatically generate the configuration. The format of configfile is described in oview_layout(1). To force reading the configuration from stdin if -a or -h have been specified, use ``-c -'' -h host Performance metric information is retrieved in real time from the Performance Metrics Collector Daemon (PMCD) of the nominated host machine. Implies that oview4sn0 will run in ``live'' mode, so no archives (-a) can be specified on the command line. Only one -h option may be given and the target host must be an Origin 2000 system. -l level Change the level of detail shown by oview4sn0 when first displaying the scene. The default level of details depends on the number of routers on the target host: 0 Show only routers, the default for systems with more than eight routers. 1 Show the routers and nodes, the default for systems with five to eight routers. 2 Show all the routers, nodes and CPUs, the default for systems with less than five routers. -n pmnsfile Normally oview4sn0 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. -t interval The default update interval may be set to something other than the default 2 seconds. 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). -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, oview4sn0 reports the time of day according to the local timezone on the system where it 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 or the first -a options. -geometry geometry -display display -name name -title title -xrm "resourceName: value" Most standard X(1) command line arguments may be used. WINDOW The oview4sn0 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 affect. 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 object under the cursor will be displayed in the top text box of the oview4sn0 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 object in the scene. Moving the cursor over the surrounding space will clear the text box. Clicking the left mouse button on a object will bind the text box on that metric instance so that the metric can be monitored while performing other actions with the mouse. The object will be highlighted with a red wire frame. Clicking the left mouse button on text or the space surrounding the scene will deselect the object, causing the text box to revert to the original behavior of showing the metric underneath the cursor. Multiple selections are possible by pressing the SHIFT key while selecting an object with the left mouse button. When more than one object is selected, the text box behaves as if nothing is selected, so the metric displayed will be the metric currently under the cursor. MENUS There are four menus in oview4sn0'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). Some menu options will change depending on the current selections and the objects that are visible and hidden in the current scene. 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, oview4sn0 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, oview4sn0 will launch a pmlogger(1) process to collect the metrics required 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 oview4sn0 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 a dialog for the pmlogger(1) instance describing the size and location of the archive files. The red dot is then 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 terminates while recording, a dialog will appear allowing you to terminate the 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. 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 oview4sn0 immediately exits. If recording was active, a dialog will be displayed for the pmlogger(1) process so that it may be terminated. Options/Show Time Control Displays the time controls (see pmtime(1)) that are driving this instance of oview4sn0. The time controls may be shared by other tools, including pmchart(1), that have been launched by other instances of oview and pmview(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. The four remaining options in the Options menu allow the user to ``sprout'' and hide CPUs and nodes in the current scene. The Options menu items will change depending on the current selections and the number of objects that are visible, so not all of these items will be available at any one time. Options/Show All Nodes Reveal all nodes that are currently hidden. Options/Show Nodes Reveal all nodes attached to this router that are currently hidden. Options/Show Node Reveal the single node attached to the selected router that is currently hidden. Options/Hide All Nodes Hide all nodes that are visible in the current scene. Options/Hide Nodes Hide the nodes attached to the selected router. Options/Hide Node Hide the selected node or the only visible node attached to the selected router. Options/Show All CPUs Reveal all CPUs that are currently hidden. Options/Show CPUs Reveal all CPUs attached to the selected node or router that are currently hidden. Options/Show CPU Reveal the single CPU attached to the selected node or router that is currently hidden. Options/Hide All CPUs Hide all CPUs that are currently visible. Options/Hide CPUs Hide all CPUs attached to the selected node or router that are currently visible. Options/Hide CPU Hide the selected CPU, or the single CPU attached to the selected node or router that is currently visible. 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 oview4sn0 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 oview4sn0. The set of launched tools is configurable, and may include IRIX and user applications. See pmlaunch(5) for more details. Help/... If pcp_eoe.books.help has been installed, then the insight(1) books for oview 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 oview4sn0 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 edit-able 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)). APPLICATION RESOURCES This section describes the X11 application resources that can be configured by the user. Other resources, such as those for controlling labels in the user interface are not described here - see comments in the oview application defaults file, /usr/lib/X11/app-defaults/OView. OView*routerDistance The distance between proximal routers, relative to the router radius. OView*routerLinkRadius The radius of router-router link tubes, relative to the router radius. OView*axisLength The axis length as a proportion of routerDistance. OView*nodeLinkLength The length of node-router links relative to the length of a router-router link. A value of 1.0 indicates equal lengths. OView*nodeLinkRouterProportion The proportion of the node-router link tube that router-metering uses (the remainder is used for node-metering). A value of 0.5 indicates equal (balanced) proportions. OView*nodeRadius The radius of a node cylinder, relative to the router radius. OView*cpuHeight The height of a CPU block, relative to the router radius. OView*centerMarkLength The length of the center mark for router-router links, relative to the router radius. OView*longBendDeviation The bend deviation factor for "long diagonal" router-router links, relative to routerLinkRadius. This is used to avoid collisions of otherwise intersecting long diagonal link tubes. OView*nodeLinkRadius The node-router link radius relative to routerLinkRadius. A value of 1.0 specifies equal radii. OView*sceneXRotation The initial rotation of the whole scene around the X-Axis, in degrees. OView*sceneYRotation The initial rotation of the whole scene around the Y-Axis, in degrees. OView*antiAliasSmooth Whether to perform anti-aliasing. A true value sets "fast" anti- aliasing. OView*antiAliasPasses The number of anti-aliasing passes, in the range 1 to 255. A value of 1 (the default) disables anti-aliasing. OView*cpuSlack.color The color of the inactive part of a CPU bar. OView*cpuMetric1.color OView*cpuMetric2.color OView*cpuMetric3.color The colors used in the active parts of a CPU bar. OView*routerLinkSlack.color The color of the inactive part of a router link. OView*routerLinkMetric1.color OView*routerLinkMetric2.color OView*routerLinkMetric3.color The colors used for the three metrics showing utilization for router-router links. OView*nodeLinkMetric.color The color of the metric showing utilization at the node end of a router-node link. This is normally the same as routerLinkMetric1.color. OView*evenRouter.color OView*oddRouter.color The alternating (even/odd) colors of all routers with "insignificant" utilization (utilization less than routerLevel1.legend). By default the same color is used for both. OView*routerLevel1.color OView*routerLevel2.color OView*routerLevel3.color OView*routerLevel4.color The color legend for router utilization. A router will be drawn with routerLeveln.color if its associated utilization threshold (routerLeveln.legend) is exceeded. OView*routerLevel1.legend OView*routerLevel2.legend OView*routerLevel3.legend OView*routerLevel4.legend The floating point utilization threshold values for the router utilization color legend above. The values should be increasing in the range from 0.0 to 1.0 where 1.0 represents 100% utilization. OView*node.color The color of nodes with "insignificant" utilization (utilization less than nodeLevel1.legend). OView*nodeLevel1.color OView*nodeLevel2.color OView*nodeLevel3.color OView*nodeLevel4.color The color legend for node migration interrupt utilization. A node will be drawn with nodeLeveln.color if its associated utilization threshold (nodeLeveln.legend) is exceeded. OView*nodeLevel1.legend OView*nodeLevel2.legend OView*nodeLevel3.legend OView*nodeLevel4.legend The floating point utilization values for the node migration interrupt utilization color legend resources described above. The values should be increasing in the range from 0.0 to 1.0 where 1.0 represents 100% utilization (relative to migrUtilModulationScale). OView*join.color The color of the inactive center (join) section of long links. OView*centerMark.color The router link center marker color. OView*linkWarn.color The color for unrecognized link-type alerts. If any links appear in this color then it is likely the oview_layout program has incorrectly resolved the system topology or a syntactically correct but semantically invalid configuration file was supplied with the -c command line option. OView*routerUtilModulationScale The maximum value for link utilization. Since the router metrics are already normalized to 100%, this resource should never need to be changed. OView*cpuUtilModulationScale The maximum CPU utilization (in milliseconds per second). This resource should not be changed from 1000. OView*nodeUtilModulationScale The maximum migration interrupt rate (per second) for determining migration interrupt utilization. This may be changed from the default of 10 interrupts per second equals 100%. OView*nodeMetric The metric for modulating nodes in the scene. The default is origin.numa.migr.intr.total, but this can be changed to any other metric with the node instance domain. In other words, a metric which also represents nodes. For example, to monitor the free memory available on each node, this resource can be set to origin.node.free.total. The modulation scale OView*nodeUtilModulationScale must also be set to the maximum physical memory on any node, which can be obtained from the metric origin.node.physmem. There is no mechanism at this time for specifying different scales for each node. The color scale must also be specified in reverse as low values indicate the lack of free memory. For example, for a system with 256 Meg of physical memory on each node, the resources to monitor memory usage could be: OView*nodeMetric: origin.node.free.total OView*nodeUtilModulationScale: 268435456 OView*node.color: red OView*nodeLevel1.color: orange OView*nodeLevel1.legend: 0.2 OView*nodeLevel2.color: magenta OView*nodeLevel2.legend: 0.4 OView*nodeLevel3.color: blue OView*nodeLevel3.legend: 0.6 OView*nodeLevel4.color: light yellow OView*nodeLevel4.legend: 0.8 OView*saturation The saturation multiplier for all modulated objects. The default saturation multiplier is set to 1.05 which allows for a 5% error in metric values due to rate calculations using slightly inaccurate time deltas. Therefore, a metric which exceeds the modulation scale by more than 5% is considered saturated. However, the modulation of an object never actually exceeds 100%. In other words a height modulated object will never exceed the maximum height even if the point of saturation is larger than 100%. Default values for these resources are supplied in the oview application defaults file, /usr/lib/X11/app-defaults/OView. Consult the X(1) man page for details of the syntax for standard X11 geometry resources and other standard resources. CONFIGURATION FILE SYNTAX The syntax of the oview4sn0 configuration file is described in the oview_layout(1) man page. FILES $PCP_VAR_DIR/pmns/* default PMNS specification files /usr/lib/X11/app-defaults/OView the application defaults file $PCP_VAR_DIR/config/pmlogger/config.oview pmlogger(1) configuration file suitable for use with oview $PCP_VAR_DIR/config/pmlaunch/* global configuration files controlling the Launch menu contents $HOME/.pcp/pmlaunch/pmlaunchrc user specific configuration files controlling the Launch menu contents CAVEAT The algorithm for 3-D layout of Origin system components by oview4sn0(1) is complex, and relies on heuristics. If you encounter a configuration that is not displayed as expected, please send e-mail to pcp-info@sgi.com including a description of the problem, and attaching the output from pminfo -f hinv A known area of layout difficulty occurs in configurations with many links with diagonal portions in the same vicinity; oview4sn0 might draw connections on top of one another in the 3-D scene. 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 ALSO mpvis(1), oview(1), oview_layout(1), PCPintro(1), pmafm(1), pmcd(1), pmdumptext(1), pminfo(1), pmlogger(1), pmtime(1), pmview+(1), X(1), environ(5) and pmlaunch(5). DIAGNOSTICS Are intended to be self explanatory. The environment variable PCP_STDERR can be set to force most startup warnings and errors to be posted in a dialog rather than sent to standard error. See PCPintro(1) for more details.