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.

4 files changed, 298 insertions, 3 deletions

diff --git a/.gitignore b/.gitignore
index fe0279fe..82624490 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,6 +37,7 @@ config.sub
 configure
 depcomp
 htop.1
+pcp-htop.5
 install-sh
 libtool
 ltmain.sh
diff --git a/configure.ac b/configure.ac
index be40187a..9936bdf9 100644
--- a/configure.ac
+++ b/configure.ac
@@ -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
diff --git a/htop.1.in b/htop.1.in
index 9b81a210..b4cde44f 100644
--- a/htop.1.in
+++ b/htop.1.in
@@ -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.
diff --git a/pcp-htop.5.in b/pcp-htop.5.in
new file mode 100644
index 00000000..d017cb89
--- /dev/null
+++ b/pcp-htop.5.in
@@ -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.