1PCP-HTOP(5) File Formats PCP-HTOP(5)
2
6 pcp-htop - pcp-htop configuration file
7
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 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 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 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
29 The following is an example configuration for a new Redis meter:
30 [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 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 There are several parameters that define the way the meter will be dis‐
49 played to the user.
50 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 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 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 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 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 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 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 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 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
108 The following is an example configuration for a new column showing open
109 file descriptors for each process:
110 [openfds]
112 heading = FDS
113 caption = FDCOUNT
114 description = Open file descriptors
115 metric = proc.fd.count
116 width = 3
117 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 Each column must specify a metric. Optional parameters can also be
124 set.
125 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 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 heading
143 The short title that will be displayed at the head of the column -
144 usually a short, cryptic, all uppercase string.
145 caption
147 A short identifying word presented to users on the Setup screen
148 under both the Available and Active Columns lists.
149 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
156 pcp-htop(1), pminfo(1), pmcd(1), pmdaproc(1), pmdabcc(1), pmdabpf(1)
157 and pmRegisterDerived(3).
158
160 htop was originally developed by Hisham Muhammad. Nowadays it is main‐
161 tained by the community at <htop@groups.io>.
162 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.
166Performance Co-Pilot 2023 PCP-HTOP(5)