diff options
Diffstat (limited to 'pcp-htop.5.in')
| -rw-r--r-- | pcp-htop.5.in | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/pcp-htop.5.in b/pcp-htop.5.in new file mode 100644 index 0000000..ebb4748 --- /dev/null +++ b/pcp-htop.5.in @@ -0,0 +1,237 @@ +.TH "PCP-HTOP" "5" "2024" "@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. |