docs: updates and new manual page for pcp-htop

Add some words about pcp-htop to the main man page, and add a
new man page describing the pcp-htop configuration files that
allow new meters and columns to be defined at runtime.
This commit is contained in:
Nathan Scott 2021-07-23 11:50:28 +10:00
parent 4f3ba680fb
commit 04da92dfd1
4 changed files with 298 additions and 3 deletions

1
.gitignore vendored
View File

@ -37,6 +37,7 @@ config.sub
configure
depcomp
htop.1
pcp-htop.5
install-sh
libtool
ltmain.sh

View File

@ -663,7 +663,7 @@ AM_CONDITIONAL([HTOP_PCP], [test "$my_htop_platform" = pcp])
AM_CONDITIONAL([HTOP_UNSUPPORTED], [test "$my_htop_platform" = unsupported])
AC_SUBST(my_htop_platform)
AC_CONFIG_FILES([Makefile htop.1])
AC_CONFIG_FILES([Makefile htop.1 pcp-htop.5])
AC_OUTPUT
if test "$my_htop_platform" = unsupported; then

View File

@ -1,9 +1,13 @@
.TH "HTOP" "1" "2020" "@PACKAGE_STRING@" "User Commands"
.SH "NAME"
htop \- interactive process viewer
htop, pcp-htop \- interactive process viewer
.SH "SYNOPSIS"
.B htop
.RB [ \-dCFhpustvH ]
.br
.B pcp\ htop
.RB [ \-dCFhpustvH ]
.RB [ \-\-host/-h\ host ]
.SH "DESCRIPTION"
.B htop
is a cross-platform ncurses-based process viewer.
@ -18,6 +22,19 @@ multiple processes and act on them all at once.
.LP
Tasks related to processes (killing, renicing) can be done without
entering their PIDs.
.LP
.B pcp-htop
is a version of
.B htop
built using the Performance Co-Pilot (PCP) Metrics API (see \c
.BR PCPIntro (1),
.BR PMAPI (3)),
allowing values not built into
.B htop
to be displayed from arbitrary metrics.
See the section below titled
.B "CONFIG FILES"
for further details.
.br
.SH "COMMAND-LINE OPTIONS"
Mandatory arguments to long options are mandatory for short options too.
@ -527,7 +544,7 @@ Summary: build time dependency on
C header files, optional runtime dependency on
.B libsensors(3)
via dynamic loading.
.SH "CONFIG FILE"
.SH "CONFIG FILES"
By default
.B htop
reads its configuration from the XDG-compliant path
@ -544,6 +561,36 @@ and as a last resort, falls back to its hard coded defaults.
You may override the location of the configuration file using the $HTOPRC
environment variable (so you can have multiple configurations for different
machines that share the same home directory, for example).
.LP
The
.B pcp-htop
utility makes use of
.I htoprc
in exactly the same way.
In addition, it supports additional configuration files allowing
new meters and columns to be added to the display via the usual
Setup function, which will display additional Available Meters
and Available Column entries for each runtime configured meter
or column.
.LP
These
.B pcp-htop
configuration files are read once at startup.
The format of these files is described in detail in the
.BR pcp-htop (5)
manual page.
.LP
This functionality makes available many thousands of Performance
Co-Pilot metrics for display by
.BR pcp-htop ,
as well as the ability to display custom metrics added at individual sites.
Applications and services instrumented using the OpenMetrics format
.B https://openmetrics.io
can also be displayed by
.B pcp-htop
if the
.BR pmdaopenmetrics (1)
component is configured.
.SH "MEMORY SIZES"
Memory sizes in
.B htop
@ -561,7 +608,17 @@ space and make memory size representations consistent throughout
.BR uptime (1)
and
.BR limits.conf (5).
.SH "SEE ALSO FOR PCP"
.BR pmdaopenmetrics (1),
.BR PCPIntro (1),
.BR PMAPI (3),
and
.BR pcp-htop (5).
.SH "AUTHORS"
.B htop
was originally developed by Hisham Muhammad.
Nowadays it is maintained by the community at <htop@groups.io>.
.LP
.B 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.

237
pcp-htop.5.in Normal file
View File

