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  the  configuration
17       file described below.  For command line argument details see pmrep(1).
18
19       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 users
22       to create specifically crafted  metricsets  particularly  relevant  for
23       their  application  or environment.  Instead of being dependent on what
24       existing tools provide or collecting the needed data with several  dis‐
25       joint  utilities  users  can define custom metricsets by merely editing
26       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 options.
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       options follows:
46
47           [section]
48           key = value
49           key2 = value2
50
51       The supported value  data  types  are  string,  integer,  and  boolean.
52       String  values need not to be quoted expect when whitespace needs to be
53       included in the value (for instance, for the column separator);  double
54       quotes from quoted strings will be removed.
55
56       A  line comment starts with a hash sign (``#'') or a semicolon (``;'').
57       Inline comments are not supported.
58
59       pmrep.conf must be readable by the user invoking pmrep.
60
61       Any option described below with a  corresponding  command  line  option
62       contains additional description in pmrep(1).
63

SPECIAL SECTIONS

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

CUSTOM SECTIONS

322       Any  other  section than [options] or [global] will be interpreted as a
323       new metricset specification.  The section name is arbitrary,  typically
324       a  reference  to its coverage or purpose.  A custom section can contain
325       options, metricspecs, or both.
326
327       All the metrics specified in a custom section will be reported when pm‐
328       rep  is  instructed to use the particular custom section.  pmrep can be
329       executed with more than one custom section (i.e., metricset) defined in
330       which case the combination of all the metrics specified in them will be
331       reported.
332
333       Section options
334
335           Any option valid in the [options] section is also valid in a custom
336           section.   Any  option or metric defined in the custom section will
337           override the same option or metric possibly defined in  an  earlier
338           section.  See below for the metricspec specification.
339

METRICSET SPECIFICATION

341       There  are three forms of the metricspec.  First, on the command line a
342       metricspec can start with a colon (``:'') to indicate a reference to  a
343       metricset  to  be  read from the pmrep configuration file.  Second, the
344       compact form of a metricspec is a one-line metric  specification  which
345       can  be  used  both  on the command line and in the [global] and custom
346       sections of the configuration file.  The only difference of  its  usage
347       in  the  configuration  file is that the metric name is used as the key
348       and the optional specifiers as values.  The compact form of the metric‐
349       spec  is specified in detail in pmrep(1).  The third, verbose form of a
350       metricspec, is valid only in the configuration file (see below).
351
352       A key containing a dot (``.'') is interpreted as  a  metric  name  (see
353       above),  a  non-option  key  not  containing a dot is interpreted as an
354       identifier (see below).
355
356       The verbose form of a metricspec starts with a  declaration  consisting
357       of  a mandatory identifier as the key and the actual performance metric
358       name (a PMNS leaf node) as its value.  This equals to the compact  form
359       of  the  metricspec defining the same performance metric without any of
360       optional specifiers defined.  The identifier is arbitrary  and  is  not
361       used  otherwise  except for binding the below specifiers and the metric
362       together.
363
364       The following specifiers are optional in the verbose form  and  can  be
365       used  as keys in any order with an earlier declared identifier followed
366       by a dot and the specifier (as in identifier.specifier):
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  later specified formula.  Both of these metrics will be in‐
403       cluded in 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.   Using  the  tab  key on the command line after the colon can be
415       used to complete available 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           allcache = mem.util.allcache
428           allcache.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
429           allcache.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