# pmchart

## NAME



           **pmchart** - strip chart tool for Performance Co-Pilot
    


## 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_...]
    


## 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 (X-axis), and through the
           use of multiple interface Tabs.
    
           Metric values can be sourced from one or more live hosts
           (simultaneously).  Alternatively, one or more sets of PCP archives
           can be used as a source of historical data.  See PCPIntro(1) for
           an in-depth discussion of the capabilities of the PCP framework,
           many of which are used by **pmchart.**
    
           Many aspects of the behaviour of **pmchart** can be customised through
           the interface.  In particular, the use of "views" (refer to the
           section describing VIEWS later in this document) allows predefined
           sets of metrics and charting parameters like colors, scaling,
           titles, legends, and so on to be stored for later use, or use with
           different hosts and sets of archives.  In addition, the
           Preferences dialog allows customisations to the rest of the
           **pmchart** user interface to be saved and restored between different
           invocations of the tool.  This allows the default background
           color, highlight color, contents and location of the toolbar, and
           many other aspects to be configured.
    
           **pmchart** makes extensive use of the pmtime(1) utility for time
           control, refer to the **pmtime** manual page for further details of
           its operation.
    


## 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, each of which may be the base name of an archive or
                the name of a directory containing one or more archives.  The
                resulting set of archives will be the source of the
                performance metrics.  The initial Tab created will be an
                archive mode Tab.  Multiple **-a** options can be presented, and
                the resulting list of sets of archives is used for sourcing
                metric values.  Any _sources_ listed on the command line are
                assumed to be sets of archives if this option is used.
    
           **-A** _align_ , **--align** =_align_
                Force the initial sample to be aligned on the boundary of a
                natural time unit _align_.  Refer to PCPIntro(1) for a complete
                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.  Multiple **-c** views can be
                specified, and they will 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 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, such as the chart title, legend, and Y-axis
                label.  The default value is "Sans Serif".  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, such as the chart title, legend, and Y-axis
                label.  The default is platform dependent, but is either 7, 8
                or 9.  This setting does not affect the rest of the user
                interface.
    
           **-g** _geometry_ , **--geometry** =_geometry_
                Generate image with the specified _geometry_ (width and
                height).  This option is only useful when used in conjunction
                with the **-o** option for generating an output image.  The
                _geometry_ argument takes the form "WxH" (e.g. 240x120).  When
                NOT using the **-o** flag, to specify the display window
                geometry, 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.  Multiple **-h** options can
                be presented, and the list of hosts is used for sourcing
                metric values.  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).  More than one **-K** option may
                be used.
    
           **-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**).  Refer to PCPIntro(1)
                for a complete 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_.
                Refer to PCPIntro(1) for a complete 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 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_.
                Refer to PCPIntro(1) for a complete 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 (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", which allows
           the metadata associated with one or more charts to 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
           much more.
    
           From a conceptual point of view, there are two classes of view.
           These views share the same configuration file format - refer to a
           later section for a complete description of this format.  The
           differences lie in where they are installed and how they are
           manipulated.
    
           The first class, the "system" view, is simply any view that is
           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 is these views that are initially listed.  The
           system views cannot be modified by a normal user, and should not
           be modified even by a user with suitable privileges, as they will
           be overwritten during an upgrade.
    
           The second class of view is the "user" view.  These views are
           created on-the-fly using the _File→Save View_ dialog.  This is a
           mechanism for individual users to save their commonly used views.
           Access to these views is achieved through the _File→Open View_
           dialog, as 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



           **pmchart** provides the common user interface concept of the Tab,
           which is most prevalent in modern web browsers.  Tabs allow
           **pmchart** to update many more charts than the available screen real
           estate allows, by providing a user interface mechanism to stack
           (and switch between) different vertical sets of charts.  Switching
           between Tabs is achieved by clicking on the Tab labels, which are
           located along the top of the display beneath the Menu and Tool
           bars).
    
           Each Tab has a mode of operation (either live or archive - **pmchart**
           can support both modes simultaneously), the total number of
           samples and currently visible points, and a label describing the
           Tab which is displayed at the top of the **pmchart** window.  New Tabs
           can be created using the _File→Add Tab_ dialog.
    
           In order to save on vertical screen real estate, note that the
           user interface element for changing between different Tabs (and
           its label) are only displayed when more than one Tab exists.  A
           Tab can be dismissed using the _File→Close Tab_ menu, which removes
           the current Tab and any charts it contained.
    


## IMAGES and PRINTING



           A static copy of the currently displayed vertical series of charts
           can be captured in two ways.
    
           When the intended display device is the screen, the _File→Export_
           menu option should be used.  This allows exporting the charts in a
           variety of image formats, including PNG, JPEG, GIF, and BMP.  The
           image size can be scaled up or down in any dimension.
    
           Alternatively, when the intended display device is paper, the
           _File→Print_ menu option can be used.  This supports the usual set
           of printing options (choice of printer, grayscale/color,
           landscape/portrait, scaling to different paper sizes, etc), and in
           addition allows printing to the intermediate printer formats of
           PostScript and Portable Document Format (PDF).
    


