Ubuntu Manpage: pmrep.conf - pmrep configuration file

NAME

       pmrep.conf - pmrep configuration file

DESCRIPTION

pmrep is a customizable performance metrics reporting tool. Any available performance metric, live or
archived, system and/or application, can be selected for reporting using one of the available output
alternatives together with applicable formatting options.

The metrics of interest are named in the metricspec argument(s) on the pmrep command line. These
metricspecs define individual metrics or pre-defined performance metricsets to be read from configuration
files described below. For command line argument details see pmrep(1).

The pmrep.conf configuration file allows for setting default runtime values and defining any number of
custom metricsets for pmrep. A metricset is a user-defined arbitrary set of performance metrics. This
allows users to create specifically crafted metricsets particularly relevant for their application or
environment. Instead of being dependent on what existing tools provide or collecting the needed data
with several disjoint utilities users can define custom metricsets by merely editing pmrep.conf. See
below for the metricset specification.

In case pmrep configuration files are read from a directory then values for the [options] and [global]
sections will be combined from each file where defined. The last definition of a directive wins, meaning
the last definition will be used in case defined multiple times. However, custom metricset sections will
not be combined, only the last definition found will be used for reporting.

Options via environment values (see pmGetOptions(3)) override the corresponding built-in default values
(if any). Configuration file options override the corresponding environment variables (if any). Command
line options override the corresponding configuration file options (if any).

