Provided by: pcp-gui_5.3.6-1build1_amd64 bug

NAME

       pmchart - strip chart tool for Performance Co-Pilot

SYNOPSIS

       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

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

       -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

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

       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

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