Man Linux: Main Page and Category List

NAME

       pmchart, kmchart - strip chart tool for Performance Co-Pilot

SYNOPSIS

       pmchart  [-CVWz]  [-A align] [-a archive] [-c configfile] [-g geometry]
       [-h  host]  [-o  outfile]  [-O  offset]  [-p  port]  [-s  samples]  [-S
       starttime]  [-T  endtime]  [-t  interval]  [-v  visible]  [-Z timezone]
       [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 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
       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 Performance Co-
            Pilot (PCP) archive log file identified by the base name  archive,
            by  default.  The initial Tab created will be an archive mode Tab.
            Multiple -a options can be presented, and the list of archives  is
            used  for  sourcing  metric  values.   Any  sources  listed on the
            command line are assumed to be 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.

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

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

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

       -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  FileOpen  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 priviledges, 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  FileSave View dialog.  This is a mechanism for
       individual users to save their commonly used views.   Access  to  these
       views is achieved through the FileOpen 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 FileAdd 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 FileClose 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 FileExport 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
       FilePrint  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  RecordStart 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
       RecordStop 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 RecordQuery menu item.

       Finally, the RecordDetach 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.   After  the  view  is  loaded,  the  title
          visibility and setting can be manipulated using the Chart Title text
          box in the EditChart 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 EditChart Style dropdown
          list.

          The <options> are zero or more of the optional elements:
               [scale [from] <ymin> [to] <ymax>] [legend <onoff>]
          If scale is specfied, 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 EditChart 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  if  it  contains  the
          sequence  "%i" this will be replaced by the metric instance name (if
          any).

          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 hexidecimal 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(4).

       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),
       pmval(1), pmcd(1), pminfo(1), pcp.conf(4), pcp.env(4) and pmns(4).