pmchart(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | 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 [-CLVWz?]  [-a archive] [-A align] [--archive-folio
       folio] [-c configfile] [-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         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         top

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

       -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, fB--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         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

       PCPIntro(1), pmafm(1), pmconfirm(1), pmdumptext(1), pminfo(1),
       pmrep(1), pmtime(1), pmval(1), pcp.conf(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@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  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)

Pages that refer to this page: ganglia2pcp(1)iostat2pcp(1)mkaf(1)mrtg2pcp(1)pcp2elasticsearch(1)pcp2graphite(1)pcp2influxdb(1)pcp2json(1)pcp2spark(1)pcp2template(1)pcp2xlsx(1)pcp2xml(1)pcp2zabbix(1)pcpcompat(1)pcpintro(1)pcp-iostat(1)pcp-tapestat(1)pmafm(1)pmclient(1)pmdaweblog(1)pmdumptext(1)pminfo(1)pmlogsummary(1)pmquery(1)pmrep(1)pmsnap(1)pmstat(1)pmtime(1)pmval(1)pmview(1)sar2pcp(1)sheet2pcp(1)pmparsehostattrsspec(3)pmparsehostspec(3)pmregisterderived(3)LOGARCHIVE(5)pmview(5)