diff options
Diffstat (limited to 'man/man1/pmlogger_check.1')
| -rw-r--r-- | man/man1/pmlogger_check.1 | 528 |
1 files changed, 528 insertions, 0 deletions
diff --git a/man/man1/pmlogger_check.1 b/man/man1/pmlogger_check.1 new file mode 100644 index 0000000..4554b92 --- /dev/null +++ b/man/man1/pmlogger_check.1 @@ -0,0 +1,528 @@ +'\"macro stdmacro +.\" +.\" Copyright (c) 2013-2014 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, +\f3pmlogger_daily\f1, +\f3pmlogger_merge\f1 \- administration of Performance Co-Pilot archive log files +.SH SYNOPSIS +.B $PCP_BINADM_DIR/pmlogger_check +[\f3\-CNsTV\f1] +[\f3\-c\f1 \f2control\f1] +.br +.B $PCP_BINADM_DIR/pmlogger_daily +[\f3\-NorV\f1] +[\f3\-c\f1 \f2control\f1] +[\f3\-k\f1 \f2discard\f1] +[\f3\-m\f1 \f2addresses\f1] +[\f3\-s\f1 \f2size\f1] +[\f3\-t\f1 \f2want\f1] +[\f3\-x\f1 \f2compress\f1] +[\f3\-X\f1 \f2program\f1] +[\f3\-Y\f1 \f2regex\f1] +.br +.B $PCP_BINADM_DIR/pmlogger_merge +[\f3\-fNV\f1] +[\f2input-basename\f1 ... \f2output-name\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 +Performance Co-Pilot (see +.BR PCPintro (1)) +archive log files. +.PP +The +.B \-V +option that is common to all the scipts will enable verbose tracing and +reporting. +By default the scripts generate no output unless some error or warning condition is +encountered. +.PP +The common +.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. +.PP +.B pmlogger_daily +is intended to be run once per day, preferably in the early morning, as +soon after midnight as practicable. Its task is to aggregate and rotate +one or more sets of PCP archives. +After some period, old PCP archives 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 archives beyond the current one, and +.B forever +to prevent any archives being discarded. +.PP +Archive data files can optionally be compressed after some period +to conserve disk space. This is particularly useful for large numbers of +.B pmlogger +processes under the control of +.BR pmlogger_check . +By default no compression is done. +The +.B \-x +option enables compression and +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 +To accommodate the evolution of PMDAs and changes in production +logging environments, +.B pmlogger_daily +is integrated with +.BR pmlogrewrite (1) +to allow optional and automatic rewriting of archives before merging. +If there are global rewriting rules to be applied across all archives +mentioned in the control file, then create the directory +.B $PCP_SYSCONF_DIR/pmlogrewrite +and place any +.BR pmlogrewrite (1) +rewriting rules in this directory. +For rewriting rules that are specific to only one family of archives, +use the directory name from the control file (the +.I fourth +field) and create a file, or a directory, or a symbolic link named +.B pmlogrewrite +within this directory +and place the required rewriting rule(s) in the +.B pmlogrewrite +file or in files +within the +.B pmlogrewrite +subdirectory. +.B pmlogger_daily +will choose rewriting rules from the archive directory if they +exist, else rewriting rules from +.B $PCP_SYSCONF_DIR/pmlogrewrite +if that directory exists, else no rewriting is attempted. +.PP +The +.B \-r +command line option acts as an over-ride and +prevents all archive rewriting with +.BR pmlogrewrite (1) +independent of the presence of any rewriting rule files or directories. +.PP +By default all possible archives will be merged. The +.B \-o +option reinstates the old behaviour in which only yesterday's archives +will be considered as merge candidates. +.PP +In the special case where only a single input archive +needs to be merged, +.BR pmlogmv (1) +is used to rename the archive, rather than copy the input archive +using +.BR pmlogger_merge . +.PP +The +.B \-M +option may be used to disable archive merging (or renaming) and rewriting +(\c +.B \-M +implies +.BR \-r ). +This is most useful in cases where the archives are being incrementally +copied to a remote repository, e.g. using +.BR rsync (1). +Merging, renaming and rewriting all risk an increase in the synchronization +load, especially immediately after +.B pmlogger_daily +has run, so +.B \-M +may be useful in these cases. +.PP +To assist with debugging or diagnosing intermittent failures the +.B \-t +option may be used. This will turn on very verbose tracing (\c +.BR \-VV ) +and capture the trace output in a file named +.BI $PCP_LOG_DIR/pmlogger/daily. datestamp .trace, +where +.I datestamp +is the time +.B pmlogger_daily +was run in the format YYYYMMDD.HH.MM. +In addition, the +.I want +argument will ensure that trace files created with +.B \-t +will be kept for +.I want +days and then discarded. +.PP +In addition, if the +PCP ``notices'' file (\c +.BR $PCP_LOG_DIR/NOTICES ) +is larger than 20480 bytes, +.B pmlogger_daily +will rename the file with a ``.old'' suffix, and start +a new ``notices'' file. +The rotate threshold may be changed from 20480 to +.I size +bytes using the +.B \-s +option. +.PP +Use of the +.B \-m +option causes +.B pmlogger_daily +to construct a summary of the ``notices'' file entries which were +generated in the last 24 hours, and e-mail that summary to the set of +space-separated +.IR addresses . +This daily summary is stored in the file +.BR $PCP_LOG_DIR/NOTICES.daily , +which will be empty when no new ``notices'' entries were made in the previous +24 hour period. +.PP +The script +.B $PCP_BINADM_DIR/pmlogger_daily +could be copied and modified to implement a site-specific procedure for +end-of-week and/or end-of-month management for a set of PCP archives. +.PP +.B pmlogger_check +may be run at any time, and is intended to check that the desired set +of +.BR pmlogger (1) +processes are running, and if not to re-launch any failed loggers. +Use of the +.B \-s +option provides the reverse functionality, allowing the set of +.B pmlogger +processes to be cleanly shutdown. +Use of the +.B \-C +option queries the system service runlevel information for +.BR pmlogger , +and uses that to determine whether to start or stop processes. +.PP +The +.B \-T +option provides a terser form of output for +.B pmlogger_check +that is most suitable for a +.I pmlogger +\&``farm'' where many instances of +.I pmlogger +are expected to be running. +.PP +.B pmlogger_merge +is a wrapper script for +.BR pmlogextract (1) +that merges all of the archive logs matching the +.I input-basename +arguments, and creates a new archive using +.I output-name +as the base name for the physical files that constitute +an archive log. +The +.I input-basename +arguments may contain meta characters in the style of +.BR sh (1). +If specified, the +.B \-f +option causes all of the input files to be removed once the output +archive has been created. +.PP +.B pmlogger_merge +is used by +.BR pmlogger_daily . +.PP +Both +.B pmlogger_daily +and +.B pmlogger_check +are controlled by a PCP logger control file +that specifies the +.B pmlogger +instances to be managed. The default control file is +.BR $PCP_PMLOGGERCONTROL_PATH , +but an alternate may be specified using the +.B \-c +option. +.PP +The control file should be customized according to the following rules +that define for the current version (1.1) +of the control file format. +.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 scripts, e.g. +.br +.in +4n +.ft CW +.nf +$ PMCD_CONNECT_TIMEOUT=20 +.fi +.ft R +.in -4n +.br +.BR Warning : +The +.B $PCP_PMLOGGERCONTROL_PATH +file must not be writable by any user other than root. +.br +.IP 3. +There +.B must +be a version line of the form: +.br +.in +4n +.ft CW +.nf +$ version=1.1 +.fi +.ft R +.in -4n +.IP 4. +There should be one line in the control file +for each +.B pmlogger +instance of the form: + +.in +4n +.ft CW +.nf +\f2host\f1 \f3y\f1|\f3n\f1 \f3y\f1|\f3n\f1 \f2directory\f1 \f2args\f1 +.fi +.ft R +.in -4n + +.IP 5. +Fields within a line of the control file +are separated by one or more spaces or tabs. +.IP 6. +The +.I first +field is the name of the host that is the source of the +performance metrics for this +.B pmlogger +instance. +.IP 7. +The +.I second +field indicates if this is a +.I primary +.B pmlogger +instance (\c +.BR y ) +or not (\c +.BR n ). +Since the primary logger must run on the local host, and there may be +at most one primary logger for a particular host, this field can be +.B y +for at most one +.B pmlogger +instance, in which case the host name must be the name of the local host. +.IP 8. +The +.I third +field indicates if this +.B pmlogger +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 9. +The +.I fourth +field is a directory name. All files +associated with this +.B pmlogger +instance will be created in this directory, +and this will be the current directory for the execution of +any programs required in the maintenance of those archives. +A useful convention is that primary logger archives for the local host +with hostname +.I myhost +are maintained in the directory +.BI $PCP_LOG_DIR/pmlogger/ myhost +(this is where the default +.B pmlogger +start-up script in +.B $PCP_RC_DIR/pcp +will create the archives), while archives for the remote host +.I mumble +are maintained in +.BI $PCP_LOG_DIR/pmlogger/ mumble\fR. +.IP 10. +All other fields are interpreted as arguments to be passed to +.BR pmlogger (1) +and/or +.BR pmnewlog (1). +Most typically this would be the +.B \-c +option. +.PD +.PP +The following sample control lines specify a primary logger +on the local host (\c +.IR bozo ), +and a non-primary logger to collect and log +performance metrics from the host +.IR boing . +.PP +.nf +.ft CW +$version=1.1 +bozo y n $PCP_LOG_DIR/pmlogger/bozo \-c config.default +boing n n $PCP_LOG_DIR/pmlogger/boing \-c ./pmlogger.config +.ft 1 +.fi +.PP +Typical +.BR crontab (5) +entries for periodic execution of +.B pmlogger_daily +and +.B pmlogger_check +are given in +.BR $PCP_SYSCONF_DIR/pmlogger/crontab +(unless installed by default in +.I /etc/cron.d +already) +and shown below. +.PP +.nf +.ft CW +# daily processing of archive logs +14 0 * * * $PCP_BINADM_DIR/pmlogger_daily +# every 30 minutes, check pmlogger instances are running +25,55 * * * * $PCP_BINADM_DIR/pmlogger_check +.ft 1 +.fi +.PP +The output from the +.BR cron (1) +execution of the scripts may be extended using the +.B \-V +option. + +.SH FILES +.TP 10 +.B $PCP_PMLOGGERCONTROL_PATH +the PCP logger control file +.br +.BR Warning : +this file must not be writable by any user other than root. +.TP +.B $PCP_SYSCONF_DIR/pmlogger/crontab +sample crontab for automated script execution by $PCP_USER (or root). +Exists only if the platform does not support the /etc/cron.d mechanism. +.TP +.B $PCP_SYSCONF_DIR/pmlogger/config.default +default +.B pmlogger +configuration file location for the local primary logger, typically +generated automatically by +.BR pmlogconf (1). +.TP +.BI $PCP_LOG_DIR/pmlogger/ hostname +default location for archives of performance information collected from the host +.I hostname +.TP +.BI $PCP_LOG_DIR/pmlogger/ 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 +.B pmlogger_daily +nor +.B pmlogger_check +are running +.TP +.BI $PCP_LOG_DIR/pmlogger/ 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 +.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 pmlc (1), +.BR pmlogconf (1), +.BR pmlogger (1), +.BR pmlogextract (1), +.BR pmlogmv (1), +.BR pmlogrewrite (1), +.BR pmnewlog (1), +.BR pmsocks (1), +.BR xz (1) +and +.BR cron (8). |