1PMREP.CONF(5) File Formats Manual PMREP.CONF(5)
2
6 pmrep.conf - pmrep configuration file
7
9 pmrep is a customizable performance metrics reporting tool. Any avail‐
10 able performance metric, live or archived, system and/or application,
11 can be selected for reporting using one of the available output alter‐
12 natives together with applicable formatting options.
13 The metrics of interest are named in the metricspec argument(s) on the
15 pmrep command line. These metricspecs define individual metrics or pre-
16 defined performance metric sets to be read from the configuration file
17 described below. For command line argument details see pmrep(1).
18 The pmrep.conf configuration file allows setting default runtime values
20 and defining any number of custom metricsets for pmrep. A metricset is
21 a user-defined set of arbitrary performance metrics. This allows the
22 user to create specifically crafted metricsets particularly relevant
23 for their application or environment. Instead of being dependent on
24 what existing tools provide or collecting the needed data with several
25 disjoint utilities the user can create and modify custom metricsets by
26 editing pmrep.conf. See below for the metricset specification.
27 Configuration file parameters override the corresponding built-in
29 default values (if any). Command line parameters override the corre‐
30 sponding configuration file parameters (if any).
31
33 The file has an ini-style syntax and consists of sections and parame‐
34 ters. A section begins with the name of the section in square brackets
35 and continues until the next section begins. An example section with
36 two parameters follows:
37 [section]
39 key = value
40 key2 = value2
41 The data types used are string (no quotes needed), integer, and bool
43 (with values of yes or no).
44 A line comment starts with a hash sign (``#'') or a semicolon (``;'').
46 Inline comments are not supported.
47 pmrep.conf must be readable by the user invoking pmrep.
49 Any parameter described below with a corresponding command line parame‐
51 ter contains additional description in pmrep(1).
52
54 The [options] section
55 The [options] section is read every time pmrep is run and it defines
56 the default runtime values (which may be overridden by the correspond‐
57 ing command line options). Metric specifications are not allowed in
58 this section.
59 Section parameters
61 version (integer)
63 Indicates the configuration file version. Defaults to 1. The only
64 currently supported value is 1.
65 source (string)
67 Indicates the source for metrics. Interpreted as a PCP archive if
68 the string contains a slash (``/''), otherwise interpreted as a
69 hostname. Corresponding command line paraters are -a and -h.
70 Defaults to local: (see PCPIntro(1)).
71 output (string)
73 Indicates the output target. Corresponding command line parameter
74 is -o. For supported output targets, see pmrep(1). Defaults to
75 stdout.
76 derived (string)
78 Derived metric specifications. Corresponding command line parameter
79 is -e. For syntax description, see pmrep(1). Undefined by default.
80 header (bool)
82 Indicates whether to print headers. Corresponding command line
83 parameter is -H. Defaults to yes.
84 unitinfo (bool)
86 Indicates whether to include unit information as part of headers.
87 Corresponding command line parameter is -U. Defaults to yes.
88 globals (bool)
90 Indicates whether to include metrics from the [global] section (see
91 below) for reporting. Corresponding command line parameter is -G.
92 Defaults to yes.
93 timestamp (bool)
95 Indicates whether to print the timestamp. Corresponding command
96 line parameter is -p. Defaults to no.
97 samples (integer)
99 Indicates the number of samples to print. Corresponding command
100 line parameter is -s. Undefined by default (meaning unlimited num‐
101 ber of samples if not limited by other options).
102 interval (string)
104 Indicates the interval between samples. Corresponding command line
105 parameter is -o. Follows the time syntax described in PCPIntro(1).
106 Defaults to 1s.
107 delay (bool)
109 Indicates whether to pause between samples when replaying from an
110 archive rather than replaying at full speed. Corresponding command
111 line parameter is -d. Defaults to no.
112 type (string)
114 Indicates whether to output raw metric values by disabling all rate
115 conversions or convert cumulative counters to rates (default).
116 Corresponding command line parameter is -r. Allowed values are
117 default or raw.
118 width (integer)
120 Indicates the width of stdout output columns. Corresponding command
121 line parameter is -w. Forced minimum is 3. Defaults to the shortest
122 width that can fit the metric label.
123 precision (integer)
125 Indicates how many decimals to use for numeric non-integer output
126 values. Corresponding command line parameter is -P. Defaults to 3.
127 delimiter (string)
129 Indicates the column separator. Corresponding command line parame‐
130 ter is -l. Default depends on the output target, see pmrep(1).
131 extheader (bool)
133 Indicates whether to print extended header. Corresponding command
134 line parameter is -x. Defaults to no.
135 repeat_header (integer)
137 Indicates how often to repeat the header. Corresponding command
138 line parameter is -E. Defaults to 0.
139 timefmt (string)
141 Indicates the format string for formatting the timestamp. Corre‐
142 sponding command line parameter is -f. Defaults to %H:%M:%S.
143 interpol (bool)
145 Indicates whether to interpolate reported archive values. Corre‐
146 sponding command line parameter is -u. See pmrep(1) for complete
147 description. Defaults to yes.
148 count_scale (string)
150 Indicates the unit/scale for counter metrics. Corresponding command
151 line parameter is -q. For supported syntax, see pmrep(1). Unde‐
152 fined (no scaling) by default.
153 space_scale (string)
155 Indicates the unit/scale for space metrics. Corresponding command
156 line parameter is -b. For supported syntax, see pmrep(1). Unde‐
157 fined (no scaling) by default.
158 time_scale (string)
160 Indicates the unit/scale for time metrics. Corresponding command
161 line parameter is -y. For supported syntax, see pmrep(1). Unde‐
162 fined (no scaling) by default.
163 Output target specific parameters
165 The following parameters are also accepted in the [options] section
167 but are typically used only in custom sections as they are applica‐
168 ble only to certain output targets.
169 zabbix_server (string) (zabbix output target only)
171 Hostname or IP address of Zabbix server to send the metrics to. If
172 a host is monitored by a proxy, proxy hostname or IP address should
173 be used instead. Undefined by default.
174 zabbix_port (integer) (zabbix output target only)
176 Specify port number of server trapper running on the server.
177 Default is 10051.
178 zabbix_host (string) (zabbix output target only)
180 Specify agent hostname as registered in Zabbix frontend. Host IP
181 address and DNS name will not work. Undefined by default.
182 zabbix_interval (string) (zabbix output target only)
184 Indicates the interval to send the metrics to the Zabbix server.
185 This can be longer than the generic interval to minimize the over‐
186 head when communicating with the server (as each send creates a new
187 connection). Follows the time syntax described in PCPIntro(1).
188 Defaults to the generic interval. Zabbix tools send at most 250
189 metrics at a time. Ignored when reading metrics from PCP archives,
190 in which case metrics will be sent roughly at 250 metric batches.
191 The [global] section
193 The [global] section is used to define metrics that will be reported in
194 addition to any other separately defined metrics or metricsets. Config‐
195 uration parameters are not allowed in this section. Global metrics are
196 reported by default, the command line option -G or the configuration
197 file parameter globals can be used to disable global metrics.
198 Section parameters
200 No predefined parameters, only metricspecs allowed in this section.
202 See below for the metricspec specification.
203
205 Any other section than [options] or [global] will be interpreted as a
206 new metricset specification. The section name is arbitrary, typically a
207 reference to its coverage or purpose. A custom section can contain
208 options, metricspecs, or both.
209 All the metrics specified in a custom section will be reported when
211 pmrep is instructed to use the particular custom section. pmrep can be
212 executed with more than one custom section (i.e., metricset) defined in
213 which case the combination of all the metrics specified in them will be
214 reported.
215 Section parameters
217 Any option valid in the [options] section is also valid in a custom
219 section. Any option or metric defined in the custom section will
220 override the same option or metric possibly defined earlier in the
221 [options] section. See below for the metricspec specification.
222
224 There are three forms of the metricspec. First, on the command line a
225 metricspec can start with a colon (``:'') to indicate a reference to a
226 metricset to be read from the pmrep configuration file. Second, the
227 compact form of a metricspec is a one-line metric specification which
228 can be used both on the command line and in the [global] and custom
229 sections of the configuration file. The only difference of its usage
230 in the configuration file is that the metric name is used as the key
231 and the optional specifiers as values. The compact form of the metric‐
232 spec is specified in detail in pmrep(1). The third, verbose form of a
233 metricspec is valid only in the configuration file.
234 A key containing a dot (``.'') is interpreted as a metric name (see
236 above), a non-option key not containing a dot is interpreted as an
237 identifier (see below).
238 The verbose form of a metricspec starts with a declaration consisting
240 of a mandatory identifier as the key and the actual performance metric
241 name (a PMNS leaf node) as its value. This equals to the compact form
242 of the metricspec defining the same performance metric without any of
243 optional specifiers defined. The identifier is arbitrary and is not
244 used otherwise except for binding the below specifiers and the metric
245 together.
246 The following specifiers are optional in the verbose form and can be
248 used as keys in any order with an earlier declared identifier followed
249 by a dot and the specifier (as in identifier.specifier):
250 label
252 Defines a text label for the metric used by supporting output
253 targets.
254 formula
256 Defines the needed arithmetic expression for the metric. For
257 details see pmRegisterDerived(3).
258 instance
260 This specifier is currently recognized but not implemented.
261 unit
263 Defines the unit/scale conversion for the metric. Needs to be
264 dimension-compatible and is used with non-string and (cur‐
265 rently) non-raw metrics. For allowed values, see pmrep(3).
266 type
268 If set to raw rate conversion for the metric will be disabled.
269 width
271 Defines the width of the output column for the metric.
272
274 The following example contains a short [options] section setting some
275 locally wanted default values. It then goes on to define the global
276 metrics kernel.all.sysfork using the compact form and mem.util.allcache
277 using the verbose form of a metricspec. The latter is a derived metric
278 using the later specified formula. Both of these metrics will be
279 included in reporting unless disabled with -G or globals = no.
280 Three different metricsets are also specified: db1, db2, and sar-w.
282 The DB sets define a host to be used as the source for the metrics.
284 Both use the verbose form of a metricspec (as the non-option key set
285 does not contain the dot) to include all postgresql related metrics.
286 The sar-w set is an example how to mimic an existing tool with pmrep.
288 [options]
290 timestamp = yes
291 interval = 2s
292 extheader = yes
293 repeat_header = 20
294 space_scale = MB
295 [global]
297 kernel.all.sysfork = forks,,,,8
298 allcache = mem.util.allcache
299 allcache.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
300 [db1]
302 source = db-host1.example.com
303 set = postgresql
304 [db2]
306 source = db-host2.example.com
307 set = postgresql
308 [sar-w]
310 header = yes
311 unitinfo = no
312 globals = no
313 timestamp = yes
314 interval = 1s
315 extheader = no
316 precision = 2
317 sysfork = kernel.all.sysfork
318 sysfork.label = proc/s
319 sysfork.width = 11
320 pswitch = kernel.all.pswitch
321 pswitch.label = cswch/s
322 pswitch.width = 8
323
326 ./pmrep.conf
327 Default configuration file.
328
330 PCPIntro(1), pmrep(1), pmRegisterDerived(3) and zbxpcp(3).
331Performance Co-Pilot PCP PMREP.CONF(5)