NAME | SYNOPSIS | DESCRIPTION | VIEWS | TABS | IMAGES and PRINTING | RECORDING | CONFIGURATION FILE SYNTAX | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMCHART(1)                 General Commands Manual                PMCHART(1)

NAME         top

       pmchart - strip chart tool for Performance Co-Pilot

SYNOPSIS         top

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

DESCRIPTION         top

       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 which control the default source, timing and layout of the
       pmchart window are as follows:

       -a   Performance metric values are retrieved from the set of
            Performance Co-Pilot (PCP) archive logs 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.

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

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

       -p   port number for connection to an existing pmtime time control
            process.

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

       -t   Sets the inital 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).

       -v   Sets the inital 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   Display pmchart version number and exit

       -W   Export images using an opaque(white) background

       -Z   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).

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

VIEWS         top

       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         top

       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         top

       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         top

       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         top

       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 dropdown
          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         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).

       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.

SEE ALSO         top

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

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-03-13.  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                                              PMCHART(1)