pmsnap - generate performance summary snapshot images
$PCP_BINADM_DIR/pmsnap [-NV] [-C dir] [-c configs] [-n names] [-o dir] [-t type]
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 sup-
ported 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
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 argu-
ments 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
Without any arguments pmsnap will process every non-comment line in $PCP_PMSNAPCON-
TROL_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 sup-
plied 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 con-
tent, 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
Only process lines in the control file which match the config-pattern regular
expression in the Config column.
Only process lines in the control file which match the name-pattern regular expres-
sion (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 pro-
cessed. These arguments allow multiple entries for pmsnap in crontab so that different
performance summary images can be generated at different times or with different frequen-
A sample HTML page, suitable for the Summary snapshot may be found in $PCP_VAR_DIR/con-
Although pmsnap attempts to flush stdio(3) output buffers in the relevant pmlogger pro-
cesses 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.
pmsnap control file
summary view for pmchart
sample HTML page for summary snapshot
PCP archive folio for the host hostname, as generated by pmlogger_check
example crontab entry
cron(1), crontab(1), egrep(1), pmchart(1), pmafm(1), pmlc(1), pmlogger(1), pmlog-
ger_daily(1), X(1), and Xvfb(1).
Performance Co-Pilot PMSNAP(1)