# pmlogger_check

## 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.
    


* * *