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

NAME

6       pmie_check, pmie_daily - administration of the Performance Co-Pilot in‐
7       ference engine
8

SYNOPSIS

10       $PCP_BINADM_DIR/pmie_check [-CNPpsTV?]  [-c control] [-l logfile]
11       $PCP_BINADM_DIR/pmie_daily [-NV?]  [-c control] [-k discard]  [-l  log‐
12       file] [-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_check  may  be  run at any time of the day and verifies that a de‐
20       sired set of pmie processes is running.  If  not,  it  (re-)starts  any
21       missing inference engine processes.
22
23       pmie_daily  is intended to be run once per day, preferably in the early
24       morning, as soon after midnight as practicable.  Its task is to  rotate
25       the  log  files  for  the running pmie processes - these files may grow
26       without bound if the ``print'' action is used, or any other pmie action
27       writes  to  its stdout/stderr streams.  After some period, old pmie log
28       files are discarded.
29

OPTIONS

31       The available command line options are:
32
33       -c control, --control=control
34            Both pmie_check and pmie_daily are controlled by PCP inference en‐
35            gine  control  file(s)  that specify the pmie instances to be man‐
36            aged.  The default control file is  $PCP_PMIECONTROL_PATH  but  an
37            alternate  may be specified using the -c option.  If the directory
38            $PCP_PMLOGGERCONTROL_PATH.d (or control.d from the -c option)  ex‐
39            ists,  then  the  contents of any additional control files therein
40            will be appended to the main control file (which must exist).
41
42       -C   This option causes pmie_check to query the system service runlevel
43            information  for  pmie, and use that to determine whether to start
44            processes or not.
45
46       -k period, --discard=period
47            The log retention period is 14 days by default, but  this  may  be
48            changed  using this option.  Two special values are recognized for
49            the discard period, namely 0 to keep no log files beyond the  cur‐
50            rent one, and forever to prevent any log files being discarded.
51
52       -l file, --logfile=file
53            In  order  to  ensure  that  mail is not unintentionally sent when
54            these scripts are run from cron(8) diagnostics are always sent  to
55            log      files.       By      default,     these     files     are
56            $PCP_LOG_DIR/pmie/pmie_daily.log                               and
57            $PCP_LOG_DIR/pmie/pmie_check.log but this can be changed using the
58            -l option.  If this  log  file  already  exists  when  the  script
59            starts,  it  will  be renamed with a .prev suffix (overwriting any
60            log file saved earlier) before diagnostics are  generated  to  the
61            new log file.
62
63       -m addresses, --mail=addresses
64            Use of this option causes pmie_daily to construct a summary of the
65            log files generated for all monitored hosts in the last  24  hours
66            (lines  matching  `` OK '' are culled), and e-mail that summary to
67            the set of space-separated addresses.
68
69       -N, --showme
70            This option enables a ``show me'' mode, where the programs actions
71            are  echoed, but not executed, in the style of ``make -n''.  Using
72            -N in conjunction with -V maximizes  the  diagnostic  capabilities
73            for debugging.
74
75       -s, --stop
76            Use  of this option provides the reverse pmie_check functionality,
77            allowing the set of pmie processes to be cleanly shutdown.
78
79       -p, --skip-primary
80            If this option is specified for pmie_check then any line from  the
81            control  files  for the primary pmie will be ignored.  This option
82            is intended for environments where some system daemon,  like  sys‐
83            temd(1),  is  responsible  for  controlling  (starting,  stopping,
84            restarting, etc.) the primary pmie.
85
86       -P, --only-primary
87            If this option is specified for pmie_check then only  the  primary
88            pmie  entry  in  the control files will be processed.  This is the
89            logical opposite of the -p option described above and is  intended
90            for  use  by  RC scripts that start only the primary pmie, such as
91            the pmie.service unit.  The -p and -P options  to  pmie_check  are
92            mutually exclusive.
93
94       -T, --terse
95            This  option  to  pmie_check produces less verbose output than the
96            default.  This is most suitable for a pmie ``farm'' where many in‐
97            stances of pmie are expected to be running.
98
99       -V, --verbose
100            The  output from the cron execution of the scripts may be extended
101            using the -V option to the scripts which will enable verbose trac‐
102            ing  of their activity.  By default the scripts generate no output
103            unless some error or warning condition is encountered.   Using  -N
104            in  conjunction  with -V maximizes the diagnostic capabilities for
105            debugging.
106
107       -x period, --compress-after=period
108            Log files can optionally be compressed after some period  to  con‐
109            serve  disk  space.  This is particularly useful for large numbers
110            of pmie processes under the control of pmie_check.  The -x  option
111            specifies  the number of days after which to compress archive data
112            files.
113
114       -X program, --compressor=program
115            This option specifies the program to use for compression - by  de‐
116            fault this is xz(1).
117
118       -Y regex, --regex=regex
119            This  option  allows  a regular expression to be specified causing
120            files in the set of files matched for compression to be omitted  -
121            this allows only the data file to be compressed, and also prevents
122            the program from attempting to compress it more  than  once.   The
123            default  regex  is ".(meta|index|Z|gz|bz2|zip|xz|lzma|lzo|lz4)$" -
124            such files are filtered using the -v option to egrep(1).
125
126       -?, --help
127            Display usage message and exit.
128

CONFIGURATION

130       Warning: The $PCP_PMIECONTROL_PATH  and  $PCP_PMIECONTROL_PATH.d  files
131       must not be writable by any user other than root.
132
133       The  control  file(s)  should  be customized according to the following
134       rules that define for the current version (1.1)  of  the  control  file
135       format.
136
137       1.  Lines beginning with a ``#'' are comments.
138       2.  Lines beginning with a ``$'' are assumed to be assignments to envi‐
139           ronment variables in the style of sh(1), and all text following the
140           ``$''  will  be eval'ed by the script reading the control file, and
141           the corresponding variable exported into the environment.  This  is
142           particularly  useful  to set and export variables into the environ‐
143           ment of the administrative script, e.g.
144               $ PMCD_CONNECT_TIMEOUT=20
145       3.  There must be a version line in the initial  control  file  of  the
146           form:
147               $ version=1.1
148       4.  There  should  be one line in the control file(s) for each pmie in‐
149           stance of the form:
150
151               host y|n y|n logfile args
152
153       5.  Fields within a line of the control file(s) are separated by one or
154           more spaces or tabs.
155       6.  The  first field is the name of the host that is the default source
156           of the performance metrics for this pmie instance.
157       7.  The second field indicates if this is a primary pmie  instance  (y)
158           or not (n).  Since the primary inference engine must run on the lo‐
159           cal host, and there may be at most one  primary  for  a  particular
160           host,  this  field can be y for at most one pmie instance, in which
161           case the host name must be the name of the local host.  When gener‐
162           ating  pmie  configuration files, the primary clause indicates that
163           pmieconf(1) should enable all rules in the primary group, in  addi‐
164           tion to all other default rules.
165       8.  The  third  field  indicates whether this pmie instance needs to be
166           started under the control  of  pmsocks(1)  to  connect  to  a  pmcd
167           through a firewall (y or n).
168       9.  The fourth field is the name of the pmie activity log file.  A use‐
169           ful convention is that pmie instances  monitoring  the  local  host
170           with    hostname   myhost   are   maintained   in   the   directory
171           $PCP_LOG_DIR/pmie/myhost, while activity logs for the  remote  host
172           mumble are maintained in $PCP_LOG_DIR/pmie/mumble.  This is consis‐
173           tent with the way pmlogger(1) maintains its activity logs  and  ar‐
174           chive files.
175       10. All  other  fields  are  interpreted  as  arguments to be passed to
176           pmie(1).  Most typically this would be the -c option.
177
178       The following sample control lines specify one pmie instance monitoring
179       the  local  host  (wobbly),  and another monitoring performance metrics
180       from the host splat.
181
182       wobbly  n  PCP_LOG_DIR/pmie/wobbly  -c config.default
183       splat   n  PCP_LOG_DIR/pmie/splat   -c splat/cpu.conf
184
185       Typical crontab(5) entries for periodic  execution  of  pmie_daily  and
186       pmie_check are given in $PCP_SYSCONF_DIR/pmie/crontab (unless installed
187       by default in /etc/cron.d already) and shown below.
188
189       # daily processing of pmie logs
190       08      0       *       *       *       $PCP_BINADM_DIR/pmie_daily
191       # every 30 minutes, check pmie instances are running
192       28,58   *       *       *       *       $PCP_BINADM_DIR/pmie_check
193       When using systemd(1) on Linux, no crontab entries are  needed  as  the
194       timer mechanism provided by systemd is used instead.
195
196       The  pmiectl(1) utility may invoke pmie_check using the sudo(1) command
197       to run it under the $PCP_USER ``pcp'' account.  If sudo  is  configured
198       with the non-default requiretty option (see below), pmie_check may fail
199       to run due to not having a tty configured.  This issue can be  resolved
200       by adding a second line (expand $PCP_BINADM_DIR according to your plat‐
201       form) to the /etc/sudoers configuration file as follows:
202
203            Defaults requiretty
204            Defaults!$PCP_BINADM_DIR/pmie_check !requiretty
205
206       Note that the unprivileged PCP account under which these  commands  run
207       uses  /sbin/nologin  as the shell, so the requiretty option is ineffec‐
208       tive here and safe to disable in this way.
209

FILES

211       $PCP_PMIECONTROL_PATH
212            the default PCP inference engine control file
213            Warning: this file must not be writable by  any  user  other  than
214            root.
215
216       $PCP_PMIECONTROL_PATH.d
217            optional directory containing additional PCP inference engine con‐
218            trol files, typically one per host
219            Warning: this files herein must not be writable by any user  other
220            than root.
221
222       $PCP_SYSCONF_DIR/pmie/crontab
223            sample  crontab  for  automated  script execution by $PCP_USER (or
224            root)  -  exists  only  if  the  platform  does  not  support  the
225            /etc/cron.d mechanism.
226
227       $PCP_VAR_DIR/config/pmie/config.default
228            default pmie configuration file location for a localhost inference
229            engine, typically generated automatically by pmieconf(1).
230
231       $PCP_LOG_DIR/pmie/pmie_check.log
232            default location for the pmie_check log file.  When run as a  dae‐
233            mon  service, if the pmie process failed to start or exited early,
234            there may be error messages in this file, particularly if the dae‐
235            mon could not open it's own log file.
236
237       $PCP_LOG_DIR/pmie/pmie_daily.log
238            default  location  for  error  messages generated during the daily
239            pmie service maintenance operations.
240
241       $PCP_LOG_DIR/pmie/<hostname>
242            default directory location for the pmie  log  file  for  the  host
243            hostname
244
245       $PCP_LOG_DIR/pmie/<hostname>/lock
246            transient  lock file to guarantee mutual exclusion during pmie ad‐
247            ministration for the host hostname - if present, can be safely re‐
248            moved if neither pmie_daily nor pmie_check are running
249
250       $PCP_LOG_DIR/NOTICES
251            PCP ``notices'' file used by pmie(1) and friends
252

PCP ENVIRONMENT

254       Environment variables with the prefix PCP_ are used to parameterize the
255       file and directory names used by PCP.  On each installation,  the  file
256       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
257       $PCP_CONF variable may be used to specify an alternative  configuration
258       file, as described in pcp.conf(5).
259

SEE ALSO

261       egrep(1),  PCPIntro(1),  pmie(1),  pmieconf(1),  systemd(1),  xz(1) and
262       cron(8).
263
264
265
266Performance Co-Pilot                  PCP                        PMIE_CHECK(1)
Impressum