PMREP.CONF(5)

pmrep.conf 💖 the pmrep config file, bestie

<section name folded in: PMREP.CONF(5) — File Formats Manual, iykyk>

---

✨ NAME ✨

pmrep.conf — the pmrep configuration file, aka where you tell pmrep what to do before it even asks 🎀

---

🌸 DESCRIPTION 🌸

Okay so, pmrep? It's a customizable performance metrics reporting tool. Like, 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. It's giving flexible, fr fr. ✨

The metrics you actually care about 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 the configuration files described below. For command line argument details, go peek at pmrep(1). 👑

The pmrep.conf configuration file lets you set default runtime values and define any number of custom metricsets for pmrep. A metricset is a user-defined arbitrary set of performance metrics. This lets users create specifically crafted metricsets that are 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. So iconic of them. 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 it's defined multiple times. However, custom metricset sections will not be combined; only the last definition found will be used for reporting. Not me learning this the hard way 💀

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). It's a whole hierarchy, bestie — like a friendship pyramid but for settings. 💅

---

🎀 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:

[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).

Careful, bestie: that "expect" is doing a lot of work there — just don't be out here quoting everything, unless your value is literally only whitespace. Then quote it. 😭

A line comment starts with a hash sign (#) or a semicolon (;). Inline comments are not supported. So no sneaking a little note at the end of a line, she will not read it 🙈

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).

---

...and that's only part 1, we're literally just getting started ✨

💫 SPECIAL SECTIONS 💫

Okay bestie, so the config file has these special lil sections that do ✨specific things✨ and honestly they're the main character. Let's get into it.

---

🎀 The [options] section 🎀

So this section gets read every single time pmrep runs, no cap. It's where you set your default runtime options. And here's the tea: these can get overridden by metricspec-specific options or by command line options. Metrics are not allowed in this section, so don't even try it 🙅‍♀️.

Allowed settings

Here's everything you can put in there:

