From 04da92dfd16ebe7c667d650cbf960c72c91f8c9e Mon Sep 17 00:00:00 2001 From: Nathan Scott Date: Fri, 23 Jul 2021 11:50:28 +1000 Subject: [PATCH] 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. --- .gitignore | 1 + configure.ac | 2 +- htop.1.in | 61 ++++++++++++- pcp-htop.5.in | 237 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 298 insertions(+), 3 deletions(-) create mode 100644 pcp-htop.5.in 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 . +.LP +.B pcp-htop +is maintained as a collaboration between the and +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 . +.LP +.B pcp-htop +is maintained as a collaboration between the and +communities, and forms part of the Performance Co-Pilot suite of tools.