1PMIE_CHECK(1) General Commands Manual PMIE_CHECK(1)
2
6 pmie_check, pmie_daily - administration of the Performance Co-Pilot
7 inference engine
8
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
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 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 pme 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 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 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 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 or
52 stop processes.
53 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 The control file(s) should be customized according to the following
63 rules.
64 1. Lines beginning with a ``#'' are comments.
66 2. Lines beginning with a ``$'' are assumed to be assignments to
67 environment variables in the style of sh(1), and all text fol‐
68 lowing the ``$'' will be eval'ed by the script reading the con‐
69 trol file, and the corresponding variable exported into the
70 environment. This is particularly useful to set and export
71 variables into the environment of the administrative script,
72 e.g.
73 $ PMCD_CONNECT_TIMEOUT=20
74 Warning: The $PCP_PMIECONTROL_PATH and $PCP_PMIECONTROL_PATH.d
75 files must not be writable by any user other than root.
76 3. There should be one line in the control file(s) for each pmie
77 instance of the form:
78 host y|n logfile args
80 4. Fields within a line of the control file(s) are separated by one
82 or more spaces or tabs.
83 5. The first field is the name of the host that is the default
84 source of the performance metrics for this pmie instance.
85 6. The second field indicates whether this pmie instance needs to
86 be started under the control of pmsocks(1) to connect to a pmcd
87 through a firewall (y or n).
88 8. The third field is the name of the pmie activity log file. A
89 useful convention is that pmie instances monitoring the local
90 host with hostname myhost are maintained in the directory
91 $PCP_LOG_DIR/pmie/myhost, while activity logs for the remote
92 host mumble are maintained in $PCP_LOG_DIR/pmie/mumble. This is
93 consistent with the way pmlogger(1) maintains its activity logs
94 and archive files.
95 9. All other fields are interpreted as arguments to be passed to
96 pmie(1). Most typically this would be the -c option.
97 The following sample control lines specify one pmie instance monitoring
99 the local host (wobbly), and another monitoring performance metrics
100 from the host splat.
101 wobbly n PCP_LOG_DIR/pmie/wobbly -c config.default
103 splat n PCP_LOG_DIR/pmie/splat -c splat/cpu.conf
104 Typical crontab(5) entries for periodic execution of pmie_daily and
106 pmie_check are given in $PCP_SYSCONF_DIR/pmie/crontab (unless installed
107 by default in /etc/cron.d already) and shown below.
108 # daily processing of pmie logs
110 08 0 * * * $PCP_BINADM_DIR/pmie_daily
111 # every 30 minutes, check pmie instances are running
112 28,58 * * * * $PCP_BINADM_DIR/pmie_check
113 In order to ensure that mail is not unintentionally sent when these
115 scripts are run from cron(8) diagnostics are always sent to log files.
116 By default, these files are $PCP_LOG_DIR/pmie/pmie_daily.log and
117 $PCP_LOG_DIR/pmie/pmie_check.log but this can be changed using the -l
118 option. If this log file already exists when the script starts, it
119 will be renamed with a .prev suffix (overwriting any log file saved
120 earlier) before diagnostics are generated to the new log file.
121 The output from the cron execution of the scripts may be extended using
123 the -V option to the scripts which will enable verbose tracing of their
124 activity. By default the scripts generate no output unless some error
125 or warning condition is encountered.
126 The -N option enables a ``show me'' mode, where the actions are echoed,
128 but not executed, in the style of ``make -n''. Using -N in conjunction
129 with -V maximizes the diagnostic capabilities for debugging.
130
132 $PCP_PMIECONTROL_PATH
133 the default PCP inference engine control file
134 Warning: this file must not be writable by any user other
135 than root.
136 $PCP_PMIECONTROL_PATH.d
138 optional directory containing additional PCP inference engine
139 control files, typically one per host
140 Warning: this files herein must not be writable by any user
141 other than root.
142 $PCP_SYSCONF_DIR/pmie/crontab
144 sample crontab for automated script execution by $PCP_USER
145 (or root) - exists only if the platform does not support the
146 /etc/cron.d mechanism.
147 $PCP_VAR_DIR/config/pmie/config.default
149 default pmlogger configuration file location for a localhost
150 inference engine, typically generated automatically by
151 pmieconf(1).
152 $PCP_LOG_DIR/pmie/hostname
154 default location for the pmie log file for the host hostname
155 $PCP_LOG_DIR/pmie/hostname/lock
157 transient lock file to guarantee mutual exclusion during pmie
158 administration for the host hostname - if present, can be
159 safely removed if neither pmie_daily nor pmie_check are run‐
160 ning
161 $PCP_LOG_DIR/NOTICES
163 PCP ``notices'' file used by pmie(1) and friends
164
166 Environment variables with the prefix PCP_ are used to parameterize the
167 file and directory names used by PCP. On each installation, the file
168 /etc/pcp.conf contains the local values for these variables. The
169 $PCP_CONF variable may be used to specify an alternative configuration
170 file, as described in pcp.conf(5).
171
173 egrep(1), PCPintro(1), pmie(1), pmieconf(1), xz(1) and cron(8).
174Performance Co-Pilot PCP PMIE_CHECK(1)