pmrep.conf(5)

1PMREP.CONF(5)                 File Formats Manual                PMREP.CONF(5)
2
3
4

NAME

6       pmrep.conf - pmrep configuration file
7

DESCRIPTION

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
14       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 configuration  files
17       described below.  For command line argument details see pmrep(1).
18
19       The  pmrep.conf  configuration  file allows for setting default runtime
20       values and defining any number of custom metricsets for pmrep.  A  met‐
21       ricset  is  a  user-defined arbitrary set of performance metrics.  This
22       allows users to create  specifically  crafted  metricsets  particularly
23       relevant for their application or environment.  Instead of being depen‐
24       dent on what existing tools provide or collecting the needed data  with
25       several disjoint utilities users can define custom metricsets by merely
26       editing pmrep.conf.  See below for the metricset specification.
27
28       In case pmrep configuration files are read from a directory then values
29       for the [options] and [global] sections will be combined from each file
30       where defined.  The last definition of a directive  wins,  meaning  the
31       last  definition will be used in case defined multiple times.  However,
32       custom metricset sections will not be combined, only the  last  defini‐
33       tion found will be used for reporting.
34
35       Options  via environment values (see pmGetOptions(3)) override the cor‐
36       responding built-in default values (if any).   Configuration  file  op‐
37       tions  override the corresponding environment variables (if any).  Com‐
38       mand line options override the corresponding configuration file options
39       (if any).
40

FILE FORMAT

