path: root/man/man1/pmie_check.1

'\"macro stdmacro
.\"
.\" Copyright (c) 2013-2014 Red Hat.
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\" 
.\"
.TH PMIE_CHECK 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmie_check\f1,
\f3pmie_daily\f1 \- administration of the Performance Co-Pilot inference engine
.SH SYNOPSIS
.B $PCP_BINADM_DIR/pmie_check
[\f3\-CNsV\f1]
[\f3\-c\f1 \f2control\f1]
.br
.B $PCP_BINADM_DIR/pmie_daily
[\f3\-NV\f1]
[\f3\-c\f1 \f2control\f1]
[\f3\-k\f1 \f2discard\f1]
[\f3\-m\f1 \f2addresses\f1]
[\f3\-x\f1 \f2compress\f1]
[\f3\-X\f1 \f2program\f1]
[\f3\-Y\f1 \f2regex\f1]
.br
.SH DESCRIPTION
This series of shell scripts and associated control files may be used to
create a customized regime of administration and management for the
Performance Co-Pilot (see
.BR PCPintro (1))
inference engine,
.BR pmie (1).
.PP
.B pmie_daily
is intended to be run once per day, preferably in the early morning, as
soon after midnight as practicable.  Its task is to rotate the log files
for the running
.B pmie
processes \- these files may grow without bound if the
``print'' action is used, or any other
.B pme
action writes to its stdout/stderr streams.
After some period, old
.B pmie
log files are discarded.
This period is 14 days by default, but may be changed using the
.B \-k
option. Two special values are recognized for the period (\c
.IR discard ),
namely
.B 0
to keep no log files beyond the current one, and
.B forever
to prevent any log files being discarded.
.PP
Log files can optionally be compressed after some period (\c
.IR compress ),
to conserve disk space.  This is particularly useful for large numbers of
.B pmie
processes under the control of
.BR pmie_check .
The
.B \-x
option specifies the number of days after which to compress archive data
files, and the
.B \-X
option specifies the program to use for compression \- by default this is
.BR xz (1).
Use of the
.B \-Y
option allows a regular expression to be specified causing files in
the set of files matched for compression to be omitted \- this allows
only the data file to be compressed, and also prevents the program from
attempting to compress it more than once.  The default
.I regex
is "\.(meta|index|Z|gz|bz2|zip|xz|lzma|lzo|lz4)$" \- such files are
filtered using the
.B \-v
option to
.BR egrep (1).
.PP
Use of the
.B \-m
option causes
.B pmie_daily
to construct a summary of the log files generated for all monitored hosts
in the last 24 hours (lines matching `` OK '' are culled), and e-mail that
summary to the set of space-separated
.IR addresses .
.PP
.B pmie_check
may be run at any time, and is intended to check that the desired set
of
.BR pmie (1)
processes are running, and if not to re-launch any failed inference engines.
Use of the
.B \-s
option provides the reverse functionality, allowing the set of
.B pmie
processes to be cleanly shutdown.
Use of the
.B \-C
option queries the system service runlevel information for
.BR pmie ,
and uses that to determine whether to start or stop processes.
.PP
Both
.B pmie_check
and
.B pmie_daily
are controlled by a PCP inference engine control file that specifies the
.B pmie
instances to be managed.  The default control file is
.B $PCP_PMIECONTROL_PATH
but an alternate may be specified using the
.B \-c
option.
.PP
The control file should be customized according to the following rules.
.IP 1.
Lines beginning with a ``#'' are comments.
.PD 0 parameters of the
.IP 2.
Lines beginning with a ``$'' are assumed to be
assignments to environment variables in the style of
.BR sh (1),
and all text following the ``$'' will be
.BR eval 'ed
by the script reading the control file,
and the corresponding variable exported into the environment.
This is particularly
useful to set and export variables into the environment of
the administrative script, e.g.
.br
.in +4n
.ft CW
.nf
$ PMCD_CONNECT_TIMEOUT=20
.fi
.ft R
.in -4n
.br
.BR Warning :
The
.B $PCP_PMIECONTROL_PATH
file must not be writable by any user other than root.
.br
.IP 3.
There should be one line in the control file
for each
.B pmie
instance of the form:

