'\"macro stdmacro
.\"
.\" Copyright (c) 2013-2019 Red Hat.
.\" Copyright (c) 2000 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 PMLOGGER_CHECK 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogger_check\f1 \- administration of Performance Co-Pilot archive files
.SH SYNOPSIS
.B $PCP_BINADM_DIR/pmlogger_check
[\f3\-CNPpqsTV?\f1]
[\f3\-c\f1 \f2control\f1]
[\f3\-l\f1 \f2logfile\f1]
.SH DESCRIPTION
.B pmlogger_check
and the related
.BR pmlogger_daily (1)
tools along with
associated control files (see
.BR pmlogger.control (5))
may be used to
create a customized regime of administration and management for
historical archives of performance data within the
Performance Co-Pilot (see
.BR PCPIntro (1))
infrastructure.
.PP
.B pmlogger_check
may be run at any time of the day and is intended to check that a desired set
of
.BR pmlogger (1)
processes are running.
If not, it (re-)starts any missing logger processes.
By default,
.B pmlogger_check
also calls
.BR pmlogger_daily (1)
with a
.B \-K
option to execute any required archive compression tasks.
.SH OPTIONS
.TP 5
\fB\-C\fR
This option causes
.B pmlogger_check
to query the system service runlevel information for
.BR pmlogger ,
and use that to determine whether to start processes or not.
.TP 5
\fB\-c\fR \fIcontrol\fR, \fB\-\-control\fR=\fIcontrol\fR
Both
.B pmlogger_check
and
.BR pmlogger_daily (1)
are controlled by PCP logger control file(s)
that specifies the
.B pmlogger
instances to be managed.
The default
.I control
file is
.I $PCP_PMLOGGERCONTROL_PATH
but an alternate may be specified using the
.B \-c
option.
If the directory
.IR $PCP_PMLOGGERCONTROL_PATH .d
(or
.IR control .d
from the
.B \-c
option) exists, then the contents of any additional
.I control
files therein will be appended to the main control file (which must exist).
.TP 5
\fB\-l\fR \fIfile\fR, \fB\-\-logfile\fR=\fIfile\fR
In order to ensure that mail is not unintentionally sent when these
scripts are run from
.BR cron (8)
or
.BR systemd (1)
diagnostics are always sent to log files.
By default, this file is
.I $PCP_LOG_DIR/pmlogger/pmlogger_check.log
but this can be changed using the
.B \-l
option.
If this log
.I file
already exists when the script starts, it will be
renamed with a
.I .prev
suffix (overwriting any log file saved earlier) before diagnostics
are generated to the log file.
The
.B \-l
and
.B \-t
options cannot be used together.
.TP 5
\fB\-N\fR, \fB\-\-showme\fR
This 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.
.TP 5
\fB\-P\fR, \fB\-\-only\-primary\fR
If this option is specified for
.B pmlogger_check
then only the primary logger entry in the control files will be processed.
This is the logical opposite of the \fB\-p\fP option described above
and is intended for use by RC scripts that start only the primary logger,
such as the
.B pmlogger.service
unit.
The \fB\-p\fP and \fB\-P\fP options are mutually exclusive.
.TP 5
\fB\-p\fR, \fB\-\-skip\-primary\fR
If this option is specified for
.B pmlogger_check
then any line from the control files for the
.I primary
.B pmlogger
will be ignored.
This option is intended for environments where some system daemon,
like
.BR systemd (1),
is responsible for controlling (starting, stopping, restarting, etc.) the
.I primary
.BR pmlogger .
.TP 5
\fB\-q\fR, \fB\-\-quick\fR
If this option is specified for
.B pmlogger_check
then the script will ``quickstart'' avoiding any optional processing
like calling
.BR pmlogger_daily (1)
to perform archive compression tasks.
.TP 5
\fB\-s\fR, \fB\-\-stop\fR
Use of this option provides the reverse
.B pmlogger_check
functionality, allowing the set of
.B pmlogger
processes to be cleanly shutdown.
.TP 5
\fB\-T\fR, \fB\-\-terse\fR
This option to
.B pmlogger_check
produces less verbose output than the default.
This is most suitable for a
.B pmlogger
\&``farm'' where many instances of
.B pmlogger
are expected to be running.
.TP 5
\fB\-V\fR, \fB\-\-verbose\fR
The
.B \-V
option enables verbose tracing.
By default
.B pmlogger_check
generates no output unless some error or warning
condition is encountered.
A second
.B \-V
increases the verbosity.
Using
.B \-N
in conjunction with
.B \-V
maximizes the diagnostic capabilities for debugging.
.TP 5
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH CONFIGURATION
Refer to
.BR pmlogger.control (5)
for a description of the control file(s) that are used to
control which
.B pmlogger
instances and which archives are managed by
.B pmlogger_check
and
.BR pmlogger_daily (1).
.PP
The
.BR pmlogctl (1)
utility may invoke
.B pmlogger_check
using the
.BR sudo (1)
command to run it under the $PCP_USER ``pcp'' account.
If
.B sudo
is configured with the non-default
.I requiretty
option (see below),
.B pmlogger_check
may fail to run due to not having a tty configured.
This issue can be resolved by adding a second line
(expand $PCP_BINADM_DIR according to your platform)
to the
.I /etc/sudoers
configuration file as follows:
.P
.ft CR
.nf
.in +0.5i
Defaults requiretty
Defaults!$PCP_BINADM_DIR/pmlogger_check !requiretty
.in
.fi
.ft 1
.P
Note that the unprivileged PCP account under which these
commands run uses
.I /sbin/nologin
as the shell, so the
.I requiretty
option is ineffective here and safe to disable in this way.
.SH FILES
.TP 5
.I $PCP_VAR_DIR/config/pmlogger/config.default
default
.B pmlogger
configuration file location for the local primary logger, typically
generated automatically by
.BR pmlogconf (1).
.TP 5
.I $PCP_ARCHIVE_DIR/<hostname>
default location for archives of performance information collected from the host
.I hostname
.TP 5
.I $PCP_ARCHIVE_DIR/<hostname>/lock
transient lock file to guarantee mutual exclusion during
.B pmlogger
administration for the host
.I hostname
\- if present, can be safely removed if neither
.BR pmlogger_daily (1)
nor
.B pmlogger_check
are running
.TP 5
.I $PCP_ARCHIVE_DIR/<hostname>/Latest
PCP archive folio created by
.BR mkaf (1)
for the most recently launched archive containing performance metrics from
the host
.I hostname
.TP 5
.I $PCP_LOG_DIR/NOTICES
PCP ``notices'' file used by
.BR pmie (1)
and friends
.TP 5
.I $PCP_LOG_DIR/pmlogger/pmlogger_check.log
if the previous execution of
.B pmlogger_check
produced any output it is saved here.
The normal case is no output in which case the file does not exist.
.TP 5
.I $PCP_ARCHIVE_DIR/<hostname>/SaveLogs
if this directory exists,
then the log file from the
.B \-l
argument
of a newly launched
.BR pmlogger (1)
for
.I hostname
will be linked into this directory with the name
.IB archive .log
where
.I archive
is the basename of the associated
.BR pmlogger (1)
PCP archive files.
This allows the log file to be inspected at a later time, even if
several
.BR pmlogger (1)
instances for
.I hostname
have been launched in the interim.
Because the PCP archive management tools run under
the $PCP_USER account ``pcp'',
.I $PCP_ARCHIVE_DIR/<hostname>/SaveLogs
typically needs to be owned by the user ``pcp''.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.PP
The default behaviour, when
.BR pmlogger (1)
configuration comes from
.BR pmlogconf (1),
is to regenerate the configuration file and check for
changes whenever
.BR pmlogger (1)
is started from
.BR pmlogger_check.
If the PMDA configuration is stable, this is not necessary,
and setting
.B $PMLOGGER_CHECK_SKIP_LOGCONF
to
.B yes
disables the regeneration and checking.
.SH SEE ALSO
.BR mkaf (1),
.BR PCPIntro (1),
.BR pmie (1),
.BR pmlc (1),
.BR pmlogconf (1),
.BR pmlogctl (1),
.BR pmlogger (1),
.BR pmlogger_daily (1),
.BR pmlogger_daily_report (1),
.BR sudo (1),
.BR systemd (1),
.BR pmlogger.control (5)
and
.BR cron (8).