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