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