mirror of https://github.com/xzeldon/htop.git
Merge pull request #705 from natoscott/pcp-htop-manual
docs: updates and new manual page for pcp-htop
This commit is contained in:
commit
9a07ba2700
|
@ -37,6 +37,7 @@ config.sub
|
||||||
configure
|
configure
|
||||||
depcomp
|
depcomp
|
||||||
htop.1
|
htop.1
|
||||||
|
pcp-htop.5
|
||||||
install-sh
|
install-sh
|
||||||
libtool
|
libtool
|
||||||
ltmain.sh
|
ltmain.sh
|
||||||
|
|
|
@ -681,7 +681,7 @@ AM_CONDITIONAL([HTOP_PCP], [test "$my_htop_platform" = pcp])
|
||||||
AM_CONDITIONAL([HTOP_UNSUPPORTED], [test "$my_htop_platform" = unsupported])
|
AM_CONDITIONAL([HTOP_UNSUPPORTED], [test "$my_htop_platform" = unsupported])
|
||||||
|
|
||||||
AC_SUBST(my_htop_platform)
|
AC_SUBST(my_htop_platform)
|
||||||
AC_CONFIG_FILES([Makefile htop.1])
|
AC_CONFIG_FILES([Makefile htop.1 pcp-htop.5])
|
||||||
AC_OUTPUT
|
AC_OUTPUT
|
||||||
|
|
||||||
if test "$my_htop_platform" = unsupported; then
|
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"
|
.TH "HTOP" "1" "2020" "@PACKAGE_STRING@" "User Commands"
|
||||||
.SH "NAME"
|
.SH "NAME"
|
||||||
htop \- interactive process viewer
|
htop, pcp-htop \- interactive process viewer
|
||||||
.SH "SYNOPSIS"
|
.SH "SYNOPSIS"
|
||||||
.B htop
|
.B htop
|
||||||
.RB [ \-dCFhpustvH ]
|
.RB [ \-dCFhpustvH ]
|
||||||
|
.br
|
||||||
|
.B pcp\ htop
|
||||||
|
.RB [ \-dCFhpustvH ]
|
||||||
|
.RB [ \-\-host/-h\ host ]
|
||||||
.SH "DESCRIPTION"
|
.SH "DESCRIPTION"
|
||||||
.B htop
|
.B htop
|
||||||
is a cross-platform ncurses-based process viewer.
|
is a cross-platform ncurses-based process viewer.
|
||||||
|
@ -18,6 +22,19 @@ multiple processes and act on them all at once.
|
||||||
.LP
|
.LP
|
||||||
Tasks related to processes (killing, renicing) can be done without
|
Tasks related to processes (killing, renicing) can be done without
|
||||||
entering their PIDs.
|
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 to extend
|
||||||
|
.B htop
|
||||||
|
to display values from arbitrary metrics.
|
||||||
|
See the section below titled
|
||||||
|
.B "CONFIG FILES"
|
||||||
|
for further details.
|
||||||
.br
|
.br
|
||||||
.SH "COMMAND-LINE OPTIONS"
|
.SH "COMMAND-LINE OPTIONS"
|
||||||
Mandatory arguments to long options are mandatory for short options too.
|
Mandatory arguments to long options are mandatory for short options too.
|
||||||
|
@ -540,7 +557,7 @@ Summary: build time dependency on
|
||||||
C header files, optional runtime dependency on
|
C header files, optional runtime dependency on
|
||||||
.B libsensors(3)
|
.B libsensors(3)
|
||||||
via dynamic loading.
|
via dynamic loading.
|
||||||
.SH "CONFIG FILE"
|
.SH "CONFIG FILES"
|
||||||
By default
|
By default
|
||||||
.B htop
|
.B htop
|
||||||
reads its configuration from the XDG-compliant path
|
reads its configuration from the XDG-compliant path
|
||||||
|
@ -557,6 +574,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
|
You may override the location of the configuration file using the $HTOPRC
|
||||||
environment variable (so you can have multiple configurations for different
|
environment variable (so you can have multiple configurations for different
|
||||||
machines that share the same home directory, for example).
|
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"
|
.SH "MEMORY SIZES"
|
||||||
Memory sizes in
|
Memory sizes in
|
||||||
.B htop
|
.B htop
|
||||||
|
@ -574,7 +621,17 @@ space and make memory size representations consistent throughout
|
||||||
.BR uptime (1)
|
.BR uptime (1)
|
||||||
and
|
and
|
||||||
.BR limits.conf (5).
|
.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"
|
.SH "AUTHORS"
|
||||||
.B htop
|
.B htop
|
||||||
was originally developed by Hisham Muhammad.
|
was originally developed by Hisham Muhammad.
|
||||||
Nowadays it is maintained by the community at <htop@groups.io>.
|
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.
|
||||||
|
|
|
@ -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 user's 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 displayed 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. Blank lines are ignored.
|
||||||
|
Lines starting with the "#" character are treated as comments.
|
||||||
|
.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