PCP-HTOP(5)

🌸 PCP-HTOP — the pcp-htop config file, bestie edition 🌸

okay so this is the manual page for pcp-htop(5), from the File Formats section of the manual. yes it's a config file page. no it's not boring. let's go 💅

---

✨ NAME ✨

pcp-htop — the pcp-htop configuration file 🎀

---

💖 DESCRIPTION 💖

pcp-htop is a customizable performance metrics reporting tool. it's got a whole dynamic architecture thing going on, where a bunch of configuration files hand over extra, optional meters and columns to stretch out the fixed set of display options that regular htop comes with. it's giving glow-up. ✨

these config files can come from system-wide locations — first /etc/pcp/htop, then /usr/share/pcp/htop — and also from below your home directory (usually ~/.config/htop). inside those locations, the meters and columns get scanned for dynamic Meter and Column specifications. yes bestie, it goes looking. 🔍

Meters show up in the top part of the pcp-htop window, and columns live in the lower part. meters tend to display system-wide metrics, and columns display metrics about individual processes. that's the vibe split. 🫶

the formats are similar but have slightly different requirements. both formats follow the common ini-style. blank lines are ignored. lines starting with the "#" character are treated as comments. periodt.

---

🔥 METERS 🔥

here's an example config for a brand new Redis meter, look at her go:

[redisclient]
caption = Redis clients
type = bar
blocked.metric = redis.blocked_clients
blocked.color = blue
blocked.label = blk
clients.metric = redis.connected_clients
clients.color = green
clients.label = conn

a configuration file can contain multiple meter definitions, no cap. each definition begins with an identifying name enclosed by square brackets — redisclient in this example. the name is used internally within pcp-htop and it must be unique, must begin with an alphabetic character, and may subsequently only contain alphanumeric characters or the underscore character. no whitespace or other characters allowed. we are not playing games with the naming rules. 💀

there are several parameters that define the way the meter will be displayed to the user:

• caption — this value is displayed on the Setup screen once the meter has been selected. a truncated version of the caption will also be displayed (followed by a colon) on the primary display while the meter is updating. 👑
• description — this can be used to provide more detail during the meter selection process on the Setup screen, and if present it is displayed in the "Available Meters" column. if not present, the caption will be used for this. if neither is present, the internal (mandatory) name will be used.
• type — this setting lets you specify a preferred default meter type. the associated value must be one of bar, text, graph, or led. if no value is provided for a dynamic meter, the default value of text will be used. ✨
• maximum — a numeric value can also be set to size the meter, such that values (e.g. for a bar type meter display) will be scaled within range zero to maximum.

the metric part, aka where the animation lives 🦋

the remaining definition syntax describes the individual metric(s) which will be used to animate the meter. one or more metrics must be specified for each meter, and there are several properties associated with each. once again, these metrics must be named (the same rules described above for meters apply here, fr fr) and the following properties can be configured:

• name.metric — this is the only mandatory field and it associates a PCP metric with the meter. values sampled for each metric at runtime provide the animation visible in the pcp-htop display. the metric specification can be either a PCP metric name as listed by pminfo(1) or a "derived" metric expression. the format for derived metric expressions is described on the pmRegisterDerived(3) manual page. 📖
• name.color — setting color to be used when rendering metric values. possible values are red, green, blue, cyan, magenta, yellow, gray, darkgray or white. pick your aesthetic 🌈
• name.label — an optional, short label to display before the metric value. the ":" character will be appended to the label before the metric value part of the display.
• name.suffix — an optional, short suffix to display after the metric value. commonly used to indicate values as a percentage using a "%" suffix value and to provide the base unit of measurement. note that since PCP maintains units for metrics, for those metrics that have dimension in "space" (bytes, kilobytes, megabytes, etc), a suffix will be automatically appended. so don't double up bestie, it's handled 🫶

---

🎀 COLUMNS 🎀

here's an example config for a new column showing open file descriptors for each process:

[openfds]
heading = FDS
caption = FDCOUNT
description = Open file descriptors
metric = proc.fd.count
width = 3

a configuration file can contain multiple column definitions. each definition begins with an identifying name enclosed by square brackets — openfds in this example — and the same rules apply as described above for meter names. 🧚

each column must specify a metric. optional parameters can also be set.

• metric — as with meters, the metric value must be either a PCP metric name as listed by pminfo(1) or a derived metric. the metric must have an instance domain (set of values) and that instance domain must map to the set of processes with the instance identifier being PIDs (process identifiers). typically this will be metrics from the proc or hotproc namespace (pmdaproc(1)), but metrics from other domains (pmdabpf(1), etc) that have per-process values are equally applicable. equal opportunity metrics 💖
• width — column width to use when displaying values for the metric. a negative value can be used to specify left alignment. an upper column limit of 28 characters is enforced. the default column width is 5 characters.
• heading — the short title that will be displayed at the head of the column — usually a short, cryptic, all uppercase string. FDS energy.
• caption — a short identifying word presented to users on the Setup screen under both the Available and Active Columns lists.
• description — text that assists users to understand the meaning of this column when it is being presented via the Setup screen in the Available Columns list.

---

👑 SEE ALSO 👑

pcp-htop(1), pminfo(1), pmcd(1), pmdaproc(1), pmdabpf(1) and pmRegisterDerived(3). go read those too, they're the supporting cast 🌟

---

💜 AUTHORS 💜

htop was originally developed by Hisham Muhammad. nowadays it is maintained by the community at <htop@groups.io>. iconic lineage honestly 🙌

pcp-htop is maintained as a collaboration between the <htop@groups.io> and <pcp@groups.io> communities, and forms part of the Performance Co-Pilot suite of tools. it's a whole crossover event ✨

---

and that's the whole page bestie 💅 this manual page comes to you from Performance Co-Pilot, dated 2026, and yes it's the PCP-HTOP(5) page in the File Formats section. slay, go configure something, and remember: every option, every rule, every default — kept exactly as it was. no cap. 🫶