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  configs] [-C dir] [-f format] [-n
10       names] [-o dir]
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.  By default pmsnap generates  no  textual  output
18       unless some error or warning condition is encountered.
19
20       pmsnap  generates images according to its control file, $PCP_PMSNAPCON‐
21       TROL_PATH (or dir/control if the -C option is specified), and uses  ar‐
22       chive  logs  created  by  pmlogger(1)  or PCP archive folios created by
23       pmafm(1) and pmlogger_check(1).  Before attempting to configure pmsnap,
24       it is strongly recommended that pmlogger be configured according to the
25       descriptions in pmlogger_daily(1), pmlogger_check(1) and pmlogger(1).
26
27       Once pmlogger has been configured, it is necessary to configure  pmsnap
28       as follows;
29
30       1.     Edit  the  control  file $PCP_PMSNAPCONTROL_PATH.  The syntax of
31              this file is described in the comment at the head  of  the  file
32              and  an  example  is  supplied for one and twelve hour "Summary"
33              performance charts for the local host.  Suitable  arguments  for
34              pmchart are also described in the comment.  The user should con‐
35              sult pmchart for further details.  Note that when pmsnap is run,
36              it  globally  substitutes the string LOCALHOSTNAME with the name
37              of the local host in the control file.
38
39       2.     Test the configuration by running
40                                  $PCP_BINADM_DIR/pmsnap.
41              Without any arguments pmsnap will process every non-comment line
42              in $PCP_PMSNAPCONTROL_PATH.  The output images will be placed in
43              the files named in the first field of each line in  the  control
44              file, with the file format appended if necessary.  If these file
45              names do not start with / or .  then they are  assumed  relative
46              to dir, as specified with the -o option.  The default dir is the
47              current directory.  Note that if pmlogger has only been recently
48              started  (within about the last 15 minutes), snapshot images may
49              not be produced and no error messages will be issued - the  rea‐
50              son  is  that pmchart can not use very short archives and hence,
51              neither can pmsnap.  For debugging purposes the -V  flag  should
52              be used.
53
54       3.     Add  an appropriate entry for pmsnap in the root user's crontab.
55              An example is supplied in $PCP_VAR_DIR/config/pmlogger/crontab.
56
57       4.     Incorporate the pmsnap images into the local WWW content.   Usu‐
58              ally,  WWW  pages  use  images that are relative to a particular
59              document root, so it is often convenient to use the  -o  command
60              line option to specify a sub-directory of the local WWW content,
61              and then create a web page in  this  directory  that  shows  the
62              snapshot  images  with text and other content appropriate to the
63              local environment.
64
65       A sample HTML page, suitable for the Summary snapshot may be  found  in
66       $PCP_VAR_DIR/config/pmsnap/Summary.html.
67
68       Although  pmsnap attempts to flush stdio(3) output buffers in the rele‐
69       vant pmlogger processes before generating snapshots  images,  this  may
70       fail for assorted reasons and no error message will be given.
71
72       pmsnap  should  not  be  invoked  immediately  after pmlogger_daily has
73       rolled the logs because the new archive  logs  will  be  too  short  to
74       obtain  meaningful  results.   Note however that pmsnap will not report
75       errors from pmchart about not being able to comply with the  -A  option
76       on  very  short archives.  In these cases no error will be reported and
77       no output images will be produced.
78

OPTIONS

80       The available command line options are:
81
82       -c config-pattern
83            Only process lines in the control file which match the config-pat‐
84            tern regular expression in the Config column.
85
86       -C dir
87            The  control  file  is located in the directory dir rather than in
88            the default $PCP_PMSNAPCONTROL_PATH location.
89
90       -f format
91            Set output image format.  The defaults format is png.
92
93       -n name-pattern
94            Only process lines in the control file which match  the  name-pat‐
95            tern regular expression (see egrep(1)) in the Name column.
96
97       -N   Enable  a  ``show me'' mode, where the actions are echoed, but not
98            executed, in the style of ``make -n''.  Using  -N  in  conjunction
99            with -V maximizes the diagnostic capabilities for debugging.
100
101       -o dir
102            The output images having file names which do not start with / or .
103            will be placed in a directory relative to dir, otherwise the  out‐
104            put  directory  is  relative  to  the  current directory (i.e. the
105            default value for dir is ./).  Note that dir must  be  a  writable
106            directory path and may be on an NFS or CIFS file system.
107
108       -V   Enable verbose mode.
109
110       -?   Display usage message and exit.
111
112       When  either  -n  or -c are used, pmsnap will only process lines in the
113       control file which match all the supplied patterns.  If no patterns are
114       given,  then all lines will be processed.  These arguments allow multi‐
115       ple entries for pmsnap in crontab so that different performance summary
116       images  can  be generated at different times or with different frequen‐
117       cies.
118

FILES

120       $PCP_PMSNAPCONTROL_PATH
121            pmsnap control file
122
123       $PCP_VAR_DIR/config/pmsnap/Summary
124            summary view for pmchart
125
126       $PCP_VAR_DIR/config/pmsnap/Summary.html
127            sample HTML page for summary snapshot
128
129       $PCP_LOG_DIR/pmlogger/<hostname>/Latest
130            PCP archive folio for the host hostname, as  generated  by  pmlog‐
131            ger_check
132
133       $PCP_VAR_DIR/config/pmlogger/crontab
134            example crontab entry
135

SEE ALSO

137       cron(1),  crontab(1),  egrep(1),  pmafm(1), pmchart(1), pmlc(1), pmlog‐
138       ger(1) and pmlogger_daily(1).
139
140
141
142Performance Co-Pilot                                                 PMSNAP(1)
Impressum