PMVIEW(1)

📦
version 7.2.2 · 4 versions
, in arch rolling, fedora 43, fedora 44, ubuntu stonking

okay so this is pmview(1), from the General Commands Manual — and bestie, it's a whole vibe. Sit down, grab a strawberry 🍓, we're doing this.

🌸 NAME 🌸

  • pmview — performance metrics 3D visualization back-end ✨

🦋 SYNOPSIS 🦋

pmview [-Cz] [-A align] [-a archive[,archive,...]]  [-c configfile] [-D
debug] [-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]

💜 DESCRIPTION 💜

pmview is a generalized 3D performance metrics visualization tool for the Performance Co-Pilot (PCP(1)). She's the moment. She's the blueprint.

pmview is literally the base utility behind the performance metrics visualization tools like dkvis(1), mpvis(1), osvis(1) and nfsvis(1). It's also used by a whole range of related tools that are specific to optional Performance Domain Agents (PMDA) and/or PCP add-on products. And yes — you can use pmview to construct your own customized 3D performance displays. main character energy fr fr 👑

So what does it actually do, bestie? 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. And since the objects are modulated by the value of the metric they represent, only numerical metrics may be visualized — that's the vibe check, no numbers no entry 🚫

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. sad but iconic 💀

The full syntax of the scene description language is provided in pmview(5). go read it, i'll wait 🫶

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 postmortem analysis of performance problems where a remote system is not accessible or a performance analyst is not available on-site. detective era 🔍

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. she does the math so you don't have to 💅

⭐ 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 containing 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. it's giving "just checking" 🔍
  • -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. one host, one love 🫶
  • -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. synchronized besties ✨
  • -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

🎀 WINDOW 🎀

The pmview window is comprised of a menu bar, time and scale controls, metric and time values, and an ``examiner'' viewer. that's the layout bestie, she's built different ✨

🧚 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. okay so here's the lineup 👇

  • 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. multi-select queen 👑

...and that's part one, bestie — more coming, don't go anywhere 💅

okay bestie, pmview's UI has four menus and they're literally the whole vibe. They let you record, save and print scenes (File), get at the time controls (Options), launch other tools (Launch), and pull up online help (Help). 🫶

💾 File/Record

when you're in live'' mode, this one launches `pmlogger(1)` processes to record the current scene into an archive folio (peep `pmafm(1)`) so you can replay it later. <red>Not available in replay'' mode, periodt. 🙈

pick File/Record and a file chooser dialog pops up asking for the name of your new archive folio. If the directory to the folio doesn't exist, pmview will try to create it. Pro tip from the manpage itself: it's usually convenient to keep each folio in its own directory, because there will be several other files hanging around with it — including the generated archives. 🎀

once a valid folio exists, pmview launches a pmlogger(1) process for each host, collecting the metrics required from that host in the current scene. And ngl, the current selections do not affect the set of metrics that get recorded.

while recording is happening, a red dot shows up in the time controls button in the top left-hand corner of the pmview window. Also File/Record changes to File/Stop Recording, because only one recording session is possible at any one time, bestie. Selecting blocks or launching other tools? No affect on the recording session, it doesn't care. 💅

to end it, hit File/Stop Recording. That shows dialogs for each pmlogger(1) instance describing the size and location of the archive files, before terminating each process. Once all the pmlogger(1) processes are terminated, the red dot dips from the time controls button and the menu reverts back to File/Record so you can run another recording session. ✨

if the application exits while recording, a dialog appears letting you terminate each pmlogger(1) process, or leave it running unattached.

you can replay an archive folio with this command:

pmafm folio replay

see pmafm(1) for more deets.

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. iconic. 🌈

🖨️ File/Print

outputs the current scene to a printer. A print dialog shows up so you can select a specific printer.

🚪 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. Heads up: the time controls may be shared by other tools, including pmchart(1), that have been launched by other instances of pmview and oview(1). So 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. main character energy fr fr. 👑

🚀 Launch

the launch menu is generated from a menu specification file (see pmlaunch(5)). It 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 displays the time control and is identical in behavior to Options/Show Time Control. 🦋

📏 SCALE CONTROLS 📏

above the examiner window there's a thumb wheel and an editable text box that let you apply a multiplier to all values represented in the scene. 🌸

  • spin the wheel to the right and/or increase the text value for the scale → the bars get taller 📈
  • spin the wheel to the left and/or lower the text value → the bars get shorter 📉
  • the button to the right of the thumb wheel → resets the scale so 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)). it's giving clock app but make it PCP. ⭐

🩺 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. 😌

📁 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.

🌿 ENVIRONMENT 🌿

the default face of the 3D font in the pmview window can be altered via the PMVIEW_FONT environment variable, which can be set to the base name of a Type1 font file in the default Inventor fonts directory. 🎀

🧚 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). 💜

🐛 DEBUGGING OPTIONS 💀

okay bestie, so the -D or --debug option turns on extra diagnostics that get dumped onto stderr — it's literally there to help you triage problems ✨ but ngl, the info is sometimes cryptic and it's primarily intended to give guidance to developers, not really for end-users. so like, don't stress if it reads like a riddle 🙈

debug is a comma separated list of debugging options 🎀 and if you wanna know what's even available, run pmdbg(1) with the -l option and it'll hand you the full list plus what each one means. iykyk 💅

✨ debugging options specific to pmvew ✨

(that spelling is straight from the source, bestie, i don't make the rules 🫶)

  • appl0 — scene construction
  • appl1 — object selection, deselection and launch
  • appl2 — fetching and object modulation
  • appl3 — object refreshing
  • appl4 — UI objects (other than the Inventor window)
  • pmc — metrics class operations (libpcp_qmc)
  • timecontrol — pmtime(1) interactions
  • qed — libpcp_qed methods

🌈 SEE ALSO 🦋

the whole friend group, in alphabetical-ish order, no cap:

and bestie, there's more — relevant info is also available from the on-line PCP Tutorial 📚✨ go read it, it's giving educational 💖

okay that's the whole page, we made it 🎀 tysm for reading to the end, you're the main character fr fr 👑

this lil masterpiece comes to you from Performance Co-Pilot 💜 and it's the PMVIEW(1) page — that's the source and the version tag, bestie, go forth and visualize ur metrics 🌸🦋✨

📦 where this page comes from