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

NAME

       pmsnap - generate performance summary snapshot images

SYNOPSIS

       $PCP_BINADM_DIR/pmsnap [-NV] [-C dir] [-c configs] [-n names] [-o dir] [-t type]

DESCRIPTION

       pmsnap  is  a  shell  script that is normally run periodically from crontab(1) to generate
       graphic images of pmchart(1) performance charts.  These  images  can  be  in  any  of  the
       supported  pmchart formats, including png, bmp, and jpeg, and may be incorporated into the
       content offered by the local Web server.  The -V option enables  verbose  tracing  of  the
       actions.   By default pmsnap generates no output unless some error or warning condition is
       encountered.

       pmsnap generates  images  according  to  its  control  file,  $PCP_PMSNAPCONTROL_PATH  (or
       dir/control  if  the -C option is specified), and uses archive logs created by pmlogger(1)
       or PCP archive folios created by pmafm(1) and  pmlogger_check(1).   Before  attempting  to
       configure  pmsnap, it is strongly recommended that pmlogger be configured according to the
       descriptions in pmlogger_daily(1), pmlogger_check(1) and pmlogger(1).

       Once pmlogger has been configured, it is necessary to configure pmsnap as follows;

       1.     Edit the  control  file  $PCP_PMSNAPCONTROL_PATH.   The  syntax  of  this  file  is
              described in the comment at the head of the file and an example is supplied for one
              and twelve  hour  "Summary"  performance  charts  for  the  local  host.   Suitable
              arguments  for  pmchart are also described in the comment.  The user should consult
              pmchart for further details.  Note that when pmsnap is run, it globally substitutes
              the string LOCALHOSTNAME with the name of the local host in the control file.

       2.     Test the configuration by running
                                            $PCP_BINADM_DIR/pmsnap.
              Without   any   arguments   pmsnap   will   process   every   non-comment  line  in
              $PCP_PMSNAPCONTROL_PATH.  The output images will be placed in the  files  named  in
              the  first field of each line in the control file, with the file format appended if
              necessary.  If these file names do not start with / or .   then  they  are  assumed
              relative  to  dir, as specified with the -o option.  The default dir is the current
              directory.  Note that if pmlogger has only been recently started (within about  the
              last  15  minutes), snap-shot images may not be produced and no error messages will
              be issued - the reason is that pmchart can not use very short archives  and  hence,
              neither can pmsnap.  For debugging purposes the -V flag should be used.

       3.     Add  an  appropriate  entry  for  pmsnap in the root user's crontab.  An example is
              supplied in $PCP_VAR_DIR/config/pmlogger/crontab.

       4.     Incorporate the pmsnap images into the local WWW content.  Usually, WWW  pages  use
              images  that  are relative to a particular document root, so it is often convenient
              to use the -o command line option to specify  a  sub-directory  of  the  local  WWW
              content,  and  then  create  a  web  page in this directory that shows the snapshot
              images with text and other content appropriate to the local environment.

OPTIONS

       pmsnap accepts the following command line options;

       -C dir The control file is located in  the  directory  dir  rather  than  in  the  default
              $PCP_PMSNAPCONTROL_PATH location.

       -c config-pattern
              Only  process  lines  in  the  control  file which match the config-pattern regular
              expression in the Config column.

       -n name-pattern
              Only process lines in  the  control  file  which  match  the  name-pattern  regular
              expression (see egrep(1)) in the Name column.

       -o dir The  output images having file names which do not start with / or .  will be placed
              in a directory relative to dir, otherwise the output directory is relative  to  the
              current  directory (i.e. the default value for dir is ./).  Note that dir must be a
              writable directory path and may be on an NFS or CIFS file system.

       The -N option enables a ``show me'' mode, where the actions are echoed, but not  executed,
       in  the  style  of  ``make -n''.  Using -N in conjunction with -V maximizes the diagnostic
       capabilities for debugging.

       When either -n or -c are used, pmsnap will only process lines in the  control  file  which
       match  all  the  supplied  patterns.   If  no  patterns  are given, then all lines will be
       processed.  These arguments allow multiple entries for pmsnap in crontab so that different
       performance  summary  images  can  be  generated  at  different  times  or  with different
       frequencies.

       A  sample  HTML  page,   suitable   for   the   Summary   snapshot   may   be   found   in
       $PCP_VAR_DIR/config/pmsnap/Summary.html.

       Although  pmsnap  attempts  to  flush  stdio(3)  output  buffers  in the relevant pmlogger
       processes before generating snap-shots images, this may fail for assorted reasons  and  no
       error message will be given.

       pmsnap  should not be invoked immediately after pmlogger_daily has rolled the logs because
       the new archive logs will be too short to obtain meaningful results.   Note  however  that
       pmsnap  will  not  report  errors  from pmchart about not being able to comply with the -A
       option on very short archives.  In these cases no error will be  reported  and  no  output
       images will be produced.

FILES

       $PCP_PMSNAPCONTROL_PATH
                 pmsnap control file

       $PCP_VAR_DIR/config/pmsnap/Summary
                 summary view for pmchart

       $PCP_VAR_DIR/config/pmsnap/Summary.html
                 sample HTML page for summary snapshot

       $PCP_LOG_DIR/pmlogger/hostname/Latest
                 PCP archive folio for the host hostname, as generated by pmlogger_check

       $PCP_VAR_DIR/config/pmlogger/crontab
                 example crontab entry

SEE ALSO

       cron(1),    crontab(1),    egrep(1),    pmchart(1),    pmafm(1),   pmlc(1),   pmlogger(1),
       pmlogger_daily(1), X(1), and Xvfb(1).