'\"macro stdmacro
.\"
.\" Copyright (c) 2013-2016,2020 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 PMREPCONF 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmrepconf\f1 \- create/edit a pmrep configuration file
.SH SYNOPSIS
\f3pmrepconf\f1
[\f3\-crv?\f1]
[\f3\-d\f2 groupsdir\f1]
[\f3\-g\f2 grouptag\f1]
[\f3\-o\f2 option\f1]
[\f3\-h\f2 host\f1]
\f2configfile\f1
.SH DESCRIPTION
.B pmrepconf
may be used to create and modify a generic configuration file for
.BR pmrep (1)
and related utilities in the
.BR pmrep.conf (5)
format.
.PP
If
.I configfile
does not exist,
.B pmrepconf
will create a generic configuration file with a
set of discovered metrics in a [metrics] section.
.PP
Once created,
.I configfile
may be used with the
.B \-c
option to
.BR pmrep (1)
and related utilities such as
.BR pcp2elasticsearch (2)
and
.BR pcp2spark (2).
.PP
If
.I configfile
does exist,
.B pmrepconf
will prompt for input from the user to enable or disable groups
of related performance metrics.
.PP
Group selection requires a simple
.B y
(yes)
or
.B n
(no) response to the prompt
.BR "Log this group?" .
.PP
Other responses at this point may be used to select
additional control functions as follows:
.IP \fBm\fP 10n
Report the names of the metrics in the current group.
.IP \fBq\fP 10n
Finish with group selection (quit) and make no further changes to
this group or any subsequent group.
.IP \fB/\fIpattern\fP 10n
Make no change to this group but search for a group containing
.I pattern
in the description of the group or the names
of the associated metrics.
.PP
When run from automated setup processes, the
.B \-c
option is used to indicate that
.I pmrepconf
is in auto-create mode and no interactive dialog takes place.
The output
.I configfile
has an additional comment message
and timestamp indicating this fact, so that it can be
identified and subsequently updated using
.B \-c
again.
This option is not appropriate for interactive use of the tool.
.PP
More verbose output may be enabled with the
.B \-v
option.
.SH SETUP GROUP FILES
When an initial
.I configfile
is created, the default specifications come from a set of group
files below the
.I groupsdir
specified with the
.B \-d
option (the default
.I groupsdir
is
.B $PCP_VAR_DIR/config/pmlogconf
which is most commonly correct, so the
.B \-d
option is rarely used in practice).
.PP
The directory structure and format of files below
.I groupsdir
is shared with the
.B pmlogconf (1)
utility, and described in detail on that manual page.
When used by
.B pmrepconf
all interval settings are ignored.
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-c\fR
Enable non-interactive, auto-create mode.
.TP
\fB\-d\fR \fIgroupdir\fR, \fB\-\-groups\fR=\fIgroupdir\fR
Specify the path to the \fIgroupsdir\fP directory.
.TP
\fB\-g\fR \fIgrouptag\fR, \fB\-\-group\fR=\fIgrouptag\fR
Query logging state for the specific group named \fIgrouptag\fP.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
Performance metrics source is
.BR pmcd (1)
on
.IR host ,
rather than on the default localhost.
.TP
\fB\-o\fR \fIoption\fR, \fB\-\-option\fR=\fIoption\fR
Specify an option to be added to the [option] secton of the
generated
.BR pmrep.conf (5)
file.
This command line option can be presented multiple times in
order to added multiple lines in the [option] section.
.TP
\fB\-r\fR, \fB\-\-reprobe\fR
Reconsider every group for inclusion in the \fIconfigfile\fP.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Enable verbose mode.
.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).
.PP
.B pmrepconf
overrides any
.B $PCP_DERIVED_CONFIG
environment variable to an empty string, for performance reasons.
.PP
.B pmrepconf
honours the
.B $PMCD_WAIT_TIMEOUT
environment variable when probing and creating new
.B pmrep
configuration files.
It uses a default timeout value of 10 seconds for this, in the
absence of an environment setting.
.SH SEE ALSO
.BR pcp2elasticsearch (1),
.BR pcp2spark (1),
.BR pmcd (1),
.BR pmlogconf (1),
.BR pmrep (1),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR pmrep.conf (5)