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

NAME

6       pmie_check,  pmie_daily  -  administration  of the Performance Co-Pilot
7       inference engine
8

SYNOPSIS

10       $PCP_BINADM_DIR/pmie_check [-CNsV] [-c control] [-l logfile]
11       $PCP_BINADM_DIR/pmie_daily [-NV] [-c control] [-k discard] [-l logfile]
12       [-m addresses] [-x compress] [-X program] [-Y regex]
13

DESCRIPTION

15       This  series  of shell scripts and associated control files may be used
16       to create a customized regime of administration and management for  the
17       Performance Co-Pilot (see PCPintro(1)) inference engine, pmie(1).
18
19       pmie_daily  is intended to be run once per day, preferably in the early
20       morning, as soon after midnight as practicable.  Its task is to  rotate
21       the  log  files  for  the running pmie processes - these files may grow
22       without bound if the ``print'' action is used, or any other pmie action
23       writes  to  its stdout/stderr streams.  After some period, old pmie log
24       files are discarded.  This period is 14 days by  default,  but  may  be
25       changed  using the -k option. Two special values are recognized for the
26       period (discard), namely 0 to keep no log files beyond the current one,
27       and forever to prevent any log files being discarded.
28
29       Log files can optionally be compressed after some period (compress), to
30       conserve disk space.  This is particularly useful for large numbers  of
31       pmie  processes  under the control of pmie_check.  The -x option speci‐
32       fies the number of days after which to compress archive data files, and
33       the -X option specifies the program to use for compression - by default
34       this is xz(1).  Use of the -Y option allows a regular expression to  be
35       specified  causing files in the set of files matched for compression to
36       be omitted - this allows only the data file to be compressed, and  also
37       prevents  the  program  from  attempting to compress it more than once.
38       The default regex  is  ".(meta|index|Z|gz|bz2|zip|xz|lzma|lzo|lz4)$"  -
39       such files are filtered using the -v option to egrep(1).
40
41       Use  of  the  -m option causes pmie_daily to construct a summary of the
42       log files generated for all monitored hosts in the last 24 hours (lines
43       matching  ``  OK  '' are culled), and e-mail that summary to the set of
44       space-separated addresses.
45
46       pmie_check may be run at any time, and is intended to  check  that  the
47       desired  set  of pmie(1) processes are running, and if not to re-launch
48       any failed inference engines.   Use  of  the  -s  option  provides  the
49       reverse functionality, allowing the set of pmie processes to be cleanly
50       shutdown.  Use of the -C option queries  the  system  service  runlevel
51       information  for pmie, and uses that to determine whether to start pro‐
52       cesses.
53
54       Both pmie_check and pmie_daily are controlled by PCP  inference  engine
55       control  file(s)  that  specify  the pmie instances to be managed.  The
56       default control file is $PCP_PMIECONTROL_PATH but an alternate  may  be
57       specified  using  the  -c  option.   If the directory $PCP_PMLOGGERCON‐
58       TROL_PATH.d (or control.d from the -c option) exists, then the contents
59       of  any  additional  control files therein will be appended to the main
60       control file (which must exist).
61
62       Warning: The $PCP_PMIECONTROL_PATH  and  $PCP_PMIECONTROL_PATH.d  files
63       must not be writable by any user other than root.
64
65       The  control  file(s)  should  be customized according to the following
66       rules that define for the current version (1.1)  of  the  control  file
67       format.
68
69       1.  Lines beginning with a ``#'' are comments.
70       2.  Lines beginning with a ``$'' are assumed to be assignments to envi‐
71           ronment variables in the style of sh(1), and all text following the
72           ``$''  will  be eval'ed by the script reading the control file, and
73           the corresponding variable exported into the environment.  This  is
74           particularly  useful  to set and export variables into the environ‐
75           ment of the administrative script, e.g.
76               $ PMCD_CONNECT_TIMEOUT=20
77       3.  There must be a version line in the initial  control  file  of  the
78           form:
79               $ version=1.1
80       4.  There  should  be  one  line  in  the control file(s) for each pmie
81           instance of the form:
82
83               host y|n y|n logfile args
84
85       5.  Fields within a line of the control file(s) are separated by one or
86           more spaces or tabs.
87       6.  The  first field is the name of the host that is the default source
88           of the performance metrics for this pmie instance.
89       7.  The second field indicates if this is a primary pmie  instance  (y)
90           or  not  (n).   Since  the primary inference engine must run on the
91           local host, and there may be at most one primary for  a  particular
92           host,  this  field can be y for at most one pmie instance, in which
93           case the host name must be the name of the local host.  When gener‐
94           ating  pmie  configuration files, the primary clause indicates that
95           pmieconf (1) should enable all rules in the primary group, in addi‐
96           tion to all other default rules.
97       8.  The  third  field  indicates whether this pmie instance needs to be
98           started under the control  of  pmsocks(1)  to  connect  to  a  pmcd
99           through a firewall (y or n).
100       9.  The fourth field is the name of the pmie activity log file.  A use‐
101           ful convention is that pmie instances  monitoring  the  local  host
102           with    hostname   myhost   are   maintained   in   the   directory
103           $PCP_LOG_DIR/pmie/myhost, while activity logs for the  remote  host
104           mumble are maintained in $PCP_LOG_DIR/pmie/mumble.  This is consis‐
105           tent with the way pmlogger(1) maintains its activity logs  and  ar‐
106           chive files.
107       10. All  other  fields  are  interpreted  as  arguments to be passed to
108           pmie(1).  Most typically this would be the -c option.
109
110       The following sample control lines specify one pmie instance monitoring
111       the  local  host  (wobbly),  and another monitoring performance metrics
112       from the host splat.
113
114       wobbly  n  PCP_LOG_DIR/pmie/wobbly  -c config.default
115       splat   n  PCP_LOG_DIR/pmie/splat   -c splat/cpu.conf
116
117       Typical crontab(5) entries for periodic  execution  of  pmie_daily  and
118       pmie_check are given in $PCP_SYSCONF_DIR/pmie/crontab (unless installed
119       by default in /etc/cron.d already) and shown below.
120
121       # daily processing of pmie logs
122       08      0       *       *       *       $PCP_BINADM_DIR/pmie_daily
123       # every 30 minutes, check pmie instances are running
124       28,58   *       *       *       *       $PCP_BINADM_DIR/pmie_check
125
126       In order to ensure that mail is not  unintentionally  sent  when  these
127       scripts  are run from cron(8) diagnostics are always sent to log files.
128       By  default,  these  files  are  $PCP_LOG_DIR/pmie/pmie_daily.log   and
129       $PCP_LOG_DIR/pmie/pmie_check.log  but  this can be changed using the -l
130       option.  If this log file already exists when  the  script  starts,  it
131       will  be  renamed  with  a .prev suffix (overwriting any log file saved
132       earlier) before diagnostics are generated to the new log file.
133
134       The output from the cron execution of the scripts may be extended using
135       the -V option to the scripts which will enable verbose tracing of their
136       activity.  By default the scripts generate no output unless some  error
137       or warning condition is encountered.
138
139       The -N option enables a ``show me'' mode, where the actions are echoed,
140       but not executed, in the style of ``make -n''.  Using -N in conjunction
141       with -V maximizes the diagnostic capabilities for debugging.
142