FILE FORMAT

       The  file  has an ini-style syntax and consists of sections and settings.  A section begins with the name
       of the section in square brackets and continues until the next section begins.  An example  section  with
       two settings follows:

           [section]
           key = value
           key2 = value2

       The  supported  data  types  for values are string, integer, and boolean.  Values should not to be quoted
       expect when the value consists solely of whitespace (i.e., a whitespace-only column separator).

       A line comment starts with a hash  sign  (``#'')  or  a  semicolon  (``;'').   Inline  comments  are  not
       supported.

       pmrep.conf must be readable by the user invoking pmrep.

       Any  option  described  below  with  a  corresponding  command line option contains additional functional
       description in pmrep(1).

SPECIAL SECTIONS

   The [options] section
       The [options] section is read every time pmrep is run and it defines the default runtime options.   These
       options  may  be  overridden  by metricspec specific options or by command line options.  Metrics are not
       allowed in this section.

       Allowed settings

       version (integer)
           Indicates the configuration file version.  Defaults to 1.  The only currently supported value is 1.

       source (string)
           Indicates the source for metrics.  Interpreted as a  PCP  archive  if  the  value  contains  a  slash
           (``/'').   If  set  to  the  special  character  ``@'',  local  DSO  PMDA context is used.  Otherwise
           interpreted as a hostname.  Corresponding command line parameters are -a, -h, and  -L.   Defaults  to
           local: (see PCPIntro(1)).

       output (string)
           Indicates the output target.  Corresponding command line option is -o.  For supported output targets,
           see pmrep(1).  Defaults to stdout.

       speclocal (string)
           Indicates  the  local  DSO  PMDAs  to  be  made  available  when  using  the  local DSO PMDA context.
           Corresponding command line option is -K.  For syntax  description,  see  pmSpecLocalPMDA(3).   Use  a
           semicolon (``;'') to separate more than one spec.  Undefined by default.

       derived (string)
           Derived metric specifications.  Corresponding command line option is -e.  For syntax description, see
           pmrep(1).  Undefined by default.

       daemonize (boolean)
           Indicates  whether  to  daemonize  on  startup.   Corresponding  command  line option is --daemonize.
           Defaults to no.

       header (boolean)
           Indicates whether to print headers.  Corresponding command line option is -H.  Defaults to yes.

       instinfo (boolean)
           Indicates whether to include instance information as part of  headers.   Corresponding  command  line
           option is --no-inst-info.  Defaults to yes.

       unitinfo (boolean)
           Indicates  whether to include unit information as part of headers.  Corresponding command line option
           is -U.  Defaults to yes.

       globals (boolean)
           Indicates  whether  to  include  metrics  from  the  [global]  section  (see  below)  for  reporting.
           Corresponding command line option is -G.  Defaults to yes.

       timestamp (boolean)
           Indicates whether to print the timestamp.  Corresponding command line option is -p.  Defaults to no.

       samples (integer)
           Indicates  the  number  of  samples to print.  Corresponding command line option is -s.  Undefined by
           default (meaning unlimited number of samples if not limited by other options).

       interval (string)
           Indicates the interval between samples.  Corresponding command line option is -o.  Follows  the  time
           syntax described in PCPIntro(1).  Defaults to 1s.

       delay (boolean)
           Indicates  whether  to  pause between samples when replaying from an archive rather than replaying at
           full speed.  Corresponding command line option is -d.  Defaults to no.

       type (string)
           Indicates whether to output raw metric values by disabling all rate conversions or convert cumulative
           counters to rates (default).  Corresponding command line option is -r.  Allowed values are default or
           raw.

       type_prefer (string)
           As type but does not override possible per-metric type specifications.   Corresponding  command  line
           option is -R.  Allowed values are default or raw.

       ignore_incompat (boolean)
           Indicates  that  incompatible  metrics  are  to be ignored.  Corresponding command line option is -I.
           Defaults to no.

       ignore_unknown (boolean)
           Indicates that unknown metrics are to be ignored.  Corresponding command line option is -5.  Defaults
           to no.

       names_change (string)
           Indicates the action to take on PMNS changes during sampling.  Corresponding command line  option  is
           -4.  Defaults to ignore.

       instances (string)
           Indicates  the  instances  to  be reported.  Corresponding command line option is -i.  Undefined (all
           instances are reported) by default.

       live_filter (boolean)
           Indicates that live filtering should be enabled.  Corresponding command line option is -j.   Defaults
           to no.

       rank (integer)
           Indicates  the  value  to  be  used  for ranking instances.  Corresponding command line option is -J.
           Undefined (all instances are reported) by default.

       overall_rank (boolean)
           Indicates that overall ranking should  be  performed.   Corresponding  command  line  option  is  -2.
           Defaults to no.

       overall_rank_alt (boolean)
           Indicates  that  overall  ranking  with alternative output format should be performed.  Corresponding
           command line option is -3.  Defaults to no.

       limit_filter (integer)
           Indicates the value to be used with limit  filtering.   Corresponding  command  line  option  is  -8.
           Undefined (all instances are reported) by default.

       limit_filter_force (integer)
           As  limit_filter  but  overrides  possible possible per-metric specifications.  Corresponding command
           line option is -9.  Undefined (all instances are reported) by default.

       invert_filter (boolean)
           Indicates that invert filtering should be  performed.   Corresponding  command  line  option  is  -n.
           Defaults to no.

       predicate (string)
           Indicates  the  metrics  to  be  used as predicate metrics.  Corresponding command line option is -N.
           Undefined by default.

       sort_metric (string)
           Indicates the metrics to be used as sort reference metrics.  Corresponding command line option is -6.
           Undefined by default.

       omit_flat (boolean)
           Indicates that single-valued ``flat'' metrics  are  to  be  omitted  from  reporting.   Corresponding
           command line option is -v.  Defaults to no.

       include_labels (boolean)
           Indicates that PCP metric labels should included in the output.  Corresponding command line option is
           -m.  Defaults to no.

       include_texts (boolean)
           Indicates  that  when writing a PCP archive, PCP help texts shall be included in the created archive.
           Corresponding command line option is --include-texts.  Defaults to no.

       colxrow (string)
           Indicates to swap columns  and  rows  in  stdout  output  using  the  value  as  metric  text  label.
           Corresponding command line option is -X.  Undefined (no swapping) by default.

       width (integer)
           Indicates  the  width  of  stdout  output  columns.  Corresponding command line option is -w.  Forced
           minimum is 3.  Defaults to the shortest width that can fit the metric text label.

       width_force (integer)
           As width but overrides possible  possible  per-metric  specifications.   Corresponding  command  line
           option is -W.  Forced minimum is 3.

       precision (integer)
           Indicates how many decimals to use for numeric non-integer output values.  Corresponding command line
           option is -P.  Defaults to 3.

       precision_force (integer)
           As  precision but overrides possible per-metric specifications.  Corresponding command line option is
           -0.  Undefined by default.

       delimiter (string)
           Indicates the column separator.  Corresponding command line option is -l.   Default  depends  on  the
           output target, see pmrep(1).

       extcsv (boolean)
           Indicates whether to write extended CSV output similar to sadf(1).  Corresponding command line option
           is -k.  Defaults to no.

       extheader (boolean)
           Indicates  whether  to  print extended header.  Corresponding command line option is -x.  Defaults to
           no.

       fixed_header (boolean)
           Indicates that a fixed header should be used.  Corresponding command line option is -7.  Defaults  to
           no.

       repeat_header (integer)
           Indicates  how  often  to  repeat  the  header.   Corresponding command line option is -E.  auto uses
           terminal height.  Defaults to 0 (header is not repeated).

       dynamic_header (boolean)
           Indicates that a dynamic header should be used.  Corresponding command line option is  -1.   Defaults
           to no.

       separate_header (boolean)
           Indicates  whether to print a separate header.  Corresponding command line option is -g.  Defaults to
           no.

       timefmt (string)
           Indicates the format string for formatting the timestamp.  Corresponding command line option  is  -f.
           Defaults to %H:%M:%S.

       interpol (boolean)
           Indicates  whether  to interpolate reported archive values.  Corresponding command line option is -u.
           See pmrep(1) for complete description.  Defaults to yes.

       count_scale (string)
           Indicates the unit/scale for  counter  metrics.   Corresponding  command  line  option  is  -q.   For
           supported syntax, see pmrep(1).  Undefined (no scaling) by default.

       count_scale_force (string)
           Like count_scale but overrides possible per-metric specifications.  Corresponding command line option
           is -Q.  Undefined by default.

       space_scale (string)
           Indicates  the unit/scale for space metrics.  Corresponding command line option is -b.  For supported
           syntax, see pmrep(1).  Undefined (no scaling) by default.

       space_scale_force (string)
           Like space_scale but overrides possible per-metric specifications.  Corresponding command line option
           is -B.  Undefined by default.

       time_scale (string)
           Indicates the unit/scale for time metrics.  Corresponding command line option is -y.   For  supported
           syntax, see pmrep(1).  Undefined (no scaling) by default.

       time_scale_force (string)
           Like  time_scale but overrides possible per-metric specifications.  Corresponding command line option
           is -Y.  Undefined by default.

   The [global] section
       The [global] section is used to define metrics that will be reported in addition to any other  separately
       defined  metric or metricset.  Configuration options are not allowed in this section.  Global metrics are
       reported by default, the command line option -G or the configuration file option globals can be  used  to
       disable global metrics.

       Allowed settings

           Only metricspecs are allowed in this section.  See below for the metricspec specification.

CUSTOM SECTIONS

       Any  other  section than [options] or [global] will be interpreted as a new metricset specification.  The
       section name is arbitrary, typically a reference to its  coverage  or  purpose.   A  custom  section  may
       contain options, metricspecs, or both.

       All  the  metrics  specified  in  a  custom  section (metricset) will be reported when pmrep reports that
       particular metricset.  More than one metricset (custom section) can be defined on  the  command  line  in
       which case pmrep reports the combination of all the metrics specified in the selected metricsets.

       Allowed settings

           Any  option  valid  in the [options] section is also valid in a custom section.  Any option or metric
           defined in a custom section will override the same option or metric possibly  defined  earlier.   See
           below for the metricspec specification.

METRICSET SPECIFICATION

There are three forms of the metricspec. First, on the command line a metricspec can start with a colon
(``:'') to indicate a reference to a metricset (custom section) to be read from a pmrep configuration
file. Second, the compact form of a metricspec is a one-line metric specification which can be used both
on the command line and in the [global] and custom sections of the configuration file. The only
difference of its usage in the configuration file is that the metric name is used as the key and the
optional specifiers as values. The compact form of the metricspec is specified in detail in pmrep(1).
The third, verbose form of a metricspec, is valid only in the configuration file (see below).

In a custom section a key containing a dot (``.'') is interpreted as a metric name and a non-option key
not containing a dot is interpreted as an identifier (handle) to bind related declarations together. The
identifier is arbitrary and is not used otherwise except for binding the below specifiers and the metric
together.

The verbose form of a metricspec starts with a declaration consisting of a mandatory identifier as the
key and a performance metric name (a PMNS node) as its value. This equals to the compact form of the
metricspec defining the same performance metric without any of the optional specifiers defined.

The following specifiers are optional in the verbose form and can be used as keys in any order with an
earlier declared identifier followed by a dot and the specifier (as in identifier.specifier). See also
the example later below.

label
Defines text label for the metric used by supporting output targets.

formula
Defines the needed arithmetic expression for the metric. For details, see pmRegisterDerived(3).

instances
Defines the instances to be reported for the metric. For details, see pmrep(1).

unit
Defines the unit/scale conversion for the metric. Needs to be dimension-compatible and is used
with non-string metrics. For allowed values, see pmrep(1).

type
If set to raw rate conversion for the metric will be disabled.

width
Defines the width of the output column for the metric.

precision
Defines precision for numeric non-integer output values.

limit
Defines value limit filter for numeric metric values.

EXAMPLE

       The  following example contains a short [options] section setting some locally wanted default values.  It
       then goes on to define the global metrics kernel.all.sysfork using the compact form and mem.util.allcache
       using the verbose form of a metricspec.  The latter is a derived  metric  using  the  specified  formula.
       Both of these metrics will be included in reporting unless disabled with -G or globals = no.

       Three different metricsets are also specified: db1, db2, and sar-w.

       The  DB  sets  define  a  host  to be used as the source for the metrics.  Both use the verbose form of a
       metricspec (as the non-option key set does not  contain  the  dot)  to  include  all  postgresql  related
       metrics.

       The sar-w set is an example how to mimic an existing tool with pmrep.

       The system default pmrep configuration files contain many more examples.  The tab key on the command line
       after a colon completes available metricsets (with bash and zsh).

           [options]
           timestamp = yes
           interval = 2s
           extheader = yes
           repeat_header = auto
           space_scale = MB

           [global]
           kernel.all.sysfork = forks,,,,8
           cacheall = mem.util.allcache
           cacheall.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
           cacheall.width = 12

           [db1]
           source = db-host1.example.com
           set = postgresql

           [db2]
           source = db-host2.example.com
           set = postgresql

           [sar-w]
           header = yes
           unitinfo = no
           globals = no
           timestamp = yes
           precision = 2
           delimiter = " "
           kernel.all.sysfork = proc/s,,,,12
           kernel.all.pswitch = cswch/s,,,,9

FILES

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

PCP ENVIRONMENT

       Environment  variables with the prefix PCP_ are used to parameterize the file and directory names used by
       PCP.  On each installation, the file /etc/pcp.conf contains the local values for  these  variables.   The
       $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

       For environment variables affecting PCP tools, see pmGetOptions(3).