• version (integer) — says what version the config file is. Defaults to 1. Fr fr the only value supported rn is 1, so yeah.
• source (string) — the source for your metrics. Here's how it reads your vibe: if the value contains a slash (/), it's interpreted as a PCP archive. If it's set to the special character @, the local DSO PMDA context gets used. Otherwise it's interpreted as a hostname. The command line parameters that correspond are -a, -h, and -L. Defaults to local: (check PCPIntro(1) for that one).
• output (string) — where your output goes. Corresponding command line option is -o. For the supported output targets, go look at pmrep(1). Defaults to stdout.
• speclocal (string) — the local DSO PMDAs that get made available when you're using the local DSO PMDA context. Corresponding command line option is -K. For the syntax deets, see pmSpecLocalPMDA(3). Use a semicolon (;) to separate more than one spec, okay? Undefined by default.
• derived (string) — derived metric specifications. Corresponding command line option is -e. Syntax description lives in pmrep(1). Undefined by default.
• daemonize (boolean) — whether to daemonize on startup or not. Corresponding command line option is --daemonize. Defaults to no.
• header (boolean) — whether to print headers. Corresponding command line option is -H. Defaults to yes.
• instinfo (boolean) — whether to include instance information as part of headers. Corresponding command line option is --no-inst-info. Defaults to yes.
• unitinfo (boolean) — whether to include unit information as part of stdout headers. Corresponding command line option is -U. Defaults to yes.
• csv_unitinfo (boolean) — whether to include unit information as part of CSV headers. Corresponding command line option is --csv-unit-info. Defaults to no.
• globals (boolean) — whether to include metrics from the [global] section (scroll down bb) for reporting. Corresponding command line option is -G. Defaults to yes.
• timestamp (boolean) — whether to print the timestamp. Corresponding command line option is -p. Defaults to no.
• samples (integer) — how many samples to print. Corresponding command line option is -s. Undefined by default (which means unlimited number of samples, unless some other option limits it).
• interval (string) — the interval between samples. Corresponding command line option is -o. Follows the time syntax described in PCPIntro(1). Defaults to 1s.
• delay (boolean) — whether to pause between samples when you're replaying from an archive, instead of replaying at full speed like a maniac. Corresponding command line option is -d. Defaults to no.
• type (string) — whether to output raw metric values by disabling all rate conversions, or convert cumulative counters to rates (that's the default). Corresponding command line option is -r. Allowed values are default or raw.
• type_prefer (string) — same as type but it does not override possible per-metric type specifications. Corresponding command line option is -R. Allowed values are default or raw.
• ignore_incompat (boolean) — says incompatible metrics are to be ignored. Corresponding command line option is -I. Defaults to no.
• ignore_unknown (boolean) — says unknown metrics are to be ignored. Corresponding command line option is -5. Defaults to no.
• names_change (string) — the action to take on PMNS changes during sampling. Corresponding command line option is -4. Defaults to ignore.
• instances (string) — the instances to be reported. Corresponding command line option is -i. Undefined by default (meaning all instances get reported).
• live_filter (boolean) — says live filtering should be enabled. Corresponding command line option is -j. Defaults to no.
• rank (integer) — the value used for ranking instances. Corresponding command line option is -J. Undefined by default (all instances are reported).
• overall_rank (boolean) — says overall ranking should be performed. Corresponding command line option is -2. Defaults to no.
• overall_rank_alt (boolean) — says overall ranking with the alternative output format should be performed. Corresponding command line option is -3. Defaults to no.
• limit_filter (integer) — the value used with limit filtering. Corresponding command line option is -8. Undefined by default (all instances are reported).
• limit_filter_force (integer) — same as limit_filter but it overrides possible per-metric specifications. Corresponding command line option is -9. Undefined by default (all instances are reported).
• invert_filter (boolean) — says invert filtering should be performed. Corresponding command line option is -n. Defaults to no.
• predicate (string) — the metrics to be used as predicate metrics. Corresponding command line option is -N. Undefined by default.
• sort_metric (string) — the metrics to be used as sort reference metrics. Corresponding command line option is -6. Undefined by default.
• omit_flat (boolean) — says single-valued "flat" metrics get omitted from reporting. Corresponding command line option is -v. Defaults to no.
• include_labels (boolean) — says PCP metric labels should be included in the output. Corresponding command line option is -m. Defaults to no.
• include_texts (boolean) — when writing a PCP archive, says PCP help texts shall be included in the created archive. Corresponding command line option is --include-texts. Defaults to no.
• colxrow (string) — swap columns and rows in stdout output, using the value as the metric text label. Corresponding command line option is -X. Undefined by default (no swapping).
• width (integer) — the width of stdout output columns. Corresponding command line option is -w. Forced minimum is 3. Defaults to the shortest width that can fit the metric text label.
• width_force (integer) — same as width but it overrides possible per-metric specifications. Corresponding command line option is -W. Forced minimum is 3.
• precision (integer) — how many decimals to use for numeric non-integer output values. Corresponding command line option is -P. Defaults to 3.
• precision_force (integer) — same as precision but it overrides possible per-metric specifications. Corresponding command line option is -0. Undefined by default.
• delimiter (string) — the column separator. Corresponding command line option is -l. The default depends on the output target, so peek at pmrep(1).
• extcsv (boolean) — whether to write extended CSV output, similar to sadf(1). Corresponding command line option is -k. Defaults to no.
• extheader (boolean) — whether to print an extended header. Corresponding command line option is -x. Defaults to no.
• fixed_header (boolean) — says a fixed header should be used. Corresponding command line option is -7. Defaults to no.
• repeat_header (integer) — how often to repeat the header. Corresponding command line option is -E. auto uses the terminal height. Defaults to 0 (header is not repeated).
• dynamic_header (boolean) — says a dynamic header should be used. Corresponding command line option is -1. Defaults to no.
• separate_header (boolean) — whether to print a separate header. Corresponding command line option is -g. Defaults to no.
• timefmt (string) — the format string for formatting the timestamp. Corresponding command line option is -f. Defaults to %H:%M:%S.
• interpol (boolean) — whether to interpolate reported archive values. Corresponding command line option is -u. See pmrep(1) for the complete description. Defaults to yes.
• count_scale (string) — the unit/scale for counter metrics. Corresponding command line option is -q. For the supported syntax, see pmrep(1). Undefined by default (no scaling).
• count_scale_force (string) — like count_scale but it overrides possible per-metric specifications. Corresponding command line option is -Q. Undefined by default.
• space_scale (string) — the unit/scale for space metrics. Corresponding command line option is -b. For the supported syntax, see pmrep(1). Undefined by default (no scaling).
• space_scale_force (string) — like space_scale but it overrides possible per-metric specifications. Corresponding command line option is -B. Undefined by default.
• time_scale (string) — the unit/scale for time metrics. Corresponding command line option is -y. For the supported syntax, see pmrep(1). Undefined by default (no scaling).
• time_scale_force (string) — like time_scale but it overrides possible per-metric specifications. Corresponding command line option is -Y. Undefined by default.

---

🦋 The [global] section 🦋

So the [global] section is where you define metrics that get reported in addition to any other separately defined metric or metricset. Bestie, listen — configuration options are not allowed in this section, only metrics. Global metrics are reported by default, and you can use the command line option -G or the configuration file option globals to turn global metrics off.

Allowed settings

Only metricspecs are allowed in this section, periodt. Scroll on down for the metricspec specification 👇

---

ngl that's a lot of options but you got this 💖 keep reading, we're not done yet

🦋 CUSTOM SECTIONS 🦋

Okay bestie, here's the fun part. Any section that isn't [options] or [global] gets read as a whole new metricset specification. That section name? Completely up to you — it's arbitrary, and usually it's just a lil reference to what it covers or what it's for. A custom section can hold options, metricspecs, or honestly both, no rules against it.

All the metrics you specify in a custom section (metricset) get reported when pmrep reports that particular metricset. And yes you can define more than one metricset (custom section) — you do it on the command line, and then pmrep reports the combination of all the metrics specified in the metricsets you picked. It's giving "why choose" energy fr fr.

✨ Allowed settings ✨

Any option that's valid in the [options] section is also valid in a custom section. And here's the rule to remember: any option or metric defined in a custom section will override the same option or metric that may have been defined earlier. Later wins, periodt. (See below for the metricspec specification, we're getting there 💅)

---

💖 METRICSET SPECIFICATION 💖

There are three forms of the metricspec, and you're gonna know all three:

1. On the command line, a metricspec can start with a colon (``:'') to indicate a reference to a metricset (custom section) that should be read from a pmrep configuration file.
2. The compact form of a metricspec is a one-line metric specification, and it works both on the command line and in the [global] and custom sections of the config file. The only difference when you use it in the config file? The metric name is used as the key and the optional specifiers become values. The compact form of the metricspec is specified in detail in pmrep(1).
3. The verbose form of a metricspec — and this one is valid only in the configuration file (see below, bestie).

In a custom section, a key containing a dot (``.'') is interpreted as a metric name, and a non-option key that does not contain a dot is interpreted as an identifier (handle) to bind related declarations together. That identifier is arbitrary and isn't used for anything else except binding the specifiers below and the metric together. Basically it's the group chat name for your metric's little squad 🫶

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 the compact form of the metricspec defining the same performance metric without any of the optional specifiers defined. Same metric, zero extras.

The following specifiers are optional in the verbose form, and you can use them as keys in any order — just take an earlier declared identifier, follow it with a dot, then the specifier (as in identifier.specifier). See the example further down below 👇

• label — Defines text label for the metric used by supporting output targets.
• formula — Defines the needed arithmetic expression for the metric. For details, see pmRegisterDerived(3).
• instances — Defines the instances to be reported for the metric. For details, see pmrep(1).
• 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 pmrep(1).
• type — If set to raw rate conversion for the metric will be disabled.
• width — Defines the width of the output column for the metric.
• precision — Defines precision for numeric non-integer output values.
• limit — Defines value limit filter for numeric metric values.

---

🌈 EXAMPLE 🌈

Okay so this example is a whole vibe. It's got a short [options] section setting some locally wanted default values, and then it defines the global metrics kernel.all.sysfork using the compact form and mem.util.allcache using the verbose form of a metricspec. That last one is a derived metric using the specified formula. Both of these metrics will be included in reporting unless you disable them with -G or globals = no.

Three different metricsets are also specified: db1, db2, and sar-w. Iconic, honestly.

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 of how to mimic an existing tool with pmrep. Not me building a whole tool clone in a config file 😭

The system default pmrep configuration files contain many more examples, and — fun fact — the tab key on the command line after a colon completes available metricsets (with bash and zsh). So handy, you're welcome.

[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

---

🎀 FILES 🎀

• $PCP_SYSCONF_DIR/pmrep/*.conf — system provided default pmrep configuration files

---

⭐ PCP ENVIRONMENT ⭐

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).

---

👑 SEE ALSO 👑

PCPIntro(1), pmrep(1), pmGetOptions(3), pmRegisterDerived(3) and pmSpecLocalPMDA(3).

---

And that's the whole page bestie!! This lil masterpiece comes to you from Performance Co-Pilot, PCP version, and it's PMREP.CONF(5) — go forth and configure your metricsets, you absolute main character 🫶💖✨