mirror of
https://github.com/xzeldon/htop.git
synced 2024-12-24 15:15:44 +00:00
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
parent
4f3ba680fb
commit
04da92dfd1
1
.gitignore
vendored
1
.gitignore
vendored
@ -37,6 +37,7 @@ config.sub
|
||||
configure
|
||||
depcomp
|
||||
htop.1
|
||||
pcp-htop.5
|
||||
install-sh
|
||||
libtool
|
||||
ltmain.sh
|
||||
|
||||
@ -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
|
||||
|
||||
61
htop.1.in
61
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.
|
||||
|
||||
237
pcp-htop.5.in
Normal file
237
pcp-htop.5.in
Normal 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.
|
||||
Loading…
Reference in New Issue
Block a user