## RECORDING



           It is possible to make a recording of a set of displayed charts,
           for later playback through **pmchart** or any of the other Performance
           Co-Pilot tools.  The _Record→Start_ functionality is simple to
           configure through the user interface, and allows fine-tuning of
           the recording process (including record frequencies that differ to
           the **pmchart** update interval, alternate file locations, etc).
    
           **pmchart** produces recordings that are compatible with the PCP
           pmafm(1) replay mechanism, for later playback via a new instance
           of **pmchart**.  In addition, when recording through **pmchart** one can
           also replay the recording immediately, as on termination of the
           recording (through the _Record→Stop_ menu item), an archive mode Tab
           will be 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 is
           displayed with a distinctive red dot.  At any time during a
           **pmchart** recording session, the amount of space used in the
           filesystem by that recording can be displayed using the
           _Record→Query_ menu item.
    
           Finally, the _Record→Detach_ menu option provides a mechanism
           whereby the recording process can be completely divorced from the
           running **pmchart** process, and allowed to continue on when **pmchart**
           exits.  A dialog displaying the current size and estimated rate of
           growth for the recording is presented.  On the other hand, if
           **pmchart** is terminated while recording is in process, then the
           recording process will prompt the user to choose immediate
           cessation of recording or for it to continue on independently.
    
           All of the record mode services available from **pmchart** are
           implemented with the assistance of the base Performance Co-Pilot
           logging services - refer to pmlogger(1) and pmafm(1) for an
           extensive description of the capabilities of these tools.
    


## CONFIGURATION FILE SYNTAX



           **pmchart** loads predefined chart configurations (or "views") from
           external files that conform to the following rules.  In the
           descriptions below keywords (shown in **bold**) may appear in upper,
           lower or mixed case, elements shown in [stuff] are optional, and
           user-supplied elements are shown as <other stuff>.  A vertical bar
           (|) is used where syntactic elements are alternatives.  Quotes (")
           may be used to enclose lexical elements that may contain white
           space, such as titles, labels and instance names.
    
           1. The first line defines the configuration file type and should
              be
                   **#kmchart**
              although **pmchart** provides backwards compatibility for the older
              **pmchart** view formats with an initial line of
                   **#pmchart**
    
           2. After the first line, lines beginning with "#" as the first
              non-white space character are treated as comments and skipped.
              Similarly blank lines are skipped.
    
           3. 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 is of the form
                   **host literal**
              or
                   **host dynamic**
    
           4. A configuration contains one or more charts defined as follows:
                   **chart**[**title** <title>] **style** <style> <options>
              If specified, the title will appear centred and above the graph
              area of the chart.  The <title> is usually enclosed in quotes
              (") and if it contains the sequence "%h" this will be replaced
              by the short form of the hostname for the default source of
              metrics at the time this chart was loaded.  Alternatively, "%H"
              can be used to insert the full host name.  If the hostname
              appears to be an inet or IPv6 address, no shortening will be
              attempted; it will be used as-is in both replacement cases.
              After the view is loaded, the title visibility and setting can
              be manipulated using the _Chart Title_ text box in the _Edit→Chart_
              dialog.
    
              The <style> controls the initial plotting style of the chart,
              and should be one of the keywords **plot**(line graph), **bar** ,
              **stacking**(stacked bar), **area** or **utilization**.  After the view is
              loaded, the plotting style can be changed using the _Edit→Chart_
              Style drop-down list.
    
              The <options> are zero or more of the 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 will be autoscaled based on the
              values currently being plotted.
    
              <onoff> is one of the keywords **on** or **off** and the **legend** clause
              controls the presence or absence of the plot legend below the
              graph area.  The default is for the legend to be shown.  After
              the view is loaded, the legend visibility can be toggled using
              the _Show Legend_ button in the _Edit→Chart_ dialog.
    
           5. **pmchart** supports a **global** clause to specify the dimensions of
              the top-level window (using the **width** and **height** keywords), the
              number of visible points (**points** keyword) and the starting X
              and Y axis positions on the screen (**xpos** and **ypos** keywords).
              Each of these **global** attributes takes an integer value as the
              sole qualifier.
    
           6. Each **chart** has one or more plots associated with it, as defined
              by one of the following specifications:
                   **plot**
                       [**legend** <title>] [**color** <colorspec>] [**host** <hostspec>]
                       **metric** <metricname>
                       [ **instance** <inst> | **matching** <pat> | **not-matching** <pat> ]
    
              The keyword **plot** may be replaced with the keyword **optional-**
              **plot** , in which case if the source of performance data does not
              include the specified performance metric and/or instance, then
              this plot is silently dropped from the chart.
    
              If specified, the title will appear in the chart legend.  The
              <title> is usually enclosed in quotes (") and it may contain
              one or more wildcard characters which will be expanded using
              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, the keyword **title** must
              be used instead of **legend**.  Nowadays **pmchart** supports either
              keyword.
    
              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 the
              following:
                   **#-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 latter is used to mean the
              default source of performance metrics.  For older **pmchart**
              configuration files, the **host** clause must be present, for new
              **pmchart** configuration files it is optional, and if missing the
              default source of performance metrics will be 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 (").
    
           7. The optional **tab** directive can be used to create views with
              multiple charts which span multiple Tabs.  The syntax is as
              follows:
                   **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 is encountered.
    


## 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).
    
           Of particular note, the **$PCP_XCONFIRM_PROG** setting is explicitly
           and unconditionally overridden by **pmchart**.  This is set to the
           pmconfirm(1), utility, in order that some popup dialogs
           (particularly in the area of Recording) maintain 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 the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmchart** are as follows:
           ┌────────┬───────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────┤
           │ **appl2** │ view parsing and loading          │
           ├────────┼───────────────────────────────────┤
           │ **appl3** │ lexical scanner from view parsing │
           └────────┴───────────────────────────────────┘
    


* * *