@ -0,0 +1,237 @@
.TH "PCP-HTOP" "5" "2021" "@PACKAGE_STRING@" "File Formats"
.SH "NAME"
\f3pcp-htop\f1 \- pcp-htop configuration file
.SH "DESCRIPTION"
.B 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
.BR htop .
.LP
These configuration files can be provided from both system-wide
locations (first
.I @sysconfdir@/pcp/htop
then
.IR @datarootdir@/pcp/htop )
and below the users home directory (usually
.IR ~/.config/htop ).
Within these locations the
.I meters
and
.I columns
are scanned for dynamic Meter and Column specifications.
.LP
Meters are displayed in the top part of the
.B pcp-htop
window, and columns are display in the lower part.
Meters tend to display system-wide metrics, and Columns
display metrics about individual processes.
.LP
The formats are similar but have slightly different requirements.
Both formats follow the common ini-style, also allowing both empty
lines and comment lines starting with the "#" character.
.SH "METERS"
The following is an example configuration for a new Redis meter:
.LP
.ft CW
.nf
.in +0.5i
[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
.in
.fi
.ft 1
.LP
A configuration file can contain multiple meter definitions.
Each definition begins with a identifying name enclosed by
square brackets \-
.I redisclient
in this example.
The name is used internally within
.B 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.
.LP
There are several parameters that define the way the meter
will be displayed to the user.
.TP 5
.B caption
This value is displayed on the Setup screen once the meter
has been selected.
A truncated version of the
.I caption
will also be displayed (followed by a colon) on the primary
display while the meter is updating.
.TP
.B 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
.B caption
will be used for this.
If neither is present, the internal (mandatory)
.B name
will be used.
.TP
.B type
This setting allows a preferred default meter type to be specified.
The associated value must be one of
.IR bar ,
.IR text ,
.IR graph ,
or
.IR led .
If no value is provided for a dynamic meter, the default value of
.IR text
will be used.
.TP
.B maximum
A numeric value can also be set to size the meter, such that
values (e.g. for a
.I bar
type meter display) will be scaled within range zero to
.IR maximum .
.LP
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:
.TP 5
.B 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
.B pcp-htop
display.
The metric specification can be either a PCP metric name as
listed by
.BR pminfo (1)
or a "derived" metric expression.
The format for derived metric expressions is described on the
.BR pmRegisterDerived (3)
manual page.
.TP
.B name.color
Setting color to be used when rendering metric values.
Possible values are
.IR red ,
.IR green ,
.IR blue ,
.IR cyan ,
.IR magenta ,
.IR yellow ,
.IR gray ,
.I darkgray
or
.IR white .
.TP
.B name.label
An optional, short label to display before the metric value.
The ":" character will be appended to the
.I label
before the metric value part of the display.
.TP
.B name.suffix
An optional, short suffix to display after the metric value.
Commonly used to indicate values as a percentage using a "%"
.I 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.
.SH "COLUMNS"
The following is an example configuration for a new column
showing open file descriptors for each process:
.LP
.ft CW
.nf
.in +0.5i
[openfds]
heading = FDS
caption = FDCOUNT
description = Open file descriptors
metric = proc.fd.count
width = 3
.in
.fi
.ft 1
.LP
A configuration file can contain multiple column definitions.
Each definition begins with a identifying name enclosed
by square brackets \-
.I openfds
in this example, and the same rules apply as described above
for meter names.
.LP
Each column must specify a metric.
Optional parameters can also be set.
.TP 5
.B metric
As with meters, the metric value must be either a PCP metric
name as listed by
.BR 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
.I proc
or
.I hotproc
namespace (\c
.BR pmdaproc (1)),
but metrics from other domains (\c
.BR pmdabcc (1),
.BR pmdabpf (1),
etc) that have per-process values are equally applicable.
.TP
.B 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.
.TP
.B heading
The short title that will be displayed at the head of the
column \- usually a short, cryptic, all uppercase string.
.TP
.B caption
A short identifying word presented to users on the Setup
screen under both the Available and Active Columns lists.
.TP
.B 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.
.SH "SEE ALSO"
.BR pcp-htop (1),
.BR pminfo (1),
.BR pmcd (1),
.BR pmdaproc (1),
.BR pmdabcc (1),
.BR pmdabpf (1)
and
.BR pmRegisterDerived (3).
.SH "AUTHORS"
.B htop
was originally developed by Hisham Muhammad.
Nowadays it is maintained by the community at <htop@groups.io>.
.LP
.B 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.