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)

NAME         top

       pmview - performance metrics 3D visualization back-end

SYNOPSIS         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       $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         top

       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         top

       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         top

       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.

COLOPHON         top

       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)