Provided by: pcp_6.3.0-1_amd64 
NAME
pcp-htop - pcp-htop configuration file
DESCRIPTION
pcp-htop is a customizable performance metrics reporting tool. It has a dynamic
architecture, where a set of configuration files provide additional, optional meters and
columns to extend the fixed set of display options provided by regular htop.
These configuration files can be provided from both system-wide locations (first
/etc/pcp/htop then /usr/share/pcp/htop) and below the user's home directory (usually
~/.config/htop). Within these locations the meters and columns are scanned for dynamic
Meter and Column specifications.
Meters are displayed in the top part of the pcp-htop window, and columns are displayed in
the lower part. Meters tend to display system-wide metrics, and Columns display metrics
about individual processes.
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.
METERS
The following is an example configuration for a new Redis meter:
[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. Each definition begins with
a identifying name enclosed by square brackets - redisclient in this example. The name is
used internally within pcp-htop and 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 are allowed.
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 allows a preferred default meter type to be specified. 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 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) and the following properties can be
configured:
name.metric
This is the only mandatory field and 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.
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.
COLUMNS
The following is an example configuration 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
a 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 (pmdabcc(1),
pmdabpf(1), etc) that have per-process values are equally applicable.
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.
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), pmdabcc(1), pmdabpf(1) and
pmRegisterDerived(3).
AUTHORS
htop was originally developed by Hisham Muhammad. Nowadays it is maintained by the
community at <htop@groups.io>.
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.