Ubuntu Manpage: pmlogger_check - administration of Performance Co-Pilot archive files

NAME

       pmlogger_check - administration of Performance Co-Pilot archive files

SYNOPSIS

       $PCP_BINADM_DIR/pmlogger_check [-CNPpqsTV?]  [-c control] [-l logfile]

DESCRIPTION

       pmlogger_check  and  the  related  pmlogger_daily(1)  tools  along  with  associated  control  files (see
       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 PCPIntro(1)) infrastructure.

       pmlogger_check  may  be  run  at  any  time  of  the  day  and is intended to check that a desired set of
       pmlogger(1) processes are running.  If not, it (re-)starts any missing  logger  processes.   By  default,
       pmlogger_check  also calls pmlogger_daily(1) with a -K option to execute any required archive compression
       tasks.

OPTIONS

-C This option causes pmlogger_check to query the system service runlevel information for pmlogger, and
use that to determine whether to start processes or not.

-c control, --control=control
Both pmlogger_check and pmlogger_daily(1) are controlled by PCP logger control file(s) that
specifies the pmlogger instances to be managed. The default control file is
$PCP_PMLOGGERCONTROL_PATH but an alternate may be specified using the -c option. If the directory
$PCP_PMLOGGERCONTROL_PATH.d (or control.d from the -c option) exists, then the contents of any
additional control files therein will be appended to the main control file (which must exist).

-l file, --logfile=file
In order to ensure that mail is not unintentionally sent when these scripts are run from cron(8) or
systemd(1) diagnostics are always sent to log files. By default, this file is
$PCP_LOG_DIR/pmlogger/pmlogger_check.log but this can be changed using the -l option. If this log
file already exists when the script starts, it will be renamed with a .prev suffix (overwriting any
log file saved earlier) before diagnostics are generated to the log file. The -l and -t options
cannot be used together.

-N, --showme
This option enables a ``show me'' mode, where the actions are echoed, but not executed, in the style
of ``make -n''. Using -N in conjunction with -V maximizes the diagnostic capabilities for
debugging.

-P, --only-primary
If this option is specified for pmlogger_check then only the primary logger entry in the control
files will be processed. This is the logical opposite of the -p option described above and is
intended for use by RC scripts that start only the primary logger, such as the pmlogger.service
unit. The -p and -P options are mutually exclusive.

-p, --skip-primary
If this option is specified for pmlogger_check then any line from the control files for the primary
pmlogger will be ignored. This option is intended for environments where some system daemon, like
systemd(1), is responsible for controlling (starting, stopping, restarting, etc.) the primary
pmlogger.

-q, --quick
If this option is specified for pmlogger_check then the script will ``quickstart'' avoiding any
optional processing like calling pmlogger_daily(1) to perform archive compression tasks.

-s, --stop
Use of this option provides the reverse pmlogger_check functionality, allowing the set of pmlogger
processes to be cleanly shutdown.

-T, --terse
This option to pmlogger_check produces less verbose output than the default. This is most suitable
for a pmlogger ``farm'' where many instances of pmlogger are expected to be running.

-V, --verbose
The -V option enables verbose tracing. By default pmlogger_check generates no output unless some
error or warning condition is encountered. A second -V increases the verbosity. Using -N in
conjunction with -V maximizes the diagnostic capabilities for debugging.

-?, --help
Display usage message and exit.

CONFIGURATION

       Refer  to  pmlogger.control(5)  for  a  description of the control file(s) that are used to control which
       pmlogger instances and which archives are managed by pmlogger_check and pmlogger_daily(1).

       The pmlogctl(1) utility may invoke pmlogger_check using the sudo(1) command to run it under the $PCP_USER
       ``pcp''  account.   If  sudo  is  configured  with  the  non-default  requiretty  option   (see   below),
       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 /etc/sudoers configuration  file
       as follows:

            Defaults requiretty
            Defaults!$PCP_BINADM_DIR/pmlogger_check !requiretty

       Note that the unprivileged PCP account under which these commands run uses /sbin/nologin as the shell, so
       the requiretty option is ineffective here and safe to disable in this way.

FILES

       $PCP_VAR_DIR/config/pmlogger/config.default
            default  pmlogger  configuration  file  location  for  the local primary logger, typically generated
            automatically by pmlogconf(1).

       $PCP_ARCHIVE_DIR/<hostname>
            default location for archives of performance information collected from the host hostname

       $PCP_ARCHIVE_DIR/<hostname>/lock
            transient lock file to guarantee mutual  exclusion  during  pmlogger  administration  for  the  host
            hostname  -  if  present,  can be safely removed if neither pmlogger_daily(1) nor pmlogger_check are
            running

       $PCP_ARCHIVE_DIR/<hostname>/Latest
            PCP archive folio created by mkaf(1) for the most recently launched archive  containing  performance
            metrics from the host hostname

       $PCP_LOG_DIR/NOTICES
            PCP ``notices'' file used by pmie(1) and friends

       $PCP_LOG_DIR/pmlogger/pmlogger_check.log
            if  the  previous execution of pmlogger_check produced any output it is saved here.  The normal case
            is no output in which case the file does not exist.

       $PCP_ARCHIVE_DIR/SaveLogs
            if this directory exists, then the log file from the -l argument for pmlogger_check will be saved in
            this directory with the name of the format <date>-pmlogger_check.log.<pid> This allows the log  file
            to be inspected at a later time, even if several pmlogger_check executions have been launched in the
            interim.   Because  the  PCP  archive  management  tools  run  under  the $PCP_USER account ``pcp'',
            $PCP_ARCHIVE_DIR/SaveLogs typically needs to be owned by the user ``pcp''.

       $PCP_ARCHIVE_DIR/<hostname>/SaveLogs
             if this directory exists, then the log file from the -l argument of a  newly  launched  pmlogger(1)
             for  hostname  will  be  saved  in  this  directory  with the name archive.log where archive is the
             basename of the associated pmlogger(1) PCP archive files.  This allows the log file to be inspected
             at a later time, even if several pmlogger(1) instances for  hostname  have  been  launched  in  the
             interim.   Because  the  PCP  archive  management  tools  run  under the $PCP_USER account ``pcp'',
             $PCP_ARCHIVE_DIR/<hostname>/SaveLogs typically needs to be owned by the user ``pcp''.

PCP ENVIRONMENT

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

       The default behaviour, when pmlogger(1) configuration comes  from  pmlogconf(1),  is  to  regenerate  the
       configuration  file  and  check  for changes whenever pmlogger(1) is started from pmlogger_check.  If the
       PMDA configuration is stable, this is not necessary,  and  setting  $PMLOGGER_CHECK_SKIP_LOGCONF  to  yes
       disables the regeneration and checking.