xenial (1) pmchart.1.gz

Provided by: pcp-gui_3.10.8build1_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] [-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.

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

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

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