'\"macro stdmacro
.\"
.\" Copyright (C) 2015-2021 Marko Myllynen <myllynen@redhat.com>
.\"
.\" 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 PMREP.CONF 5 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmrep.conf\f1 \- pmrep configuration file
.SH DESCRIPTION
.B pmrep
is a customizable performance metrics reporting tool.
Any available performance metric, live or archived, system and/or
application, can be selected for reporting using one of the available
output alternatives together with applicable formatting options.
.PP
The metrics of interest are named in the
.I metricspec
argument(s) on the
.B pmrep
command line.
These metricspecs define individual metrics or pre-defined performance
metricsets to be read from configuration files described below.
For command line argument details see
.BR pmrep (1).
.PP
The
.B pmrep.conf
configuration file allows for setting default runtime values and
defining any number of custom
.I metricsets
for
.BR pmrep .
A metricset is a user-defined arbitrary set of performance metrics.
This allows users to create specifically crafted metricsets
particularly relevant for their application or environment.
Instead of being dependent on what existing tools provide or collecting
the needed data with several disjoint utilities users can define custom
metricsets by merely editing
.BR pmrep.conf .
See below for the \fImetricset\fP specification.
.PP
In case \fBpmrep\fP configuration files are read from a directory then
values for the \fB[options]\fP and \fB[global]\fP sections will be
combined from each file where defined.
The last definition of a directive wins,
meaning the last definition will be used in case defined multiple times.
However, custom \fImetricset\fP sections will not be combined,
only the last definition found will be used for reporting.
.PP
Options via environment values (see
.BR pmGetOptions (3))
override the corresponding built-in default values (if any).
Configuration file options override the corresponding
environment variables (if any).
Command line options override the corresponding configuration
file options (if any).
.SH FILE FORMAT
The file has an ini-style syntax and consists of sections and settings.
A section begins with the name of the section in square brackets and
continues until the next section begins.
An example section with two settings follows:
.sp 1
.RS 4
.nf
[\fIsection\fP]
\fIkey\fP = \fIvalue\fP
\fIkey2\fP = \fIvalue2\fP
.fi
.RE
.PP
The supported data types for values are string, integer, and boolean.
Values should not to be quoted expect when the value consists solely
of whitespace (i.e., a whitespace-only column separator).
.PP
A line comment starts with a hash sign (``#'') or a semicolon (``;'').
Inline comments are not supported.
.PP
.B pmrep.conf
must be readable by the user invoking
.BR pmrep .
.PP
Any option described below with a corresponding command line
option contains additional functional description in
.BR pmrep (1).
.SH SPECIAL SECTIONS
.SS The [options] section
The
.B [options]
section is read every time
.B pmrep
is run and it defines the default runtime options.
These options may be overridden by metricspec specific options
or by command line options.
Metrics are not allowed in this section.
.PP
\fBAllowed settings\fP
.PP
version (integer)
.RS 4
Indicates the configuration file version.
Defaults to \fB1\fP.
The only currently supported value is \fB1\fP.
.RE
.PP
source (string)
.RS 4
Indicates the source for metrics.
Interpreted as a PCP archive if the value contains a slash (``/'').
If set to the special character ``@'', local DSO PMDA context is used.
Otherwise interpreted as a hostname.
Corresponding command line paraters are \fB\-a\fP, \fB\-h\fP,
and \fB\-L\fP.
Defaults to \fBlocal:\fP (see
.BR PCPIntro (1)).
.RE
.PP
output (string)
.RS 4
Indicates the output target.
Corresponding command line option is \fB\-o\fP.
For supported output targets, see
.BR pmrep (1).
Defaults to \fBstdout\fP.
.RE
.PP
speclocal (string)
.RS 4
Indicates the local DSO PMDAs to be made available when using the local
DSO PMDA context.
Corresponding command line option is \fB\-K\fP.
For syntax description, see
.BR pmSpecLocalPMDA (3).
Use a semicolon (``;'') to separate more than one \fIspec\fP.
Undefined by default.
.RE
.PP
derived (string)
.RS 4
Derived metric specifications.
Corresponding command line option is \fB\-e\fP.
For syntax description, see
.BR pmrep (1).
Undefined by default.
.RE
.PP
daemonize (boolean)
.RS 4
Indicates whether to daemonize on startup.
Corresponding command line option is \fB\-\-daemonize\fP.
Defaults to \fBno\fP.
.RE
.PP
header (boolean)
.RS 4
Indicates whether to print headers.
Corresponding command line option is \fB\-H\fP.
Defaults to \fByes\fP.
.RE
.PP
instinfo (boolean)
.RS 4
Indicates whether to include instance information as part of headers.
Corresponding command line option is \fB\-\-no\-inst\-info\fP.
Defaults to \fByes\fP.
.RE
.PP
unitinfo (boolean)
.RS 4
Indicates whether to include unit information as part of headers.
Corresponding command line option is \fB\-U\fP.
Defaults to \fByes\fP.
.RE
.PP
globals (boolean)
.RS 4
Indicates whether to include metrics from the \fB[global]\fP section
(see below) for reporting.
Corresponding command line option is \fB\-G\fP.
Defaults to \fByes\fP.
.RE
.PP
timestamp (boolean)
.RS 4
Indicates whether to print the timestamp.
Corresponding command line option is \fB\-p\fP.
Defaults to \fBno\fP.
.RE
.PP
samples (integer)
.RS 4
Indicates the number of samples to print.
Corresponding command line option is \fB\-s\fP.
Undefined by default (meaning unlimited number of samples if not
limited by other options).
.RE
.PP
interval (string)
.RS 4
Indicates the interval between samples.
Corresponding command line option is \fB\-o\fP.
Follows the time syntax described in
.BR PCPIntro (1).
Defaults to \fB1s\fP.
.RE
.PP
delay (boolean)
.RS 4
Indicates whether to pause between samples when replaying from an
archive rather than replaying at full speed.
Corresponding command line option is \fB\-d\fP.
Defaults to \fBno\fP.
.RE
.PP
type (string)
.RS 4
Indicates whether to output raw metric values by disabling all rate
conversions or convert cumulative counters to rates (default).
Corresponding command line option is \fB\-r\fP.
Allowed values are \fBdefault\fP or \fBraw\fP.
.RE
.PP
type_prefer (string)
.RS 4
As \fBtype\fP but does not override possible per-metric type
specifications.
Corresponding command line option is \fB\-R\fP.
Allowed values are \fBdefault\fP or \fBraw\fP.
.RE
.PP
ignore_incompat (boolean)
.RS 4
Indicates that incompatible metrics are to be ignored.
Corresponding command line option is \fB\-I\fP.
Defaults to \fBno\fP.
.RE
.PP
ignore_unknown (boolean)
.RS 4
Indicates that unknown metrics are to be ignored.
Corresponding command line option is \fB\-5\fP.
Defaults to \fBno\fP.
.RE
.PP
names_change (string)
.RS 4
Indicates the action to take on PMNS changes during sampling.
Corresponding command line option is \fB\-4\fP.
Defaults to \fBignore\fP.
.RE
.PP
instances (string)
.RS 4
Indicates the instances to be reported.
Corresponding command line option is \fB\-i\fP.
Undefined (all instances are reported) by default.
.RE
.PP
live_filter (boolean)
.RS 4
Indicates that live filtering should be enabled.
Corresponding command line option is \fB\-j\fP.
Defaults to \fBno\fP.
.RE
.PP
rank (integer)
.RS 4
Indicates the value to be used for ranking instances.
Corresponding command line option is \fB\-J\fP.
Undefined (all instances are reported) by default.
.RE
.PP
overall_rank (boolean)
.RS 4
Indicates that overall ranking should be performed.
Corresponding command line option is \fB\-2\fP.
Defaults to \fBno\fP.
.RE
.PP
overall_rank_alt (boolean)
.RS 4
Indicates that overall ranking with alternative output format
should be performed.
Corresponding command line option is \fB\-3\fP.
Defaults to \fBno\fP.
.RE
.PP
limit_filter (integer)
.RS 4
Indicates the value to be used with limit filtering.
Corresponding command line option is \fB\-8\fP.
Undefined (all instances are reported) by default.
.RE
.PP
limit_filter_force (integer)
.RS 4
As \fBlimit_filter\fP but overrides possible possible per-metric
specifications.
Corresponding command line option is \fB\-9\fP.
Undefined (all instances are reported) by default.
.RE
.PP
invert_filter (boolean)
.RS 4
Indicates that invert filtering should be performed.
Corresponding command line option is \fB\-n\fP.
Defaults to \fBno\fP.
.RE
.PP
predicate (string)
.RS 4
Indicates the metrics to be used as predicate metrics.
Corresponding command line option is \fB\-N\fP.
Undefined by default.
.RE
.PP
sort_metric (string)
.RS 4
Indicates the metrics to be used as sort reference metrics.
Corresponding command line option is \fB\-6\fP.
Undefined by default.
.RE
.PP
omit_flat (boolean)
.RS 4
Indicates that single-valued ``flat'' metrics are to be omitted
from reporting.
Corresponding command line option is \fB\-v\fP.
Defaults to \fBno\fP.
.RE
.PP
include_labels (boolean)
.RS 4
Indicates that PCP metric labels should included in the output.
Corresponding command line option is \fB\-m\fP.
Defaults to \fBno\fP.
.RE
.PP
include_texts (boolean)
.RS 4
Indicates that when writing a PCP archive,
PCP help texts shall be included in the created archive.
Corresponding command line option is \fB\-\-include\-texts\fP.
Defaults to \fBno\fP.
.RE
.PP
colxrow (string)
.RS 4
Indicates to swap columns and rows in \fIstdout\fP output using
the value as metric text label.
Corresponding command line option is \fB\-X\fP.
Undefined (no swapping) by default.
.RE
.PP
width (integer)
.RS 4
Indicates the width of stdout output columns.
Corresponding command line option is \fB\-w\fP.
Forced minimum is \fB3\fP.
Defaults to the shortest width that can fit the metric text label.
.RE
.PP
width_force (integer)
.RS 4
As \fBwidth\fP but overrides possible possible per-metric specifications.
Corresponding command line option is \fB\-W\fP.
Forced minimum is \fB3\fP.
.RE
.PP
precision (integer)
.RS 4
Indicates how many decimals to use for numeric non-integer output
values.
Corresponding command line option is \fB\-P\fP.
Defaults to \fB3\fP.
.RE
.PP
precision_force (integer)
.RS 4
As \fBprecision\fP but overrides possible per-metric specifications.
Corresponding command line option is \fB\-0\fP.
Undefined by default.
.RE
.PP
delimiter (string)
.RS 4
Indicates the column separator.
Corresponding command line option is \fB\-l\fP.
Default depends on the output target, see
.BR pmrep (1).
.RE
.PP
extcsv (boolean)
.RS 4
Indicates whether to write extended CSV output similar to
.BR sadf (1).
Corresponding command line option is \fB\-k\fP.
Defaults to \fBno\fP.
.RE
.PP
extheader (boolean)
.RS 4
Indicates whether to print extended header.
Corresponding command line option is \fB\-x\fP.
Defaults to \fBno\fP.
.RE
.PP
fixed_header (boolean)
.RS 4
Indicates that a fixed header should be used.
Corresponding command line option is \fB\-7\fP.
Defaults to \fBno\fP.
.RE
.PP
repeat_header (integer)
.RS 4
Indicates how often to repeat the header.
Corresponding command line option is \fB\-E\fP.
\fBauto\fR uses terminal height.
Defaults to \fB0\fP (header is not repeated).
.RE
.PP
dynamic_header (boolean)
.RS 4
Indicates that a dynamic header should be used.
Corresponding command line option is \fB\-1\fP.
Defaults to \fBno\fP.
.RE
.PP
separate_header (boolean)
.RS 4
Indicates whether to print a separate header.
Corresponding command line option is \fB\-g\fP.
Defaults to \fBno\fP.
.RE
.PP
timefmt (string)
.RS 4
Indicates the format string for formatting the timestamp.
Corresponding command line option is \fB\-f\fP.
Defaults to \fB%H:%M:%S\fP.
.RE
.PP
interpol (boolean)
.RS 4
Indicates whether to interpolate reported archive values.
Corresponding command line option is \fB\-u\fP.
See
.BR pmrep (1)
for complete description.
Defaults to \fByes\fP.
.RE
.PP
count_scale (string)
.RS 4
Indicates the unit/scale for counter metrics.
Corresponding command line option is \fB\-q\fP.
For supported syntax, see
.BR pmrep (1).
Undefined (no scaling) by default.
.RE
.PP
count_scale_force (string)
.RS 4
Like \fBcount_scale\fP but overrides possible per-metric specifications.
Corresponding command line option is \fB\-Q\fP.
Undefined by default.
.RE
.PP
space_scale (string)
.RS 4
Indicates the unit/scale for space metrics.
Corresponding command line option is \fB\-b\fP.
For supported syntax, see
.BR pmrep (1).
Undefined (no scaling) by default.
.RE
.PP
space_scale_force (string)
.RS 4
Like \fBspace_scale\fP but overrides possible per-metric specifications.
Corresponding command line option is \fB\-B\fP.
Undefined by default.
.RE
.PP
time_scale (string)
.RS 4
Indicates the unit/scale for time metrics.
Corresponding command line option is \fB\-y\fP.
For supported syntax, see
.BR pmrep (1).
Undefined (no scaling) by default.
.RE
.PP
time_scale_force (string)
.RS 4
Like \fBtime_scale\fP but overrides possible per-metric specifications.
Corresponding command line option is \fB\-Y\fP.
Undefined by default.
.RE
.SS The [global] section
The
.B [global]
section is used to define metrics that will be reported in addition to
any other separately defined metric or metricset.
Configuration options are not allowed in this section.
Global metrics are reported by default, the command line option \fB\-G\fP
or the configuration file option \fBglobals\fP can be used to disable
global metrics.
.PP
\fBAllowed settings\fP
.PP
.RS 4
Only \fImetricspecs\fP are allowed in this section.
See below for the metricspec specification.
.RE
.SH CUSTOM SECTIONS
Any other section than \fB[options]\fP or \fB[global]\fP will be
interpreted as a new \fImetricset\fP specification.
The section name is arbitrary, typically a reference to its
coverage or purpose.
A custom section may contain options, metricspecs, or both.
.PP
All the metrics specified in a custom section (metricset) will be
reported when \fBpmrep\fP reports that particular metricset.
More than one metricset (custom section) can be defined on the command
line in which case \fBpmrep\fP reports the combination of all the
metrics specified in the selected metricsets.
.PP
\fBAllowed settings\fP
.PP
.RS 4
Any option valid in the \fB[options]\fP section is also valid in a
custom section.
Any option or metric defined in a custom section will override the same
option or metric possibly defined earlier.
See below for the metricspec specification.
.RE
.SH METRICSET SPECIFICATION
There are three forms of the
.IR metricspec .
First, on the command line a metricspec can start with a colon
(``:'') to indicate a reference to a
.I metricset
(custom section) to be read from a
.B pmrep
configuration file.
Second, the \fIcompact form\fP of a metricspec is a one-line metric
specification which can be used both on the command line and in the
\fB[global]\fP and custom sections of the configuration file.
The only difference of its usage in the configuration file is that the
metric name is used as the key and the optional specifiers as values.
The compact form of the metricspec is specified in detail in
.BR pmrep (1).
The third, \fIverbose form\fP of a metricspec, is valid only in the
configuration file (see below).
.PP
In a custom section a key containing a dot (``.'') is interpreted as a
metric name and a non-option key not containing a dot is interpreted as
an identifier (handle) to bind related declarations together.
The identifier is arbitrary and is not used otherwise except for
binding the below specifiers and the metric together.
.PP
The verbose form of a metricspec starts with a declaration consisting of
a mandatory \fIidentifier\fP as the key and a performance metric name (a
PMNS node) as its value.
This equals to the compact form of the metricspec defining the same
performance metric without any of the optional specifiers defined.
.PP
The following specifiers are optional in the verbose form and can be
used as keys in any order with an earlier declared identifier followed
by a dot and the specifier (as in \fIidentifier\fP.\fIspecifier\fP).
See also the example later below.
.RS
.TP 2
.I label
Defines text label for the metric used by supporting output targets.
.TP
.I formula
Defines the needed arithmetic expression for the metric.
For details, see
.BR pmRegisterDerived (3).
.TP
.I instances
Defines the instances to be reported for the metric.
For details, see
.BR pmrep (1).
.TP
.I unit
Defines the unit/scale conversion for the metric.
Needs to be dimension-compatible and is used with non-string metrics.
For allowed values, see
.BR pmrep (1).
.TP
.I type
If set to \fBraw\fP rate conversion for the metric will be disabled.
.TP
.I width
Defines the width of the output column for the metric.
.TP
.I precision
Defines precision for numeric non-integer output values.
.TP
.I limit
Defines value limit filter for numeric metric values.
.RE
.SH EXAMPLE
The following example contains a short \fB[options]\fP section setting
some locally wanted default values.
It then goes on to define the global metrics \fBkernel.all.sysfork\fP
using the \fIcompact form\fP and \fBmem.util.allcache\fP using the
\fIverbose form\fP of a metricspec.
The latter is a derived metric using the specified formula.
Both of these metrics will be included in reporting unless disabled
with \fB\-G\fP or \fBglobals = no\fP.
.PP
Three different \fImetricsets\fP are also specified: \fBdb1\fP,
\fBdb2\fP, and \fBsar\-w\fP.
.PP
The DB sets define a host to be used as the source for the metrics.
Both use the \fIverbose form\fP of a metricspec (as the non-option key
\fBset\fP does not contain the dot) to include all \fBpostgresql\fP
related metrics.
.PP
The \fBsar\-w\fP set is an example how to mimic an existing tool with
\fBpmrep\fP.
.PP
The system default \fBpmrep\fP configuration files contain many more
examples.
The tab key on the command line after a colon completes available
metricsets (with bash and zsh).
.sp 1
.PP
.RS 4
.nf
[options]
timestamp = yes
interval = 2s
extheader = yes
repeat_header = auto
space_scale = MB

[global]
kernel.all.sysfork = forks,,,,8
cacheall = mem.util.allcache
cacheall.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
cacheall.width = 12

[db1]
source = db\-host1.example.com
set = postgresql

[db2]
source = db\-host2.example.com
set = postgresql

[sar\-w]
header = yes
unitinfo = no
globals = no
timestamp = yes
precision = 2
delimiter = " "
kernel.all.sysfork = proc/s,,,,12
kernel.all.pswitch = cswch/s,,,,9
.fi
.RE
.sp 1
.SH FILES
.TP
.I \f(CR$PCP_SYSCONF_DIR\fP/pmrep/*.conf
system provided default \fBpmrep\fP configuration files
.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 \fB/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
For environment variables affecting PCP tools, see \fBpmGetOptions\fP(3).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmrep (1),
.BR pmGetOptions (3),
.BR pmRegisterDerived (3)
and
.BR pmSpecLocalPMDA (3).