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_texts (boolean)
202 Indicates that when writing a PCP archive, PCP help texts shall be
203 included in the created archive. Corresponding command line option
204 is --include-texts. Defaults to no.
205 colxrow (string)
207 Indicates to swap columns and rows in stdout output using the given
208 text label. Corresponding command line option is -X. Undefined
209 (no swapping) by default.
210 width (integer)
212 Indicates the width of stdout output columns. Corresponding com‐
213 mand line option is -w. Forced minimum is 3. Defaults to the
214 shortest width that can fit the metric text label.
215 width_force (integer)
217 As width but overrides possible possible per-metric specifications.
218 Corresponding command line option is -W. Forced minimum is 3.
219 precision (integer)
221 Indicates how many decimals to use for numeric non-integer output
222 values. Corresponding command line option is -P. Defaults to 3.
223 precision_force (integer)
225 As precision but overrides possible per-metric specifications.
226 Corresponding command line option is -0. Undefined by default.
227 delimiter (string)
229 Indicates the column separator. Corresponding command line option
230 is -l. Default depends on the output target, see pmrep(1).
231 extcsv (boolean)
233 Indicates whether to write extended CSV output similar to sadf(1).
234 Corresponding command line option is -k. Defaults to no.
235 extheader (boolean)
237 Indicates whether to print extended header. Corresponding command
238 line option is -x. Defaults to no.
239 fixed_header (boolean)
241 Indicates that a fixed header should be used. Corresponding com‐
242 mand line option is -7. Defaults to no.
243 repeat_header (integer)
245 Indicates how often to repeat the header. Corresponding command
246 line option is -E. Defaults to 0.
247 dynamic_header (boolean)
249 Indicates that a dynamic header should be used. Corresponding com‐
250 mand line option is -1. Defaults to no.
251 separate_header (boolean)
253 Indicates whether to print a separate header. Corresponding com‐
254 mand line option is -g. Defaults to no.
255 timefmt (string)
257 Indicates the format string for formatting the timestamp. Corre‐
258 sponding command line option is -f. Defaults to %H:%M:%S.
259 interpol (boolean)
261 Indicates whether to interpolate reported archive values. Corre‐
262 sponding command line option is -u. See pmrep(1) for complete
263 description. Defaults to yes.
264 count_scale (string)
266 Indicates the unit/scale for counter metrics. Corresponding com‐
267 mand line option is -q. For supported syntax, see pmrep(1). Unde‐
268 fined (no scaling) by default.
269 count_scale_force (string)
271 Like count_scale but overrides possible per-metric specifications.
272 Corresponding command line option is -Q. Undefined by default.
273 space_scale (string)
275 Indicates the unit/scale for space metrics. Corresponding command
276 line option is -b. For supported syntax, see pmrep(1). Undefined
277 (no scaling) by default.
278 space_scale_force (string)
280 Like space_scale but overrides possible per-metric specifications.
281 Corresponding command line option is -B. Undefined by default.
282 time_scale (string)
284 Indicates the unit/scale for time metrics. Corresponding command
285 line option is -y. For supported syntax, see pmrep(1). Undefined
286 (no scaling) by default.
287 time_scale_force (string)
289 Like time_scale but overrides possible per-metric specifications.
290 Corresponding command line option is -Y. Undefined by default.
291 The [global] section
293 The [global] section is used to define metrics that will be reported in
294 addition to any other separately defined metrics or metricsets. Con‐
295 figuration options are not allowed in this section. Global metrics are
296 reported by default, the command line option -G or the configuration
297 file option globals can be used to disable global metrics.
298 Section options
300 No predefined options, only metricspecs allowed in this section.
302 See below for the metricspec specification.
303
305 Any other section than [options] or [global] will be interpreted as a
306 new metricset specification. The section name is arbitrary, typically
307 a reference to its coverage or purpose. A custom section can contain
308 options, metricspecs, or both.
309 All the metrics specified in a custom section will be reported when
311 pmrep is instructed to use the particular custom section. pmrep can be
312 executed with more than one custom section (i.e., metricset) defined in
313 which case the combination of all the metrics specified in them will be
314 reported.
315 Section options
317 Any option valid in the [options] section is also valid in a custom
319 section. Any option or metric defined in the custom section will
320 override the same option or metric possibly defined in an earlier
321 section. See below for the metricspec specification.
322
324 There are three forms of the metricspec. First, on the command line a
325 metricspec can start with a colon (``:'') to indicate a reference to a
326 metricset to be read from the pmrep configuration file. Second, the
327 compact form of a metricspec is a one-line metric specification which
328 can be used both on the command line and in the [global] and custom
329 sections of the configuration file. The only difference of its usage
330 in the configuration file is that the metric name is used as the key
331 and the optional specifiers as values. The compact form of the metric‐
332 spec is specified in detail in pmrep(1). The third, verbose form of a
333 metricspec, is valid only in the configuration file (see below).
334 A key containing a dot (``.'') is interpreted as a metric name (see
336 above), a non-option key not containing a dot is interpreted as an
337 identifier (see below).
338 The verbose form of a metricspec starts with a declaration consisting
340 of a mandatory identifier as the key and the actual performance metric
341 name (a PMNS leaf node) as its value. This equals to the compact form
342 of the metricspec defining the same performance metric without any of
343 optional specifiers defined. The identifier is arbitrary and is not
344 used otherwise except for binding the below specifiers and the metric
345 together.
346 The following specifiers are optional in the verbose form and can be
348 used as keys in any order with an earlier declared identifier followed
349 by a dot and the specifier (as in identifier.specifier):
350 label
352 Defines text label for the metric used by supporting output
353 targets.
354 formula
356 Defines the needed arithmetic expression for the metric. For
357 details, see pmRegisterDerived(3).
358 instances
360 Defines the instances to be reported for the metric. For
361 details, see pmrep(1).
362 unit
364 Defines the unit/scale conversion for the metric. Needs to be
365 dimension-compatible and is used with non-string metrics. For
366 allowed values, see pmrep(1).
367 type
369 If set to raw rate conversion for the metric will be disabled.
370 width
372 Defines the width of the output column for the metric.
373 precision
375 Defines precision for numeric non-integer output values.
376 limit
378 Defines value limit filter for numeric metric values.
379
381 The following example contains a short [options] section setting some
382 locally wanted default values. It then goes on to define the global
383 metrics kernel.all.sysfork using the compact form and mem.util.allcache
384 using the verbose form of a metricspec. The latter is a derived metric
385 using the later specified formula. Both of these metrics will be
386 included in reporting unless disabled with -G or globals = no.
387 Three different metricsets are also specified: db1, db2, and sar-w.
389 The DB sets define a host to be used as the source for the metrics.
391 Both use the verbose form of a metricspec (as the non-option key set
392 does not contain the dot) to include all postgresql related metrics.
393 The sar-w set is an example how to mimic an existing tool with pmrep.
395 The system default pmrep.conf file contains many more examples. Using
397 tab after the colon can be used to complete available metricsets (with
398 bash and zsh).
399 [options]
402 timestamp = yes
403 interval = 2s
404 extheader = yes
405 repeat_header = 20
406 space_scale = MB
407 [global]
409 kernel.all.sysfork = forks,,,,8
410 allcache = mem.util.allcache
411 allcache.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
412 allcache.width = 10
413 [db1]
415 source = db-host1.example.com
416 set = postgresql
417 [db2]
419 source = db-host2.example.com
420 set = postgresql
421 [sar-w]
423 header = yes
424 unitinfo = no
425 globals = no
426 timestamp = yes
427 precision = 2
428 delimiter = " "
429 kernel.all.sysfork = proc/s,,,,12
430 kernel.all.pswitch = cswch/s,,,,9
431
434 $PCP_SYSCONF_DIR/pmrep/pmrep.conf
435 system provided pmrep configuration file
436
438 Environment variables with the prefix PCP_ are used to parameterize the
439 file and directory names used by PCP. On each installation, the file
440 /etc/pcp.conf contains the local values for these variables. The
441 $PCP_CONF variable may be used to specify an alternative configuration
442 file, as described in pcp.conf(5).
443 For environment variables affecting PCP tools, see pmGetOptions(3).
445
447 PCPIntro(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3) and pmRegis‐
448 terDerived(3).
449Performance Co-Pilot PCP PMREP.CONF(5)