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
16 pre-defined performance metricsets to be read from the configuration
17 file 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 Options via environment values (see pmGetOptions(3)) override the cor‐
29 responding built-in default values (if any). Configuration file
30 options override the corresponding environment variables (if any).
31 Command line options override the corresponding configuration file
32 options (if any).
33
35 The file has an ini-style syntax and consists of sections and options.
36 A section begins with the name of the section in square brackets and
37 continues until the next section begins. An example section with two
38 options follows:
39 [section]
41 key = value
42 key2 = value2
43 The supported value data types are string, integer, and boolean.
45 String values need not to be quoted expect when whitespace needs to be
46 included in the value (for instance, for the column separator); double
47 quotes from quoted strings will be removed.
48 A line comment starts with a hash sign (``#'') or a semicolon (``;'').
50 Inline comments are not supported.
51 pmrep.conf must be readable by the user invoking pmrep.
53 Any option described below with a corresponding command line option
55 contains additional description in pmrep(1).
56
58 The [options] section
59 The [options] section is read every time pmrep is run and it defines
60 the default runtime values (which may be overridden by the correspond‐
61 ing command line options). Metric specifications are not allowed in
62 this section.
63 Section options
65 version (integer)
67 Indicates the configuration file version. Defaults to 1. The only
68 currently supported value is 1.
69 source (string)
71 Indicates the source for metrics. Interpreted as a PCP archive if
72 the string contains a slash (``/''). If set to the special charac‐
73 ter ``@'', local DSO PMDA context is used. Otherwise interpreted
74 as a hostname. Corresponding command line paraters are -a, -h, and
75 -L. Defaults to local: (see PCPIntro(1)).
76 output (string)
78 Indicates the output target. Corresponding command line option is
79 -o. For supported output targets, see pmrep(1). Defaults to std‐
80 out.
81 speclocal (string)
83 Indicates the local DSO PMDAs to be made available when using the
84 local DSO PMDA context. Corresponding command line option is -K.
85 For syntax description, see pmSpecLocalPMDA(3). Use a semicolon
86 (``;'') to separate more than one spec. Undefined by default.
87 derived (string)
89 Derived metric specifications. Corresponding command line option
90 is -e. For syntax description, see pmrep(1). Undefined by
91 default.
92 daemonize (boolean)
94 Indicates whether to daemonize on startup. Corresponding command
95 line option is --daemonize. Defaults to no.
96 header (boolean)
98 Indicates whether to print headers. Corresponding command line
99 option is -H. Defaults to yes.
100 unitinfo (boolean)
102 Indicates whether to include unit information as part of headers.
103 Corresponding command line option is -U. Defaults to yes.
104 globals (boolean)
106 Indicates whether to include metrics from the [global] section (see
107 below) for reporting. Corresponding command line option is -G.
108 Defaults to yes.
109 timestamp (boolean)
111 Indicates whether to print the timestamp. Corresponding command
112 line option is -p. Defaults to no.
113 samples (integer)
115 Indicates the number of samples to print. Corresponding command
116 line option is -s. Undefined by default (meaning unlimited number
117 of samples if not limited by other options).
118 interval (string)
120 Indicates the interval between samples. Corresponding command line
121 option is -o. Follows the time syntax described in PCPIntro(1).
122 Defaults to 1s.
123 delay (boolean)
125 Indicates whether to pause between samples when replaying from an
126 archive rather than replaying at full speed. Corresponding command
127 line option is -d. Defaults to no.
128 type (string)
130 Indicates whether to output raw metric values by disabling all rate
131 conversions or convert cumulative counters to rates (default).
132 Corresponding command line option is -r. Allowed values are
133 default or raw.
134 type_prefer (string)
136 As type but does not override possible per-metric type specifica‐
137 tions. Corresponding command line option is -R. Allowed values
138 are default or raw.
139 ignore_incompat (boolean)
141 Indicates that incompatible metrics are to be ignored. Correspond‐
142 ing command line option is -I. Defaults to no.
143 ignore_unknown (boolean)
145 Indicates that unknown metrics are to be ignored. Corresponding
146 command line option is -5. Defaults to no.
147 names_change (string)
149 Indicates the action to take on PMNS changes during sampling. Cor‐
150 responding command line option is -4. Defaults to ignore.
151 instances (string)
153 Indicates the instances to be reported. Corresponding command line
154 option is -i. Undefined (all instances are reported) by default.
155 live_filter (boolean)
157 Indicates that live filtering should be enabled. Corresponding
158 command line option is -j. Defaults to no.
159 rank (integer)
161 Indicates the value to be used for ranking instances. Correspond‐
162 ing command line option is -J. Undefined (all instances are
163 reported) by default.
164 overall_rank (boolean)
166 Indicates that overall ranking should be performed. Corresponding
167 command line option is -2. Defaults to no.
168 overall_rank_alt (boolean)
170 Indicates that overall ranking with alternative output format
171 should be performed. Corresponding command line option is -3.
172 Defaults to no.
173 limit_filter (integer)
175 Indicates the value to be used with limit filtering. Corresponding
176 command line option is -8. Undefined (all instances are reported)
177 by default.
178 limit_filter_force (integer)
180 As limit_filter but overrides possible possible per-metric specifi‐
181 cations. Corresponding command line option is -9. Undefined (all
182 instances are reported) by default.
183 invert_filter (boolean)
185 Indicates that invert filtering should be performed. Corresponding
186 command line option is -n. Defaults to no.
187 predicate (string)
189 Indicates the metrics to be used as predicate metrics. Correspond‐
190 ing command line option is -N. Undefined by default.
191 sort_metric (string)
193 Indicates the metrics to be used as sort reference metrics. Corre‐
194 sponding command line option is -6. Undefined by default.
195 omit_flat (boolean)
197 Indicates that single-valued ``flat'' metrics are to be omitted
198 from reporting. Corresponding command line option is -v. Defaults
199 to no.
200 include_labels (boolean)
202 Indicates that metric labels should included in the output. Corre‐
203 sponding command line option is -m. Defaults to no.
204 include_texts (boolean)
206 Indicates that when writing a PCP archive, PCP help texts shall be
207 included in the created archive. Corresponding command line option
208 is --include-texts. Defaults to no.
209 colxrow (string)
211 Indicates to swap columns and rows in stdout output using the given
212 text label. Corresponding command line option is -X. Undefined
213 (no swapping) by default.
214 width (integer)
216 Indicates the width of stdout output columns. Corresponding com‐
217 mand line option is -w. Forced minimum is 3. Defaults to the
218 shortest width that can fit the metric text label.
219 width_force (integer)
221 As width but overrides possible possible per-metric specifications.
222 Corresponding command line option is -W. Forced minimum is 3.
223 precision (integer)
225 Indicates how many decimals to use for numeric non-integer output
226 values. Corresponding command line option is -P. Defaults to 3.
227 precision_force (integer)
229 As precision but overrides possible per-metric specifications.
230 Corresponding command line option is -0. Undefined by default.
231 delimiter (string)
233 Indicates the column separator. Corresponding command line option
234 is -l. Default depends on the output target, see pmrep(1).
235 extcsv (boolean)
237 Indicates whether to write extended CSV output similar to sadf(1).
238 Corresponding command line option is -k. Defaults to no.
239 extheader (boolean)
241 Indicates whether to print extended header. Corresponding command
242 line option is -x. Defaults to no.
243 fixed_header (boolean)
245 Indicates that a fixed header should be used. Corresponding com‐
246 mand line option is -7. Defaults to no.
247 repeat_header (integer)
249 Indicates how often to repeat the header. Corresponding command
250 line option is -E. Defaults to 0.
251 dynamic_header (boolean)
253 Indicates that a dynamic header should be used. Corresponding com‐
254 mand line option is -1. Defaults to no.
255 separate_header (boolean)
257 Indicates whether to print a separate header. Corresponding com‐
258 mand line option is -g. Defaults to no.
259 timefmt (string)
261 Indicates the format string for formatting the timestamp. Corre‐
262 sponding command line option is -f. Defaults to %H:%M:%S.
263 interpol (boolean)
265 Indicates whether to interpolate reported archive values. Corre‐
266 sponding command line option is -u. See pmrep(1) for complete
267 description. Defaults to yes.
268 count_scale (string)
270 Indicates the unit/scale for counter metrics. Corresponding com‐
271 mand line option is -q. For supported syntax, see pmrep(1). Unde‐
272 fined (no scaling) by default.
273 count_scale_force (string)
275 Like count_scale but overrides possible per-metric specifications.
276 Corresponding command line option is -Q. Undefined by default.
277 space_scale (string)
279 Indicates the unit/scale for space metrics. Corresponding command
280 line option is -b. For supported syntax, see pmrep(1). Undefined
281 (no scaling) by default.
282 space_scale_force (string)
284 Like space_scale but overrides possible per-metric specifications.
285 Corresponding command line option is -B. Undefined by default.
286 time_scale (string)
288 Indicates the unit/scale for time metrics. Corresponding command
289 line option is -y. For supported syntax, see pmrep(1). Undefined
290 (no scaling) by default.
291 time_scale_force (string)
293 Like time_scale but overrides possible per-metric specifications.
294 Corresponding command line option is -Y. Undefined by default.
295 The [global] section
297 The [global] section is used to define metrics that will be reported in
298 addition to any other separately defined metrics or metricsets. Con‐
299 figuration options are not allowed in this section. Global metrics are
300 reported by default, the command line option -G or the configuration
301 file option globals can be used to disable global metrics.
302 Section options
304 No predefined options, only metricspecs allowed in this section.
306 See below for the metricspec specification.
307
309 Any other section than [options] or [global] will be interpreted as a
310 new metricset specification. The section name is arbitrary, typically
311 a reference to its coverage or purpose. A custom section can contain
312 options, metricspecs, or both.
313 All the metrics specified in a custom section will be reported when
315 pmrep is instructed to use the particular custom section. pmrep can be
316 executed with more than one custom section (i.e., metricset) defined in
317 which case the combination of all the metrics specified in them will be
318 reported.
319 Section options
321 Any option valid in the [options] section is also valid in a custom
323 section. Any option or metric defined in the custom section will
324 override the same option or metric possibly defined in an earlier
325 section. See below for the metricspec specification.
326
328 There are three forms of the metricspec. First, on the command line a
329 metricspec can start with a colon (``:'') to indicate a reference to a
330 metricset to be read from the pmrep configuration file. Second, the
331 compact form of a metricspec is a one-line metric specification which
332 can be used both on the command line and in the [global] and custom
333 sections of the configuration file. The only difference of its usage
334 in the configuration file is that the metric name is used as the key
335 and the optional specifiers as values. The compact form of the metric‐
336 spec is specified in detail in pmrep(1). The third, verbose form of a
337 metricspec, is valid only in the configuration file (see below).
338 A key containing a dot (``.'') is interpreted as a metric name (see
340 above), a non-option key not containing a dot is interpreted as an
341 identifier (see below).
342 The verbose form of a metricspec starts with a declaration consisting
344 of a mandatory identifier as the key and the actual performance metric
345 name (a PMNS leaf node) as its value. This equals to the compact form
346 of the metricspec defining the same performance metric without any of
347 optional specifiers defined. The identifier is arbitrary and is not
348 used otherwise except for binding the below specifiers and the metric
349 together.
350 The following specifiers are optional in the verbose form and can be
352 used as keys in any order with an earlier declared identifier followed
353 by a dot and the specifier (as in identifier.specifier):
354 label
356 Defines text label for the metric used by supporting output
357 targets.
358 formula
360 Defines the needed arithmetic expression for the metric. For
361 details, see pmRegisterDerived(3).
362 instances
364 Defines the instances to be reported for the metric. For
365 details, see pmrep(1).
366 unit
368 Defines the unit/scale conversion for the metric. Needs to be
369 dimension-compatible and is used with non-string metrics. For
370 allowed values, see pmrep(1).
371 type
373 If set to raw rate conversion for the metric will be disabled.
374 width
376 Defines the width of the output column for the metric.
377 precision
379 Defines precision for numeric non-integer output values.
380 limit
382 Defines value limit filter for numeric metric values.
383
385 The following example contains a short [options] section setting some
386 locally wanted default values. It then goes on to define the global
387 metrics kernel.all.sysfork using the compact form and mem.util.allcache
388 using the verbose form of a metricspec. The latter is a derived metric
389 using the later specified formula. Both of these metrics will be
390 included in reporting unless disabled with -G or globals = no.
391 Three different metricsets are also specified: db1, db2, and sar-w.
393 The DB sets define a host to be used as the source for the metrics.
395 Both use the verbose form of a metricspec (as the non-option key set
396 does not contain the dot) to include all postgresql related metrics.
397 The sar-w set is an example how to mimic an existing tool with pmrep.
399 The system default pmrep.conf file contains many more examples. Using
401 tab after the colon can be used to complete available metricsets (with
402 bash and zsh).
403 [options]
406 timestamp = yes
407 interval = 2s
408 extheader = yes
409 repeat_header = 20
410 space_scale = MB
411 [global]
413 kernel.all.sysfork = forks,,,,8
414 allcache = mem.util.allcache
415 allcache.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
416 allcache.width = 10
417 [db1]
419 source = db-host1.example.com
420 set = postgresql
421 [db2]
423 source = db-host2.example.com
424 set = postgresql
425 [sar-w]
427 header = yes
428 unitinfo = no
429 globals = no
430 timestamp = yes
431 precision = 2
432 delimiter = " "
433 kernel.all.sysfork = proc/s,,,,12
434 kernel.all.pswitch = cswch/s,,,,9
435
438 $PCP_SYSCONF_DIR/pmrep/pmrep.conf
439 system provided pmrep configuration file
440
442 Environment variables with the prefix PCP_ are used to parameterize the
443 file and directory names used by PCP. On each installation, the file
444 /etc/pcp.conf contains the local values for these variables. The
445 $PCP_CONF variable may be used to specify an alternative configuration
446 file, as described in pcp.conf(5).
447 For environment variables affecting PCP tools, see pmGetOptions(3).
449
451 PCPIntro(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3) and pmRegis‐
452 terDerived(3).
453Performance Co-Pilot PCP PMREP.CONF(5)