1PCP-HTOP(5)                      File Formats                      PCP-HTOP(5)
2
3
4

NAME

6       pcp-htop - pcp-htop configuration file
7

DESCRIPTION

9       pcp-htop  is a customizable performance metrics reporting tool.  It has
10       a dynamic architecture, where a set of configuration files provide  ad‐
11       ditional,  optional  meters and columns to extend the fixed set of dis‐
12       play options provided by regular htop.
13
14       These configuration files can be provided from both  system-wide  loca‐
15       tions  (first  /etc/pcp/htop  then  /usr/share/pcp/htop)  and below the
16       user's home directory (usually ~/.config/htop).  Within these locations
17       the  meters and columns are scanned for dynamic Meter and Column speci‐
18       fications.
19
20       Meters are displayed in the top part of the pcp-htop window,  and  col‐
21       umns  are  displayed in the lower part.  Meters tend to display system-
22       wide metrics, and Columns display metrics about individual processes.
23
24       The formats are similar but have slightly different requirements.  Both
25       formats  follow  the  common ini-style. Blank lines are ignored.  Lines
26       starting with the "#" character are treated as comments.
27

METERS

29       The following is an example configuration for a new Redis meter:
30
31            [redisclient]
32            caption = Redis clients
33            type = bar
34            blocked.metric = redis.blocked_clients
35            blocked.color = blue
36            blocked.label = blk
37            clients.metric = redis.connected_clients
38            clients.color = green
39            clients.label = conn
40
41       A configuration file can contain multiple meter definitions.  Each def‐
42       inition  begins  with  a identifying name enclosed by square brackets -
43       redisclient in this example.  The name is used internally  within  pcp-
44       htop  and  must be unique, must begin with an alphabetic character, and
45       may subsequently only contain alphanumeric characters or the underscore
46       character.  No whitespace or other characters are allowed.
47
48       There are several parameters that define the way the meter will be dis‐
49       played to the user.
50
51       caption
52            This value is displayed on the Setup screen  once  the  meter  has
53            been  selected.   A  truncated version of the caption will also be
54            displayed (followed by a colon) on the primary display  while  the
55            meter is updating.
56
57       description
58            This can be used to provide more detail during the meter selection
59            process on the Setup screen, and if present it is displayed in the
60            "Available  Meters"  column.   If not present, the caption will be
61            used for this.  If neither is present,  the  internal  (mandatory)
62            name will be used.
63
64       type This  setting  allows  a preferred default meter type to be speci‐
65            fied.  The associated value must be one of bar,  text,  graph,  or
66            led.   If  no  value  is provided for a dynamic meter, the default
67            value of text will be used.
68
69       maximum
70            A numeric value can also be set to size the meter, such that  val‐
71            ues  (e.g.  for  a  bar  type meter display) will be scaled within
72            range zero to maximum.
73
74       The remaining definition  syntax  describes  the  individual  metric(s)
75       which  will  be used to animate the meter.  One or more metrics must be
76       specified for each meter and there are  several  properties  associated
77       with each.  Once again, these metrics must be named (the same rules de‐
78       scribed above for meters apply here) and the following  properties  can
79       be configured:
80
81       name.metric
82            This  is the only mandatory field and associates a PCP metric with
83            the meter.  Values sampled for each metric at runtime provide  the
84            animation  visible in the pcp-htop display.  The metric specifica‐
85            tion can be either a PCP metric name as listed by pminfo(1)  or  a
86            "derived"  metric  expression.   The format for derived metric ex‐
87            pressions is described on the pmRegisterDerived(3) manual page.
88
89       name.color
90            Setting color to be used when rendering metric  values.   Possible
91            values are red, green, blue, cyan, magenta, yellow, gray, darkgray
92            or white.
93
94       name.label
95            An optional, short label to display before the metric value.   The
96            ":"  character  will  be  appended  to the label before the metric
97            value part of the display.
98
99       name.suffix
100            An optional, short suffix to display after the metric value.  Com‐
101            monly  used  to indicate values as a percentage using a "%" suffix
102            value and to provide the base  unit  of  measurement.   Note  that
103            since PCP maintains units for metrics, for those metrics that have
104            dimension in "space" (bytes, kilobytes, megabytes, etc), a  suffix
105            will be automatically appended.
106

COLUMNS

108       The following is an example configuration for a new column showing open
109       file descriptors for each process:
110
111            [openfds]
112            heading = FDS
113            caption = FDCOUNT
114            description = Open file descriptors
115            metric = proc.fd.count
116            width = 3
117
118       A configuration file can contain  multiple  column  definitions.   Each
119       definition begins with a identifying name enclosed by square brackets -
120       openfds in this example, and the same rules apply  as  described  above
121       for meter names.
122
123       Each  column  must  specify  a metric.  Optional parameters can also be
124       set.
125
126       metric
127            As with meters, the metric value must be either a PCP metric  name
128            as  listed by pminfo(1) or a derived metric.  The metric must have
129            an instance domain (set of values) and that instance  domain  must
130            map  to  the  set  of processes with the instance identifier being
131            PIDs (process identifiers).  Typically this will be  metrics  from
132            the  proc  or  hotproc  namespace  (pmdaproc(1)), but metrics from
133            other domains (pmdabcc(1), pmdabpf(1), etc) that have  per-process
134            values are equally applicable.
135
136       width
137            Column width to use when displaying values for the metric.  A neg‐
138            ative value can be used to specify left alignment.  An upper  col‐
139            umn  limit of 28 characters is enforced.  The default column width
140            is 5 characters.
141
142       heading
143            The short title that will be displayed at the head of the column -
144            usually a short, cryptic, all uppercase string.
145
146       caption
147            A  short  identifying  word presented to users on the Setup screen
148            under both the Available and Active Columns lists.
149
150       description
151            Text that assists users to understand the meaning of  this  column
152            when  it  is being presented via the Setup screen in the Available
153            Columns list.
154

SEE ALSO

156       pcp-htop(1), pminfo(1), pmcd(1),  pmdaproc(1),  pmdabcc(1),  pmdabpf(1)
157       and pmRegisterDerived(3).
158

AUTHORS

160       htop was originally developed by Hisham Muhammad.  Nowadays it is main‐
161       tained by the community at <htop@groups.io>.
162
163       pcp-htop is maintained as a collaboration between the  <htop@groups.io>
164       and  <pcp@groups.io> communities, and forms part of the Performance Co-
165       Pilot suite of tools.
166
167
168
169Performance Co-Pilot                 2022                          PCP-HTOP(5)
Impressum