PMCHART(1)

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

💖 pmchart(1) — the manual page, but make it make sense 💖

okay so bestie, welcome to pmchart, a General Commands Manual situation, and no cap this tool is gorgeous once you get it. It's a strip chart tool for Performance Co-Pilot, and I'm gonna walk you through it like we're texting at 2am. ✨

🌈 SYNOPSIS 🌈

pmchart [-CLVWz?]  [-a archive] [-A align] [--archive-folio folio] [-c
configfile] [-D debug] [-f fontfamily] [-F fontsize] [-g geometry] [-h
host] [-n pmnsfile] [-o outfile] [-O offset] [-p port] [-s samples] [-S
starttime] [-t interval] [-T endtime] [-v visible] [-Z timezone]
[-geometry geometry] [sources...]

Like… it's giving options for days, and honestly? We love that for us. 💅

🦋 DESCRIPTION 🦋

pmchart is a graphical utility that plots performance metrics values available through the facilities of the Performance Co-Pilot (PCP). Multiple charts can be displayed simultaneously — either aligned on the unified time axis (the X-axis), or by using multiple interface Tabs. 🎀

Metric values can come from one or more live hosts (yes, simultaneously, she's multitalented like that), OR from one or more sets of PCP archives when you want historical data instead. If you wanna go deep on what the PCP framework can actually do — and lowkey a lot of it gets used by pmchart — go read PCPIntro(1). 📚

So many aspects of how pmchart behaves can be customised right through the interface. Specifically: the use of "views" (there's a whole section about VIEWS later in this doc, iykyk) lets you store predefined sets of metrics plus charting parameters — colors, scaling, titles, legends, all of it — for later, or to reuse with different hosts and different sets of archives. And the Preferences dialog lets you save and restore customisations to the rest of the pmchart user interface between different invocations of the tool. That means the default background color, highlight color, the contents and location of the toolbar, and a whole bunch of other stuff can all be configured. 🌸

Also pmchart makes extensive use of the pmtime(1) utility for time control — so go read the pmtime manual page for the details of how that operates. ⏰

✨ OPTIONS ✨

The available command line options are:

  • -a archive, --archive=archive — Performance metric values are retrieved from the set of Performance Co-Pilot (PCP) archives identified by this option, by default. The argument is a comma-separated list of names, and each name may be the base name of an archive or the name of a directory containing one or more archives. The resulting set of archives becomes the source of the performance metrics. The initial Tab created will be an archive mode Tab. You can stack multiple -a options, and that resulting list of sets of archives is what gets used for sourcing metric values. Heads up: any sources listed on the command line are assumed to be sets of archives if this option is used. 🗂️
  • -A align, --align=align — Forces the initial sample to be aligned on the boundary of a natural time unit, align. Go to PCPIntro(1) for the full description of the syntax for align. 📐
  • --archive-folio=folio — Read metric source archives from the PCP archive folio. 🗃️
  • -c configfile, --view=configfile — configfile specifies an initial view to load, using the default source of metrics. You can specify multiple -c views and they'll all be opened in the default Tab with the default source of metrics. 💜
  • -c, --check — Used with -c, the view(s) are parsed, any errors are reported, and then the tool exits. This is primarily intended for testing purposes. If a second -C option is presented, pmchart also connects to pmcd(1) to check the semantics of metrics. 🔍
  • -f family, --font-family=family — Specify the default font family to be used in several chart components, like the chart title, the legend, and the Y-axis label. The default value is "Sans Serif". Note: this setting does not affect the rest of the user interface, where the value is inherited from the environment in which pmchart operates, and differs according to the look-and-feel of each platform. 🖋️
  • -F point, --font-size=point — Specify the default font point size to be used in several chart components, like the chart title, the legend, and the Y-axis label. The default is platform dependent, but it's either 7, 8 or 9. Same deal as above: this setting does not affect the rest of the user interface. 🔤
  • -g geometry, --geometry=geometry — Generate an image with the specified geometry (width and height). This option is only useful when used alongside the -o option for generating an output image. The geometry argument takes the form "WxH" (e.g. 240x120). When you are NOT using the -o flag, and you want to specify the display window geometry instead, use -geometry geometry where geometry specifies the desired window width, height and optional placement. 📏
  • -h host, --host=host — Current performance metric values are retrieved from the nominated host machine by default. You can present multiple -h options, and that list of hosts is what gets used for sourcing metric values. Same rule as before: any sources listed on the command line are assumed to be hosts if this option is used. 🖥️
  • -H path, --hostsfile=path — Specify the path to a file containing a set of hostnames where pmcd(1) is running, rather than using the default localhost. 🌐
  • -K spec, --spec-local=spec — When fetching metrics from a local context (see -L), the -K option may be used to control the DSO PMDAs that should be made accessible. The spec argument conforms to the syntax described in pmSpecLocalPMDA(3). You can use more than one -K option. 🧩
  • -L, --local-PMDA — Use a local context to collect metrics from DSO PMDAs on the local host without PMCD. See also -K. 🏠
  • -n pmnsfile, --namespace=pmnsfile — Load an alternative Performance Metrics Name Space (PMNS(5)) from the file pmnsfile. 📛
  • -o outfile, --output=outfile — Generate an image file named outfile, and then exit. This is most useful when run with a set of archives and one or more views. The generated image will be in the format specified as the file extension (automatically determined from outfile). If no extension can be determined, then the GIF format is used and the generated file is named with this extension. The supported image file formats include: bmp, jpeg, jpg, png, ppm, tif, tiff, xbm, and xpm. 🖼️
  • -O origin, --origin=origin — When reporting archived metrics, start reporting at origin within the time window (see -S and -T). Go to PCPIntro(1) for the full description of the syntax for origin. 🎯
  • -p port, --guiport=port — port number for connection to an existing pmtime time control process. 🔌
  • -s samples, --samples=samples — Specifies the number of samples that will be retained before discarding old data (replaced by new values at the current time position). This value can subsequently be modified through the Edit Tab dialog. 🔢
  • -S starttime, --start=starttime — When reporting archived metrics, the report will be restricted to those records logged at or after starttime. Go to PCPIntro(1) for the full description of the syntax for starttime. ⏩
  • -t interval, --interval=interval — Sets the initial update interval to something other than the default 1 second. The interval argument follows the syntax described in PCPIntro(1), and in the simplest form it may be an unsigned integer (the implied units in this case are seconds). ⏱️
  • -T endtime, --finish=endtime — When reporting archived metrics, the report will be restricted to those records logged before or at endtime. Go to PCPIntro(1) for the full description of the syntax for endtime. ⏹️
  • -v samples, --visible=samples — Sets the initial visible samples that will be displayed in all charts in the default Tab. This value must be less than or equal to the total number of samples retained (that's the -s value). 👀
  • -V, --version — Display pmchart version number and exit. 👋
  • -W, --white — Export images using an opaque (white) background. 🤍
  • -z, --hostzone — 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 -a options. 🌍
  • -Z timezone, --timezone=timezone — By default, pmtime reports the time of day according to the local timezone on the system where pmchart is run. The -Z option changes the timezone to timezone in the format of the environment variable TZ as described in environ(7). 🕰️
  • -?, --help — Display usage message and exit. ❓

🎀 VIEWS 🎀

The primary pmchart configuration file is the "view", and it's the thing that lets the metadata associated with one or more charts be saved in the filesystem. This metadata describes all aspects of the charts — including which PCP metrics and instances are to be used, which hosts, which colors, the chart titles, use of chart legends, and so much more. 💖

From a conceptual point of view, there are two classes of view. They share the same configuration file format — there's a later section with a complete description of that format — and the differences lie in where they're installed and how they're manipulated. 👑

The first class is the "system" view, which is simply any view installed as part of the pmchart package. These are stored in $PCP_VAR_DIR/config/pmchart. When the File→Open View dialog is displayed, it's these views that are initially listed. Now listen: the system views cannot be modified by a normal user, and they should not be modified even by a user with suitable privileges, because they will be overwritten during an upgrade. 🙅♀️

💀 fr fr do not touch the system views. She will not survive the upgrade and that's on periodt.

The second class of view is the "user" view. These views are created on-the-fly using the File→Save View dialog — it's a mechanism for individual users to save their commonly used views. Access to these views is achieved through the File→Open View dialog, just like with the system views. Once the dialog is opened, the list of views can be toggled between user and system views by clicking on the two toggle buttons in the top right corner. User views are stored in $HOME/.pcp/pmchart. 🦋

✨ TABS ✨

okay so bestie, you know how your browser has tabs? same energy, except it's charts 🎀 pmchart gives you the classic Tab concept — the one that's literally everywhere in modern web browsers — and the whole point is that you can update SO many more charts than your screen could ever physically fit, because tabs let you stack different vertical sets of charts on top of each other and switch between them. Iconic. 💅

Switching between Tabs? Just click on the Tab labels — they're chilling along the top of the display, right beneath the Menu and Tool bars. easy peasy 🦋

Every single Tab has:

  • a mode of operation — either live or archive, and yes, pmchart can lowkey support both modes at the same time 😭
  • the total number of samples and the currently visible points
  • a label describing the Tab, which shows up at the top of the pmchart window

Wanna make a new Tab? Hit up the File→Add Tab dialog. ✨

pro tip for saving that precious vertical screen real estate: the UI element for switching between Tabs (and its label) only shows up when there's more than one Tab. so if you only have one, it's not cluttering your vibe. 🌸

And when you're done with a Tab, dismiss it with the File→Close Tab menu — heads up tho, that removes the current Tab and any charts it contained. it's giving "no takebacks" 💀

🖼️ IMAGES and PRINTING 🖨️

Want a static copy of the vertical series of charts you're staring at? You got two ways, bestie.

1. Screen time 📱 — when the display device you're aiming for is the screen, use the File→Export menu option. This lets you export your charts in a whole variety of image formats, including PNG, JPEG, GIF, and BMP. And the image size? Scale it up or down in any dimension you want. slay.

2. Paper time 📄 — when the intended display device is actual paper, use the File→Print menu option instead. It supports the usual set of printing options (choice of printer, grayscale/color, landscape/portrait, scaling to different paper sizes, etc), and bonus it also lets you print to the intermediate printer formats of PostScript and Portable Document Format (PDF). obsessed. 🫶

🔴 RECORDING 🔴

Okay this part is genuinely so cool. You can make a recording of a set of displayed charts, for later playback through pmchart or any of the other Performance Co-Pilot tools. 🎀

Record→Start is stupid simple to configure through the user interface, and it lets you fine-tune the recording process — including record frequencies that differ to the pmchart update interval, alternate file locations, etc. you're the main character of data collection fr fr 👑

pmchart produces recordings that are compatible with the PCP pmafm(1) replay mechanism, so you can play them back later via a new instance of pmchart. And here's the cute part: when you record through pmchart you can also replay the recording immediately — because on termination of the recording (through the Record→Stop menu item), an archive mode Tab gets created with the captured view. 😭✨

Once recording is active in a Live Tab, the Time Control status button in the bottom left corner of the pmchart window shows up with a distinctive red dot. 🔴 that's your lil indicator that yes, we are recording. At any time during a pmchart recording session, you can see how much space that recording is using in the filesystem via the Record→Query menu item.

Now for the ✨iconic✨ escape hatch: the Record→Detach menu option gives you a mechanism where the recording process can be completely divorced from the running pmchart process, and allowed to keep going even after pmchart exits. A dialog showing the current size and estimated rate of growth for the recording pops up so you know what you're getting into. 🦋

On the other hand — if pmchart gets terminated while a recording is in process, the recording process will prompt the user to choose between immediate cessation of recording, or for it to continue on independently. your call, bestie 💅

All of the record mode services available from pmchart are implemented with the assistance of the base Performance Co-Pilot logging services — go refer to pmlogger(1) and pmafm(1) for an extensive description of the capabilities of these tools. iykyk 📚

📝 CONFIGURATION FILE SYNTAX

okay so this is the part where pmchart loads up its predefined chart configs (aka "views") from external files, and bestie those files have rules. Here's the whole lore:

In everything below, keywords (the bold ones) can show up in UPPER, lower, or MiXeD case, anything wrapped in [stuff] is optional, and anything shown as <other stuff> is on you to supply. A vertical bar (|) means "pick one of these, they're alternatives". And quotes (") can wrap lexical elements that might have white space in them — think titles, labels, instance names. 🎀

  1. The very first line defines the configuration file type, and it should be
#kmchart

although pmchart keeps backwards compatibility for the older pmchart view formats with an initial line of

#pmchart
  1. After that first line, any line where # is the first non-white space character is a comment and gets skipped. Blank lines get skipped too. 💤
  2. The next line should be
version <n> <host-clause>

where <n> depends on the configuration file type, and is 1 for pmchart else 1.1, 1.2 or 2.0 for pmchart.

The <host-clause> part is optional (and ignored) for pmchart configuration files, but required for the pmchart configuration files, and it looks like

host literal

or

host dynamic
  1. A configuration contains one or more charts, defined like this:
chart [title <title>] style <style> <options>

If you specify it, the title shows up centred and above the graph area of the chart. The <title> is usually wrapped in quotes ("), and if it contains the sequence %h that gets swapped out for the short form of the hostname for the default source of metrics at the time this chart was loaded. Or you can use %H to insert the full host name instead. ✨ And heads up: if the hostname looks like an inet or IPv6 address, no shortening is attempted at all — it's used as-is in both replacement cases. After the view is loaded, you can mess with title visibility and setting using the Chart Title text box in the Edit→Chart dialog.

The <style> controls the chart's initial plotting style, and should be one of the keywords plot (line graph), bar, stacking (stacked bar), area or utilization. After the view is loaded, you can change the plotting style with the Edit→Chart Style drop-down list. 🎨

The <options> are zero or more of these optional elements:

[scale [from] <ymin> [to] <ymax>] [legend <onoff>]

If scale is specified, the vertical scaling is set for all plots in the chart to a y-range defined by <ymin> and <ymax>. Otherwise the vertical axis gets autoscaled based on the values currently being plotted.

<onoff> is one of the keywords on or off, and the legend clause controls whether the plot legend below the graph area shows up or not. Default is legend shown, periodt. After the view is loaded, you can toggle legend visibility with the Show Legend button in the Edit→Chart dialog.

  1. pmchart supports a global clause for specifying the dimensions of the top-level window (using the width and height keywords), the number of visible points (the points keyword) and the starting X and Y axis positions on the screen (the xpos and ypos keywords). Each of these global attributes takes an integer value as its sole qualifier. 🧮
  2. Each chart has one or more plots attached to it, defined by one of these:
plot
    [legend <title>] [color <colorspec>] [host <hostspec>]
    metric <metricname>
    [ instance <inst> | matching <pat> | not-matching <pat> ]

You can swap the keyword plot for the keyword optional-plot, and in that case, if the source of performance data doesn't include the specified performance metric and/or instance, then this plot gets silently dropped from the chart. 🙈

If specified, the title appears in the chart legend. The <title> is usually wrapped in quotes (") and it may contain one or more wildcard characters which get expanded using the metric name, instance name and host name for the plot. The wildcards are %i (short unique instance name, up to the first whitespace), %I (full instance name), %h (short host name, up to the first dot), %H (full host name), %m (metric name shortened to the final two PMNS components), and %M (full metric name). 👑

For older pmchart configuration files, you have to use the keyword title instead of legend. These days pmchart supports either keyword, slay.

The color clause is optional for newer pmchart configuration files, but it was mandatory in the original pmchart configuration file format. <colorspec> may be one of:

#-cycle
rgbi:rr:gg:bb
#rgb
#rrggbb
#rrrgggbbb
#rrrrggggbbbb
<Xcolor>

where each of r, g and b are hexadecimal digits (0-9 and A-F) representing respectively the red, green and blue color components. <Xcolor> is one of the color names from the X color database, e.g. red or steelblue, see also the output from showrgb(1). 🌈

The color #-cycle specifies that pmchart should use the next in a pallet of colors that it uses cyclically for each chart. This is the default if the color clause is omitted.

The <hostspec> in the host clause may be a hostname, an IP address, or an asterisk (*); the last one means the default source of performance metrics. For older pmchart configuration files, the host clause must be present; for new pmchart configuration files it's optional, and if it's missing the default source of performance metrics gets used.

The optional instance specification,

(a) is omitted, in which case one plot will be created for every instance of the <metricname> metric

(b) starts with instance, in which case only the instance named <inst> will be plotted

(c) starts with matching, in which case all instances whose names match the pattern <pat> will be plotted; the pattern uses extended regular expression notation in the style of egrep(1) (refer to the PMCD view for an example)

(d) starts with not-matching, in which case all instances whose names do not match the pattern <pat> will be plotted; the pattern uses extended regular expression notation in the style of egrep(1) (refer to the Netbytes view for an example)

pmchart uses a bizarre syntactic notation where <inst> and <pat> extend from the first non-white space character to the end of the input line. For pmchart configuration files these elements are either delimited by white space, or enclosed in quotes ("). 💀

  1. The optional tab directive can be used to create views with multiple charts which span multiple Tabs. The syntax is:
tab <label> [host <host>] [points <points> [samples <samples>]]

All chart specifications following this keyword will be created on the new Tab, until the end of the configuration file or until another tab keyword shows up. 🗂️

🌍 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). 🫶

And of particular note — the $PCP_XCONFIRM_PROG setting is explicitly and unconditionally overridden by pmchart. It's set to the pmconfirm(1) utility, so that some popup dialogs (especially in the area of Recording) keep a consistent look-and-feel with the rest of the pmchart application. 💅

🐛 DEBUGGING OPTIONS

The -D or --debug option enables the output of additional diagnostics on stderr to help triage problems, although ngl the information is sometimes cryptic and primarily intended to give guidance for developers rather than end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to get a list of the available debugging options and their meaning. 🔍

Debugging options specific to pmchart are:

  • appl2 — view parsing and loading
  • appl3 — lexical scanner from view parsing

👀 SEE ALSO

PCPIntro(1), pmafm(1), pmconfirm(1), pmdumptext(1), pminfo(1), pmrep(1), pmtime(1), pmval(1), pcp.conf(5) and PMNS(5).

and that's the whole page bestie, you're officially a pmchart scholar 💖 this lil masterpiece comes from the Performance Co-Pilot crew, it's PMCHART(1), so go forth and chart, mwah 🎀✨

📦 where this page comes from