Provided by: pcp-gui_4.0.1-1_amd64 bug

NAME

       pmchart - strip chart tool for Performance Co-Pilot

SYNOPSIS

       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

       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

       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

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