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