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