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/<hostname>/SaveLogs
            if this directory exists, then the log file from the -l argument of a newly  launched
            pmlogger(1) for hostname will be linked into 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.