.in +4n
.ft CW
.nf
\f2host\f1 \f3y\f1|\f3n\f1 \f2logfile\f1 \f2args\f1
.fi
.ft R
.in -4n

.IP 4.
Fields within a line of the control file
are separated by one or more spaces or tabs.
.IP 5.
The
.I first
field is the name of the host that is the default source of the
performance metrics for this
.B pmie
instance.
.IP 6.
The
.I second
field indicates whether this
.B pmie
instance needs to be started under the control of
.BR pmsocks (1)
to connect to a
.B pmcd
through a firewall (\c
.B y
or
.BR n ).
.IP 8.
The
.I third
field is the name of the
.B pmie
activity log file.  
A useful convention is that
.B pmie
instances monitoring the local host
with hostname
.I myhost
are maintained in the directory
.BI $PCP_LOG_DIR/pmie/ myhost\fR,
while activity logs for the remote host
.I mumble
are maintained in
.BI $PCP_LOG_DIR/pmie/ mumble\fR.
This is consistent with the way
.BR pmlogger (1)
maintains its activity logs and archive files.
.IP 9.
All other fields are interpreted as arguments to be passed to
.BR pmie (1).
Most typically this would be the
.B \-c
option.
.PD
.PP
The following sample control lines specify one
.B pmie
instance monitoring the local host (\c
.IR wobbly ),
and another monitoring performance metrics from the host
.IR splat .
.PP
.nf
.ft CW
wobbly  n  PCP_LOG_DIR/pmie/wobbly  \-c config.default
splat   n  PCP_LOG_DIR/pmie/splat   \-c splat/cpu.conf
.ft 1
.fi
.PP
Typical
.BR crontab (5)
entries for periodic execution of
.B pmie_daily
and
.B pmie_check
are given in
.BR $PCP_SYSCONF_DIR/pmie/crontab
(unless installed by default in
.IR /etc/cron.d
already)
and shown below.
.PP
.nf
.ft CW
# daily processing of pmie logs
08      0       *       *       *       $PCP_BINADM_DIR/pmie_daily
# every 30 minutes, check pmie instances are running
28,58   *       *       *       *       $PCP_BINADM_DIR/pmie_check
.ft 1
.fi
.PP
The output from the
.BR cron (8)
execution of the scripts may be extended using the
.B \-V
option to the scripts which will enable verbose tracing of their activity.
By default the scripts generate no output unless some error or warning
condition is encountered.
.PP
The
.B \-N
option enables a ``show me'' mode, where the actions are echoed,
but not executed, in the style of ``make \-n''.
Using
.B \-N
in conjunction with
.B \-V
maximizes the diagnostic capabilities for debugging.
.SH FILES
.TP 10
.B $PCP_PMIECONTROL_PATH
the default PCP inference engine control file
.br
.BR Warning :
this file must not be writable by any user other than root.
.TP
.B $PCP_SYSCONF_DIR/pmie/crontab
sample crontab for automated script execution by $PCP_USER (or root) -
exists only if the platform does not support the
.I /etc/cron.d
mechanism.
.TP
.B $PCP_SYSCONF_DIR/pmie/config.default
default
.B pmlogger
configuration file location for a localhost inference engine, typically
generated automatically by
.BR pmieconf (1).
.TP
.BI $PCP_LOG_DIR/pmie/ hostname
default location for the pmie log file for the host
.I hostname
.TP
.BI $PCP_LOG_DIR/pmie/ hostname /lock
transient lock file to guarantee mutual exclusion during
.B pmie
administration for the host
.I hostname
\- if present, can be safely removed if neither
.B pmie_daily
nor
.B pmie_check
are running
.TP
.B $PCP_LOG_DIR/NOTICES
PCP ``notices'' file used by
.BR pmie (1)
and friends
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.B /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
.SH SEE ALSO
.BR egrep (1),
.BR PCPintro (1),
.BR pmie (1),
.BR pmieconf (1),
.BR xz (1)
and
.BR cron (8).