1PMSNAP(1)                   General Commands Manual                  PMSNAP(1)
2
3
4

NAME

6       pmsnap - generate performance summary snapshot images
7

SYNOPSIS

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

DESCRIPTION

13       pmsnap is a  shell  script  that  is  normally  run  periodically  from
14       crontab(1) to generate graphic images of pmchart(1) performance charts.
15       These images can be in any of the supported pmchart formats,  including
16       png, bmp, and jpeg, and may be incorporated into the content offered by
17       the local Web server.  The -V option enables  verbose  tracing  of  the
18       actions.   By  default  pmsnap generates no output unless some error or
19       warning condition is encountered.
20
21       pmsnap generates images according to its control file,  $PCP_PMSNAPCON‐
22       TROL_PATH  (or dir/control if the -C option is specified), and uses ar‐
23       chive logs created by pmlogger(1) or  PCP  archive  folios  created  by
24       pmafm(1) and pmlogger_check(1).  Before attempting to configure pmsnap,
25       it is strongly recommended that pmlogger be configured according to the
26       descriptions in pmlogger_daily(1), pmlogger_check(1) and pmlogger(1).
27
28       Once  pmlogger has been configured, it is necessary to configure pmsnap
29       as follows;
30
31       1.     Edit the control file $PCP_PMSNAPCONTROL_PATH.   The  syntax  of
32              this  file  is  described in the comment at the head of the file
33              and an example is supplied for one  and  twelve  hour  "Summary"
34              performance  charts  for the local host.  Suitable arguments for
35              pmchart are also described in the comment.  The user should con‐
36              sult pmchart for further details.  Note that when pmsnap is run,
37              it globally substitutes the string LOCALHOSTNAME with  the  name
38              of the local host in the control file.
39
40       2.     Test the configuration by running
41                                  $PCP_BINADM_DIR/pmsnap.
42              Without any arguments pmsnap will process every non-comment line
43              in $PCP_PMSNAPCONTROL_PATH.  The output images will be placed in
44              the  files  named in the first field of each line in the control
45              file, with the file format appended if necessary.  If these file
46              names  do  not start with / or .  then they are assumed relative
47              to dir, as specified with the -o option.  The default dir is the
48              current directory.  Note that if pmlogger has only been recently
49              started (within about the last 15 minutes), snap-shot images may
50              not  be produced and no error messages will be issued - the rea‐
51              son is that pmchart can not use very short archives  and  hence,
52              neither  can  pmsnap.  For debugging purposes the -V flag should
53              be used.
54
55       3.     Add an appropriate entry for pmsnap in the root user's  crontab.
56              An example is supplied in $PCP_VAR_DIR/config/pmlogger/crontab.
57
58       4.     Incorporate  the pmsnap images into the local WWW content.  Usu‐
59              ally, WWW pages use images that are  relative  to  a  particular
60              document  root,  so it is often convenient to use the -o command
61              line option to specify a sub-directory of the local WWW content,
62              and  then  create  a  web  page in this directory that shows the
63              snapshot images with text and other content appropriate  to  the
64              local environment.
65

OPTIONS

67       pmsnap accepts the following command line options;
68
69       -C dir The  control file is located in the directory dir rather than in
70              the default $PCP_PMSNAPCONTROL_PATH location.
71
72       -c config-pattern
73              Only process lines in the control file which match  the  config-
74              pattern regular expression in the Config column.
75
76       -n name-pattern
77              Only process lines in the control file which match the name-pat‐
78              tern regular expression (see egrep(1)) in the Name column.
79
80       -o dir The output images having file names which do not start with / or
81              .   will be placed in a directory relative to dir, otherwise the
82              output directory is relative to the current directory (i.e.  the
83              default  value for dir is ./).  Note that dir must be a writable
84              directory path and may be on an NFS or CIFS file system.
85
86       The -N option enables a ``show me'' mode, where the actions are echoed,
87       but not executed, in the style of ``make -n''.  Using -N in conjunction
88       with -V maximizes the diagnostic capabilities for debugging.
89
90       When either -n or -c are used, pmsnap will only process  lines  in  the
91       control file which match all the supplied patterns.  If no patterns are
92       given, then all lines will be processed.  These arguments allow  multi‐
93       ple entries for pmsnap in crontab so that different performance summary
94       images can be generated at different times or with  different  frequen‐
95       cies.
96
97       A  sample  HTML page, suitable for the Summary snapshot may be found in
98       $PCP_VAR_DIR/config/pmsnap/Summary.html.
99
100       Although pmsnap attempts to flush stdio(3) output buffers in the  rele‐
101       vant  pmlogger  processes before generating snap-shots images, this may
102       fail for assorted reasons and no error message will be given.
103
104       pmsnap should not  be  invoked  immediately  after  pmlogger_daily  has
105       rolled  the  logs  because  the  new  archive logs will be too short to
106       obtain meaningful results.  Note however that pmsnap  will  not  report
107       errors  from  pmchart about not being able to comply with the -A option
108       on very short archives.  In these cases no error will be  reported  and
109       no output images will be produced.
110

FILES

112       $PCP_PMSNAPCONTROL_PATH
113                 pmsnap control file
114
115       $PCP_VAR_DIR/config/pmsnap/Summary
116                 summary view for pmchart
117
118       $PCP_VAR_DIR/config/pmsnap/Summary.html
119                 sample HTML page for summary snapshot
120
121       $PCP_LOG_DIR/pmlogger/hostname/Latest
122                 PCP  archive  folio  for  the  host hostname, as generated by
123                 pmlogger_check
124
125       $PCP_VAR_DIR/config/pmlogger/crontab
126                 example crontab entry
127

SEE ALSO

129       cron(1), crontab(1), egrep(1), pmchart(1),  pmafm(1),  pmlc(1),  pmlog‐
130       ger(1), pmlogger_daily(1), X(1), and Xvfb(1).
131
132
133
134Performance Co-Pilot                                                 PMSNAP(1)
Impressum