42       The file has an ini-style syntax and consists of sections and settings.
43       A section begins with the name of the section in  square  brackets  and
44       continues  until  the next section begins.  An example section with two
45       settings follows:
46
47           [section]
48           key = value
49           key2 = value2
50
51       The supported data types for values are string, integer,  and  boolean.
52       Values should not to be quoted expect when the value consists solely of
53       whitespace (i.e., a whitespace-only column separator).
54
55       A line comment starts with a hash sign (``#'') or a semicolon  (``;'').
56       Inline comments are not supported.
57
58       pmrep.conf must be readable by the user invoking pmrep.
59
60       Any  option  described  below  with a corresponding command line option
61       contains additional functional description in pmrep(1).
62

SPECIAL SECTIONS

64   The [options] section
65       The [options] section is read every time pmrep is run  and  it  defines
66       the  default  runtime options.  These options may be overridden by met‐
67       ricspec specific options or by command line options.  Metrics  are  not
68       allowed in this section.
69
70       Allowed settings
71
72       version (integer)
73           Indicates the configuration file version.  Defaults to 1.  The only
74           currently supported value is 1.
75
76       source (string)
77           Indicates the source for metrics.  Interpreted as a PCP archive  if
78           the  value contains a slash (``/'').  If set to the special charac‐
79           ter ``@'', local DSO PMDA context is used.   Otherwise  interpreted
80           as a hostname.  Corresponding command line paraters are -a, -h, and
81           -L.  Defaults to local: (see PCPIntro(1)).
82
83       output (string)
84           Indicates the output target.  Corresponding command line option  is
85           -o.   For supported output targets, see pmrep(1).  Defaults to std‐
86           out.
87
88       speclocal (string)
89           Indicates the local DSO PMDAs to be made available when  using  the
90           local  DSO  PMDA context.  Corresponding command line option is -K.
91           For syntax description, see pmSpecLocalPMDA(3).   Use  a  semicolon
92           (``;'') to separate more than one spec.  Undefined by default.
93
94       derived (string)
95           Derived  metric  specifications.  Corresponding command line option
96           is -e.  For syntax description, see  pmrep(1).   Undefined  by  de‐
97           fault.
98
99       daemonize (boolean)
100           Indicates  whether  to daemonize on startup.  Corresponding command
101           line option is --daemonize.  Defaults to no.
102
103       header (boolean)
104           Indicates whether to print headers.  Corresponding command line op‐
105           tion is -H.  Defaults to yes.
106
107       instinfo (boolean)
108           Indicates  whether to include instance information as part of head‐
109           ers.  Corresponding command line  option  is  --no-inst-info.   De‐
110           faults to yes.
111
112       unitinfo (boolean)
113           Indicates  whether  to include unit information as part of headers.
114           Corresponding command line option is -U.  Defaults to yes.
115
116       globals (boolean)
117           Indicates whether to include metrics from the [global] section (see
118           below)  for  reporting.   Corresponding  command line option is -G.
119           Defaults to yes.
120
121       timestamp (boolean)
122           Indicates whether to print the  timestamp.   Corresponding  command
123           line option is -p.  Defaults to no.
124
125       samples (integer)
126           Indicates  the  number  of samples to print.  Corresponding command
127           line option is -s.  Undefined by default (meaning unlimited  number
128           of samples if not limited by other options).
129
130       interval (string)
131           Indicates the interval between samples.  Corresponding command line
132           option is -o.  Follows the time syntax  described  in  PCPIntro(1).
133           Defaults to 1s.
134
135       delay (boolean)
136           Indicates  whether  to pause between samples when replaying from an
137           archive rather than replaying at full speed.  Corresponding command
138           line option is -d.  Defaults to no.
139
140       type (string)
141           Indicates whether to output raw metric values by disabling all rate
142           conversions or convert  cumulative  counters  to  rates  (default).
143           Corresponding  command  line  option is -r.  Allowed values are de‐
144           fault or raw.
145
146       type_prefer (string)
147           As type but does not override possible per-metric  type  specifica‐
148           tions.   Corresponding  command  line option is -R.  Allowed values
149           are default or raw.
150
151       ignore_incompat (boolean)
152           Indicates that incompatible metrics are to be ignored.  Correspond‐
153           ing command line option is -I.  Defaults to no.
154
155       ignore_unknown (boolean)
156           Indicates  that  unknown  metrics are to be ignored.  Corresponding
157           command line option is -5.  Defaults to no.
158
159       names_change (string)
160           Indicates the action to take on PMNS changes during sampling.  Cor‐
161           responding command line option is -4.  Defaults to ignore.
162
163       instances (string)
164           Indicates the instances to be reported.  Corresponding command line
165           option is -i.  Undefined (all instances are reported) by default.
166
167       live_filter (boolean)
168           Indicates that live filtering  should  be  enabled.   Corresponding
169           command line option is -j.  Defaults to no.
170
171       rank (integer)
172           Indicates  the value to be used for ranking instances.  Correspond‐
173           ing command line option is -J.  Undefined (all  instances  are  re‐
174           ported) by default.
175
176       overall_rank (boolean)
177           Indicates  that overall ranking should be performed.  Corresponding
178           command line option is -2.  Defaults to no.
179
180       overall_rank_alt (boolean)
181           Indicates that  overall  ranking  with  alternative  output  format
182           should be performed.  Corresponding command line option is -3.  De‐
183           faults to no.
184
185       limit_filter (integer)
186           Indicates the value to be used with limit filtering.  Corresponding
187           command  line option is -8.  Undefined (all instances are reported)
188           by default.
189
190       limit_filter_force (integer)
191           As limit_filter but overrides possible possible per-metric specifi‐
192           cations.   Corresponding command line option is -9.  Undefined (all
193           instances are reported) by default.
194
195       invert_filter (boolean)
196           Indicates that invert filtering should be performed.  Corresponding
197           command line option is -n.  Defaults to no.
198
199       predicate (string)
200           Indicates the metrics to be used as predicate metrics.  Correspond‐
201           ing command line option is -N.  Undefined by default.
202
203       sort_metric (string)
204           Indicates the metrics to be used as sort reference metrics.  Corre‐
205           sponding command line option is -6.  Undefined by default.
206
207       omit_flat (boolean)
208           Indicates  that  single-valued  ``flat''  metrics are to be omitted
209           from reporting.  Corresponding command line option is -v.  Defaults
210           to no.
211
212       include_labels (boolean)
213           Indicates  that  PCP  metric  labels should included in the output.
214           Corresponding command line option is -m.  Defaults to no.
215
216       include_texts (boolean)
217           Indicates that when writing a PCP archive, PCP help texts shall  be
218           included in the created archive.  Corresponding command line option
219           is --include-texts.  Defaults to no.
220
221       colxrow (string)
222           Indicates to swap columns and rows in stdout output using the value
223           as  metric  text  label.   Corresponding command line option is -X.
224           Undefined (no swapping) by default.
225
226       width (integer)
227           Indicates the width of stdout output columns.   Corresponding  com‐
228           mand  line  option  is  -w.   Forced minimum is 3.  Defaults to the
229           shortest width that can fit the metric text label.
230
231       width_force (integer)
232           As width but overrides possible possible per-metric specifications.
233           Corresponding command line option is -W.  Forced minimum is 3.
234
235       precision (integer)
236           Indicates  how  many decimals to use for numeric non-integer output
237           values.  Corresponding command line option is -P.  Defaults to 3.
238
239       precision_force (integer)
240           As precision  but  overrides  possible  per-metric  specifications.
241           Corresponding command line option is -0.  Undefined by default.
242
243       delimiter (string)
244           Indicates  the column separator.  Corresponding command line option
245           is -l.  Default depends on the output target, see pmrep(1).
246
247       extcsv (boolean)
248           Indicates whether to write extended CSV output similar to  sadf(1).
249           Corresponding command line option is -k.  Defaults to no.
250
251       extheader (boolean)
252           Indicates  whether to print extended header.  Corresponding command
253           line option is -x.  Defaults to no.
254
255       fixed_header (boolean)
256           Indicates that a fixed header should be used.   Corresponding  com‐
257           mand line option is -7.  Defaults to no.
258
259       repeat_header (integer)
260           Indicates  how  often  to repeat the header.  Corresponding command
261           line option is -E.  auto  uses  terminal  height.   Defaults  to  0
262           (header is not repeated).
263
264       dynamic_header (boolean)
265           Indicates that a dynamic header should be used.  Corresponding com‐
266           mand line option is -1.  Defaults to no.
267
268       separate_header (boolean)
269           Indicates whether to print a separate header.   Corresponding  com‐
270           mand line option is -g.  Defaults to no.
271
272       timefmt (string)
273           Indicates  the  format string for formatting the timestamp.  Corre‐
274           sponding command line option is -f.  Defaults to %H:%M:%S.
275
276       interpol (boolean)
277           Indicates whether to interpolate reported archive  values.   Corre‐
278           sponding  command line option is -u.  See pmrep(1) for complete de‐
279           scription.  Defaults to yes.
280
281       count_scale (string)
282           Indicates the unit/scale for counter metrics.   Corresponding  com‐
283           mand line option is -q.  For supported syntax, see pmrep(1).  Unde‐
284           fined (no scaling) by default.
285
286       count_scale_force (string)
287           Like count_scale but overrides possible per-metric  specifications.
288           Corresponding command line option is -Q.  Undefined by default.
289
290       space_scale (string)
291           Indicates  the unit/scale for space metrics.  Corresponding command
292           line option is -b.  For supported syntax, see pmrep(1).   Undefined
293           (no scaling) by default.
294
295       space_scale_force (string)
296           Like  space_scale but overrides possible per-metric specifications.
297           Corresponding command line option is -B.  Undefined by default.
298
299       time_scale (string)
300           Indicates the unit/scale for time metrics.   Corresponding  command
301           line  option is -y.  For supported syntax, see pmrep(1).  Undefined
302           (no scaling) by default.
303
304       time_scale_force (string)
305           Like time_scale but overrides possible  per-metric  specifications.
306           Corresponding command line option is -Y.  Undefined by default.
307
308   The [global] section
309       The [global] section is used to define metrics that will be reported in
310       addition to any other separately defined metric or metricset.  Configu‐
311       ration options are not allowed in this section.  Global metrics are re‐
312       ported by default, the command line option -G or the configuration file
313       option globals can be used to disable global metrics.
314
315       Allowed settings
316
317           Only  metricspecs  are  allowed in this section.  See below for the
318           metricspec specification.
319

CUSTOM SECTIONS

321       Any other section than [options] or [global] will be interpreted  as  a
322       new  metricset specification.  The section name is arbitrary, typically
323       a reference to its coverage or purpose.  A custom section  may  contain
324       options, metricspecs, or both.
325
326       All  the  metrics specified in a custom section (metricset) will be re‐
327       ported when pmrep reports that particular  metricset.   More  than  one
328       metricset  (custom section) can be defined on the command line in which
329       case pmrep reports the combination of all the metrics specified in  the
330       selected metricsets.
331
332       Allowed settings
333
334           Any option valid in the [options] section is also valid in a custom
335           section.  Any option or metric defined in  a  custom  section  will
336           override  the  same option or metric possibly defined earlier.  See
337           below for the metricspec specification.
338

METRICSET SPECIFICATION

340       There are three forms of the metricspec.  First, on the command line  a
341       metricspec  can start with a colon (``:'') to indicate a reference to a
342       metricset (custom section) to be read from a pmrep configuration  file.
343       Second,  the compact form of a metricspec is a one-line metric specifi‐
344       cation which can be used both on the command line and in  the  [global]
345       and  custom sections of the configuration file.  The only difference of
346       its usage in the configuration file is that the metric name is used  as
347       the key and the optional specifiers as values.  The compact form of the
348       metricspec is specified in detail in pmrep(1).  The third, verbose form
349       of a metricspec, is valid only in the configuration file (see below).
350
351       In  a custom section a key containing a dot (``.'') is interpreted as a
352       metric name and a non-option key not containing a dot is interpreted as
353       an  identifier  (handle)  to  bind  related declarations together.  The
354       identifier is arbitrary and is not used otherwise  except  for  binding
355       the below specifiers and the metric together.
356
357       The  verbose  form of a metricspec starts with a declaration consisting
358       of a mandatory identifier as the key and a performance metric  name  (a
359       PMNS  node)  as its value.  This equals to the compact form of the met‐
360       ricspec defining the same performance metric without  any  of  the  op‐
361       tional specifiers defined.
362
363       The  following  specifiers  are optional in the verbose form and can be
364       used as keys in any order with an earlier declared identifier  followed
365       by  a dot and the specifier (as in identifier.specifier).  See also the
366       example later below.
367
368              label
369                Defines text label for the metric used  by  supporting  output
370                targets.
371
372              formula
373                Defines  the needed arithmetic expression for the metric.  For
374                details, see pmRegisterDerived(3).
375
376              instances
377                Defines the instances to be reported for the metric.  For  de‐
378                tails, see pmrep(1).
379
380              unit
381                Defines the unit/scale conversion for the metric.  Needs to be
382                dimension-compatible and is used with non-string metrics.  For
383                allowed values, see pmrep(1).
384
385              type
386                If set to raw rate conversion for the metric will be disabled.
387
388              width
389                Defines the width of the output column for the metric.
390
391              precision
392                Defines precision for numeric non-integer output values.
393
394              limit
395                Defines value limit filter for numeric metric values.
396

EXAMPLE

398       The  following  example contains a short [options] section setting some
399       locally wanted default values.  It then goes on to  define  the  global
400       metrics kernel.all.sysfork using the compact form and mem.util.allcache
401       using the verbose form of a metricspec.  The latter is a derived metric
402       using the specified formula.  Both of these metrics will be included in
403       reporting unless disabled with -G or globals = no.
404
405       Three different metricsets are also specified: db1, db2, and sar-w.
406
407       The DB sets define a host to be used as the  source  for  the  metrics.
408       Both  use  the  verbose form of a metricspec (as the non-option key set
409       does not contain the dot) to include all postgresql related metrics.
410
411       The sar-w set is an example how to mimic an existing tool with pmrep.
412
413       The system default pmrep configuration files contain  many  more  exam‐
414       ples.   The  tab key on the command line after a colon completes avail‐
415       able metricsets (with bash and zsh).
416
417
418           [options]
419           timestamp = yes
420           interval = 2s
421           extheader = yes
422           repeat_header = auto
423           space_scale = MB
424
425           [global]
426           kernel.all.sysfork = forks,,,,8
427           cacheall = mem.util.allcache
428           cacheall.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
429           cacheall.width = 12
430
431           [db1]
432           source = db-host1.example.com
433           set = postgresql
434
435           [db2]
436           source = db-host2.example.com
437           set = postgresql
438
439           [sar-w]
440           header = yes
441           unitinfo = no
442           globals = no
443           timestamp = yes
444           precision = 2
445           delimiter = " "
446           kernel.all.sysfork = proc/s,,,,12
447           kernel.all.pswitch = cswch/s,,,,9
448
449

FILES

451       $PCP_SYSCONF_DIR/pmrep/*.conf
452              system provided default pmrep configuration files
453

PCP ENVIRONMENT

455       Environment variables with the prefix PCP_ are used to parameterize the
456       file  and  directory names used by PCP.  On each installation, the file
457       /etc/pcp.conf contains the  local  values  for  these  variables.   The
458       $PCP_CONF  variable may be used to specify an alternative configuration
459       file, as described in pcp.conf(5).
460
461       For environment variables affecting PCP tools, see pmGetOptions(3).
462