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 [-CNsTV?]  [-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       -T, --terse
80            This option to pmie_check produces less verbose  output  than  the
81            default.  This is most suitable for a pmie ``farm'' where many in‐
82            stances of pmie are expected to be running.
83
84       -V, --verbose
85            The output from the cron execution of the scripts may be  extended
86            using the -V option to the scripts which will enable verbose trac‐
87            ing of their activity.  By default the scripts generate no  output
88            unless  some  error or warning condition is encountered.  Using -N
89            in conjunction with -V maximizes the diagnostic  capabilities  for
90            debugging.
91
92       -x period, --compress-after=period
93            Log  files  can optionally be compressed after some period to con‐
94            serve disk space.  This is particularly useful for  large  numbers
95            of  pmie processes under the control of pmie_check.  The -x option
96            specifies the number of days after which to compress archive  data
97            files.
98
99       -X program, --compressor=program
100            This  option specifies the program to use for compression - by de‐
101            fault this is xz(1).
102
103       -Y regex, --regex=regex
104            This option allows a regular expression to  be  specified  causing
105            files  in the set of files matched for compression to be omitted -
106            this allows only the data file to be compressed, and also prevents
107            the  program  from  attempting to compress it more than once.  The
108            default regex is  ".(meta|index|Z|gz|bz2|zip|xz|lzma|lzo|lz4)$"  -
109            such files are filtered using the -v option to egrep(1).
110
111       -?, --help
112            Display usage message and exit.
113

CONFIGURATION

115       Warning:  The  $PCP_PMIECONTROL_PATH  and $PCP_PMIECONTROL_PATH.d files
116       must not be writable by any user other than root.
117
118       The control file(s) should be customized  according  to  the  following
119       rules  that  define  for  the current version (1.1) of the control file
120       format.
121
122       1.  Lines beginning with a ``#'' are comments.
123       2.  Lines beginning with a ``$'' are assumed to be assignments to envi‐
124           ronment variables in the style of sh(1), and all text following the
125           ``$'' will be eval'ed by the script reading the control  file,  and
126           the  corresponding variable exported into the environment.  This is
127           particularly useful to set and export variables into  the  environ‐
128           ment of the administrative script, e.g.
129               $ PMCD_CONNECT_TIMEOUT=20
130       3.  There  must  be  a  version line in the initial control file of the
131           form:
132               $ version=1.1
133       4.  There should be one line in the control file(s) for each  pmie  in‐
134           stance of the form:
135
136               host y|n y|n logfile args
137
138       5.  Fields within a line of the control file(s) are separated by one or
139           more spaces or tabs.
140       6.  The first field is the name of the host that is the default  source
141           of the performance metrics for this pmie instance.
142       7.  The  second  field indicates if this is a primary pmie instance (y)
143           or not (n).  Since the primary inference engine must run on the lo‐
144           cal  host,  and  there  may be at most one primary for a particular
145           host, this field can be y for at most one pmie instance,  in  which
146           case the host name must be the name of the local host.  When gener‐
147           ating pmie configuration files, the primary clause  indicates  that
148           pmieconf(1)  should enable all rules in the primary group, in addi‐
149           tion to all other default rules.
150       8.  The third field indicates whether this pmie instance  needs  to  be
151           started  under  the  control  of  pmsocks(1)  to  connect to a pmcd
152           through a firewall (y or n).
153       9.  The fourth field is the name of the pmie activity log file.  A use‐
154           ful  convention  is  that  pmie instances monitoring the local host
155           with   hostname   myhost   are   maintained   in   the    directory
156           $PCP_LOG_DIR/pmie/myhost,  while  activity logs for the remote host
157           mumble are maintained in $PCP_LOG_DIR/pmie/mumble.  This is consis‐
158           tent  with  the way pmlogger(1) maintains its activity logs and ar‐
159           chive files.
160       10. All other fields are interpreted  as  arguments  to  be  passed  to
161           pmie(1).  Most typically this would be the -c option.
162
163       The following sample control lines specify one pmie instance monitoring
164       the local host (wobbly), and  another  monitoring  performance  metrics
165       from the host splat.
166
167       wobbly  n  PCP_LOG_DIR/pmie/wobbly  -c config.default
168       splat   n  PCP_LOG_DIR/pmie/splat   -c splat/cpu.conf
169
170       Typical  crontab(5)  entries  for  periodic execution of pmie_daily and
171       pmie_check are given in $PCP_SYSCONF_DIR/pmie/crontab (unless installed
172       by default in /etc/cron.d already) and shown below.
173
174       # daily processing of pmie logs
175       08      0       *       *       *       $PCP_BINADM_DIR/pmie_daily
176       # every 30 minutes, check pmie instances are running
177       28,58   *       *       *       *       $PCP_BINADM_DIR/pmie_check
178       When  using  systemd(1)  on Linux, no crontab entries are needed as the
179       timer mechanism provided by systemd is used instead.
180

FILES

182       $PCP_PMIECONTROL_PATH
183            the default PCP inference engine control file
184            Warning: this file must not be writable by  any  user  other  than
185            root.
186
187       $PCP_PMIECONTROL_PATH.d
188            optional directory containing additional PCP inference engine con‐
189            trol files, typically one per host
190            Warning: this files herein must not be writable by any user  other
191            than root.
192
193       $PCP_SYSCONF_DIR/pmie/crontab
194            sample  crontab  for  automated  script execution by $PCP_USER (or
195            root)  -  exists  only  if  the  platform  does  not  support  the
196            /etc/cron.d mechanism.
197
198       $PCP_VAR_DIR/config/pmie/config.default
199            default  pmlogger  configuration file location for a localhost in‐
200            ference engine, typically generated automatically by pmieconf(1).
201
202       $PCP_LOG_DIR/pmie/pmie_check.log
203            default location for the pmie_check log file.  When run as a  dae‐
204            mon  service, if the pmie process failed to start or exited early,
205            there may be error messages in this file, particularly if the dae‐
206            mon could not open it's own log file.
207
208       $PCP_LOG_DIR/pmie/pmie_daily.log
209            default  location  for  error  messages generated during the daily
210            pmie service maintenance operations.
211
212       $PCP_LOG_DIR/pmie/<hostname>
213            default directory location for the pmie  log  file  for  the  host
214            hostname
215
216       $PCP_LOG_DIR/pmie/<hostname>/lock
217            transient  lock file to guarantee mutual exclusion during pmie ad‐
218            ministration for the host hostname - if present, can be safely re‐
219            moved if neither pmie_daily nor pmie_check are running
220
221       $PCP_LOG_DIR/NOTICES
222            PCP ``notices'' file used by pmie(1) and friends
223

PCP ENVIRONMENT

225       Environment variables with the prefix PCP_ are used to parameterize the
226       file and directory names used by PCP.  On each installation,  the  file
227       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
228       $PCP_CONF variable may be used to specify an alternative  configuration
229       file, as described in pcp.conf(5).
230

SEE ALSO

232       egrep(1),  PCPIntro(1),  pmie(1),  pmieconf(1),  systemd(1),  xz(1) and
233       cron(8).
234
235
236
237Performance Co-Pilot                  PCP                        PMIE_CHECK(1)
Impressum