FILES

144       $PCP_PMIECONTROL_PATH
145                 the default PCP inference engine control file
146                 Warning:  this  file  must  not be writable by any user other
147                 than root.
148
149       $PCP_PMIECONTROL_PATH.d
150                 optional directory containing additional PCP inference engine
151                 control files, typically one per host
152                 Warning:  this  files herein must not be writable by any user
153                 other than root.
154
155       $PCP_SYSCONF_DIR/pmie/crontab
156                 sample crontab for automated script  execution  by  $PCP_USER
157                 (or  root) - exists only if the platform does not support the
158                 /etc/cron.d mechanism.
159
160       $PCP_VAR_DIR/config/pmie/config.default
161                 default pmlogger configuration file location for a  localhost
162                 inference   engine,   typically  generated  automatically  by
163                 pmieconf(1).
164
165       $PCP_LOG_DIR/pmie/hostname
166                 default location for the pmie log file for the host hostname
167
168       $PCP_LOG_DIR/pmie/hostname/lock
169                 transient lock file to guarantee mutual exclusion during pmie
170                 administration  for  the  host  hostname - if present, can be
171                 safely removed if neither pmie_daily nor pmie_check are  run‐
172                 ning
173
174       $PCP_LOG_DIR/NOTICES
175                 PCP ``notices'' file used by pmie(1) and friends
176

PCP ENVIRONMENT

178       Environment variables with the prefix PCP_ are used to parameterize the
179       file and directory names used by PCP.  On each installation,  the  file
180       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
181       $PCP_CONF variable may be used to specify an alternative  configuration
182       file, as described in pcp.conf(5).
183

SEE ALSO

185       egrep(1), PCPintro(1), pmie(1), pmieconf(1), xz(1) and cron(8).
186
187
188
189Performance Co-Pilot                  PCP                        PMIE_CHECK(1)
Impressum