pcp-htop - pcp-htop configuration file
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.
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.
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.
pcp-htop(1),
pminfo(1),
pmcd(1),
pmdaproc(1),
pmdabcc(1),
pmdabpf(1) and
pmRegisterDerived(3).
htop was originally developed by Hisham Muhammad. Nowadays it is
maintained by the community at <
[email protected]>.
pcp-htop is maintained as a collaboration between the
<
[email protected]> and <
[email protected]> communities, and forms part
of the Performance Co-Pilot suite of tools.