|PMREP.CONF(5)||File Formats Manual||PMREP.CONF(5)|
pmrep.conf - pmrep configuration file
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.
The metrics of interest are named in the metricspec argument(s) on the 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 pmrep(1).
The pmrep.conf configuration file allows for setting default runtime values and defining any number of custom metricsets for 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 pmrep.conf. See below for the metricset specification.
In case pmrep configuration files are read from a directory then values for the [options] and [global] 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 metricset sections will not be combined, only the last definition found will be used for reporting.
Options via environment values (see 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).
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:
[section] key = value key2 = value2
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).
A line comment starts with a hash sign (``#'') or a semicolon (``;''). Inline comments are not supported.
pmrep.conf must be readable by the user invoking pmrep.
Any option described below with a corresponding command line option contains additional functional description in pmrep(1).
The [options] section¶
The [options] section is read every time 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.
The [global] section¶
The [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 -G or the configuration file option globals can be used to disable global metrics.
Any other section than [options] or [global] will be interpreted as a new metricset specification. The section name is arbitrary, typically a reference to its coverage or purpose. A custom section may contain options, metricspecs, or both.
All the metrics specified in a custom section (metricset) will be reported when pmrep reports that particular metricset. More than one metricset (custom section) can be defined on the command line in which case pmrep reports the combination of all the metrics specified in the selected metricsets.
There are three forms of the metricspec. First, on the command line a metricspec can start with a colon (``:'') to indicate a reference to a metricset (custom section) to be read from a pmrep configuration file. Second, the compact form of a metricspec is a one-line metric specification which can be used both on the command line and in the [global] 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 pmrep(1). The third, verbose form of a metricspec, is valid only in the configuration file (see below).
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.
The verbose form of a metricspec starts with a declaration consisting of a mandatory identifier 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.
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 identifier.specifier). See also the example later below.
- Defines text label for the metric used by supporting output targets.
- Defines the needed arithmetic expression for the metric. For details, see pmRegisterDerived(3).
- Defines the instances to be reported for the metric. For details, see pmrep(1).
- Defines the unit/scale conversion for the metric. Needs to be dimension-compatible and is used with non-string metrics. For allowed values, see pmrep(1).
- If set to raw rate conversion for the metric will be disabled.
- Defines the width of the output column for the metric.
- Defines precision for numeric non-integer output values.
- Defines value limit filter for numeric metric values.
The following example contains a short [options] section setting some locally wanted default values. It then goes on to define the global metrics kernel.all.sysfork using the compact form and mem.util.allcache using the verbose form 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 -G or globals = no.
Three different metricsets are also specified: db1, db2, and sar-w.
The DB sets define a host to be used as the source for the metrics. Both use the verbose form of a metricspec (as the non-option key set does not contain the dot) to include all postgresql related metrics.
The sar-w set is an example how to mimic an existing tool with pmrep.
The system default pmrep configuration files contain many more examples. The tab key on the command line after a colon completes available metricsets (with bash and zsh).
[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
- system provided default pmrep configuration files
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).
For environment variables affecting PCP tools, see pmGetOptions(3).