'\"macro stdmacro
.\"
.\" Copyright (c) 2018-2019 Red Hat.
.\"
.\" 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_DAILY_REPORT 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogger_daily_report\f1 \- write Performance Co-Pilot daily summary reports
.SH SYNOPSIS
.B $PCP_BINADM_DIR/pmlogger_daily_report
[\f3\-ApV?\f1]
[\f3\-a\f1 \f2archivefile\f1]
[\f3\-f\f1 \f2outputfile\f1]
[\f3\-h\f1 \f2hostname\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-o\f1 \f2directory\f1]
[\f3\-t\f1 \f2interval\f1]
.SH DESCRIPTION
.B pmlogger_daily_report
and the associated
.BR systemd (1)
services
write daily performance summary reports, much like those produced by
.BR sadc (1)
and the
.BR sa2 (8)
utility.
.PP
All of the command line arguments are optional and intended to be self
explanatory.
The service is not enabled by default.
If the service is enabled and no arguments are specified,
.B pmlogger_daily_report
will be run by
.BR systemd
at 2am each morning and write a performance summary report named
.BI sar XX
(where
.I XX
is yesterdays day-of-the-month, wrapping to the previous month
if today is the 1st).
The
.I outputfile
may be changed with the
.B \-f
option.
The report will be written to the
.I $PCP_LOG_DIR/sa
directory by default, but this may be changed with the
.B \-o
option to a different
.IR directory .
.PP
Note that there are suffciently flexible command line options for
.B pmlogger_daily_report
to be used to read any
.B archivefile
and write the report to any output directory.
.PP
If the
.B \-a
option is not given, the default input
.IR archivefile
is
.IR $PCP_ARCHIVE_DIR/HOSTNAME/YYYYMMDD ,
where
.I HOSTNAME
defaults to the local hostname (unless changed with the
.B \-h
option) and
.I YYYYMMDD
is the base name of yesterdays merged archive, as produced by
.BR pmlogger (1)
and the
.BR pmlogger_daily (1)
scripts.
If
.I archivefile
is a directory, then
.B pmlogger_daily_report
will use all PCP archives found in that directory
to write the report (this is known as multi-archive mode,
and may be considerably slower than specifying a single
archive as the input).
.PP
The reports themselves are created by the
.BR pmrep (1)
utility using its default configuration file, see
.BR pmrep.conf (5).
The
.BR pmrep (1)
configuration entries used to write the reports is currently hardwired
into the
.B pmlogger_daily_report
script.
.PP
Finally, the input archives must contain sufficient metrics as needed by
.BR pmrep (1)
to write the report.
On platforms that support it, the
.I pcp-zeroconf
package configures PCP logging as required for this \- hence
.B pmlogger_daily_report
should be used with the
.BR pmlogger (1)
configuration that is set up by
.BR pcp-zeroconf .
As the name suggests,
.BR pcp-zeroconf
requires no additional configuration after installation in order to
capture the required archives needed by
.BR pmlogger_daily_report .
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-a\fR \fIarchive\fR
Specifies an alternate input
.I archive
file basename or directory path.
.TP
\fB\-A\fR
Use the start and end times of input archive for the report, as
opposed to the default behaviour of 24 hours from midnight yesterday.
.TP
\fB\-f\fR \fIfilename\fR
Specifies an alternate output
.IR filename .
\fB\-h\fR \fIhostname\fR
Specifies an alternateA
.I hostname
to use within the default input archive file path.
.TP
\fB\-l\fR \fIfile\fR, \fB\-\-logfile\fR=\fIfile\fR
In order to ensure that mail is not unintentionally sent when this
script is run from
.BR systemd (1)
diagnostics are always sent to a log
.IR file .
By default, this file is
.B $PCP_LOG_DIR/pmlogger/pmlogger_daily_report.log
but this can be changed using the
.B \-l
option.
If this log 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.
.TP
\fB\-p\fR
If this option is specified
then the status of the daily processing is polled and if the
report has not been done in the last 24 hours then it is done now.
The intent is to have
.B pmlogger_daily_report
called regularly with the
.B \-p
option (at 30 mins past the hour, every hour in the default
.BR systemd (1)
setup) to ensure daily processing happens as soon as possible
if it was missed at the regularly scheduled time (2am by default),
for example if the system was down or suspended at that time.
With this option,
.B pmlogger_daily_report
simply exits if the previous day's processing has already been
done.
.TP
\fB\-t\fR \fIinterval\fR
Specifies the sampling
.I interval
used when generating the report, in the format described in
.BR PCPIntro (1).
The default is every 10 minutes.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
The output from the execution of the script may be extended using
this option which enables verbose tracing of activity.
By default the script generates no log output unless some error or
warning condition is encountered.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.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).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmlogger_daily (1),
.BR pmlogger (1),
.BR pmrep (1),
.BR sadc (1),
.BR systemd (1)
and
.BR sa2 (8).