PCP-DSTAT(5)

✨ pcp-dstat(5) — the config file glow-up ✨

okay bestie, so you know pcp-dstat? yeah. this is its configuration file situation — pcp-dstat(5) if you wanna be formal about it. 💅 let's get into it.

---

🌸 NAME 🌸

pcp-dstat — the pcp-dstat configuration file. that's it, that's the name, she's simple like that 🎀

---

💖 DESCRIPTION 💖

pcp-dstat is a customizable performance metrics reporting tool. and the way she does it?? she has a whole ``plugin'' architecture — a bunch of pre-defined plugins each offering small lil sets of columnar metric reports, and then the pcp-dstat command line options pick which of those plugins actually show up in the report you generate. iconic behavior, honestly. ✨

every single plugin lives in a section of a configuration file. a typical installation ships many configuration files, and often there's more than one section (plugin) inside each file. so yeah, lots of plugins, lots of files, very main character. 👑

configuration files get read from both a system directory and the user's home directory:

• $PCP_SYSCONF_DIR/dstat
• $HOME/.pcp/dstat

---

🦋 FILE FORMAT 🦋

the config files use ini-style syntax — sections (plugins) and options inside those sections. a section starts with the plugin name in square brackets and keeps going until the next section starts. here's an example section with two options, look at her:

[plugin]
option = value
metric.option = value2

a line comment starts with a hash sign (#) or a semicolon (;). and ngl, inline comments are not supported — so don't try it, bestie, it will not work. 🙈

there are some options that apply to the plugin as a whole, and literally anything else counts as a column definition. column definitions map directly to individual PCP metrics. periodt.

✨ The [plugin] options ✨

• label (string) — the overall title used for this plugin. in the special case where metrics have instances being reported as a group (peep grouptype below), this string can contain the %I pattern, which gets substituted with the name of the instance — go look at the cpu, disk, net and int(errupts) plugins for examples of this special syntax. undefined by default, and gets set automatically to the section (plugin) name. 🫶
• width (integer) — the column width used for metrics in this plugin. default is 5.
• precision (integer) — the maximum precision used when reporting columns in floating point for this plugin. undefined by default, set automatically based on width.
• printtype (character) — the reporting style for metric values in this plugin. possible settings are d(ecimal), f(loat), p(ercent), s(tring), b(its), t(ime). by default a setting gets used based on the metric type and semantic — refer to PMAPI(3) for the deets on PCP metric metadata.
• colorstep (integer) — a ``step'' at which the next color gets transitioned to when reporting metric values. as metric values change on each sample, colorstep determines the increments beyond which a new color gets selected. defaults to 1000. 🌈
• grouptype (integer) — for plugins with metrics sharing the same instance domain, you can request more complex grouping behaviour. the default behaviour is to not use instance grouping, and to report each instance of the metric in a separate column (the load plugin is the example here, using the kernel.all.load metric).

grouping can be set at three distinct levels — 1, 2, 3 or 4:

• Level 1 displays instances of metrics only (no totals) — equivalent to using the --cpu plugin on the pcp-dstat command line with specific processors' utilization displayed, e.g. displaying CPU numbers 4, 5 and 12 (-C 4,5,12).
• Level 2 displays the total column — the sum of all instances for the specified metric(s) in this plugin.
• Level 3 is a combination of both modes, for example using the pcp-dstat --cpu plugin with options -C 4,5,12,total.
• Level 4 is a top-like mode, where a special "top" expression is used to rank all instances — the top-most (largest) value will be displayed.

• instances (comma-separated-value string) — defines the instances to be reported for the metric. the default is to report all instances for set-values metrics.
• cullinsts (regex pattern) — an optional regular expression used to cull metric instances from the aggregation ('total') in generated reports. for example it's super common to exclude loopback devices from the network interface reports, and this option is how you do it. default is to report on all instances (no culling). 💀
• filtertype (string) — used for plugin metrics that allow command-line instance filtering options. the value of the filtertype entry should match whatever instance select option you're using, per the list below:
  • cpu — -C
  • disk — -D
  • dm — -L
  • md — -M
  • part — -P
  • int — -I
  • net — -N
  • net-packets — -N
  • swap — -S

💜 The [plugin] metrics 💜

every plugin must have at least one metric associated with it, no exceptions bestie. any key that isn't one of the global plugin options above is considered a metric specification or a metric option. these keys are what define the metrics and their report formatting. ✨

first and foremost — each column is typically represented by an individual metric (and if that metric is set-valued, i.e. it has instances, you get multiple columns out of it). you specify this by setting a new key (column) to a metric specification. the column (key) name is an arbitrary word made of alphabetic characters. the metric specification is any PCP metric name or derived metric specification, which means you can do basic arithmetic calculations to form that individual column. that derived metric syntax is described over on the pmRegisterDerived(3) manual page. 🧚

some examples of both forms of metric specification are given down in the ``EXAMPLES'' section. once a column has been associated with a metric, other options specific to that column can be set using a dot-separated syntax.

🌟 Metric options 🌟

• metric.label — the subtitle used for the reported values of this metric. the default label is the column name from the configuration file.

when set-valued PCP metrics (i.e. ones with instances) are being used, it's often convenient to put either the instance number or instance name in the heading. you do that with format specifiers — %d or %i for instance numbers (e.g. replaced by 6 for the sixth processor), and %s or %I for instance names (e.g. replaced by eth0 for the ethernet interface). you can discover the available instance names for any metric via the pminfo(1) or pmprobe(1) commands. 🔥

• metric.width — the column width to be used when reporting values for this metric.
• metric.unit (string) — 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).
• metric.type (string) — if set to raw, rate conversion for the metric will be disabled.
• metric.precision (integer) — defines precision for floating point values.
• metric.limit (string) — defines the value limit filter for numeric metric values.

---

🎀 EXAMPLES 🎀

here's the glow-up moment: this example defines a virtual filesystem plugin, with two columns, defined using three PCP metrics — vfs.files.count, vfs.inodes.count and vfs.inodes.free. the inodes metrics get combined using the derived metric notation. slay.

[vfs]
width = 6
label = filesystem
files = vfs.files.count
inode = vfs.inodes.count - vfs.inodes.free
inode.label = inodes

and the system default pcp-dstat plugin files contain many more examples. go read them, they're lowkey a whole vibe. 📚

---

🌈 FILES 🌈

• $HOME/.pcp/dstat/ — private per-user configuration files
• $PCP_SYSCONF_DIR/dstat/ — system-wide 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), pcp-dstat(1), pminfo(1), pmprobe(1), pmrep(1), PMAPI(3), pmGetOptions(3), pmRegisterDerived(3) and pmrep.conf(5).

---

and that's the whole page, bestie 💖 go forth and configure your plugins, you absolute legend.

that was pcp-dstat(5) from Performance Co-Pilot (PCP), the one and only — mwah, love her, bye 💅✨