Provided by: pcp_4.3.1-1_amd64 bug

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  the configuration file described below.  For command line argument details see
       pmrep(1).

       The pmrep.conf configuration file allows setting default runtime values and  defining  any
       number  of  custom  metricsets  for pmrep.  A metricset is a user-defined set of arbitrary
       performance metrics.  This allows the  user  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
       the user can create and modify custom metricsets by editing pmrep.conf.  See below for the
       metricset specification.

       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 options.  A section begins
       with the name of the section in square brackets  and  continues  until  the  next  section
       begins.  An example section with two options follows:

           [section]
           key = value
           key2 = value2

       The  supported  value data types are string, integer, and boolean.  String values need not
       to be quoted expect when whitespace needs to be included in the value (for  instance,  for
       the column separator); double quotes from quoted strings will be removed.

       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
       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
       values (which may be overridden  by  the  corresponding  command  line  options).   Metric
       specifications are not allowed in this section.

       Section options

       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 string contains
           a  slash  (``/'').   If  set to the special character ``@'', local DSO PMDA context is
           used.  Otherwise interpreted as a hostname.  Corresponding command line  paraters  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.

       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.

       colxrow (string)
           Indicates  to  swap  columns  and  rows  in  stdout output using the given 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.

       repeat_header (integer)
           Indicates how often to repeat the header.  Corresponding command line  option  is  -E.
           Defaults to 0.

       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 metrics or metricsets.  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.

       Section options

           No predefined options, only metricspecs 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 can contain options, metricspecs, or both.

       All the metrics specified in a custom section will be reported when pmrep is instructed to
       use the particular custom section.  pmrep can  be  executed  with  more  than  one  custom
       section  (i.e.,  metricset)  defined  in  which  case  the  combination of all the metrics
       specified in them will be reported.

       Section options

           Any option valid in the [options] section is also valid  in  a  custom  section.   Any
           option or metric defined in the custom section will override the same option or metric
           possibly defined in an earlier section.  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 to be read from the
       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).

       A  key  containing a dot (``.'') is interpreted as a metric name (see above), a non-option
       key not containing a dot is interpreted as an identifier (see below).

       The verbose form of a metricspec starts with  a  declaration  consisting  of  a  mandatory
       identifier  as  the  key  and the actual performance metric name (a PMNS leaf node) as its
       value.  This equals to the compact form of the metricspec defining  the  same  performance
       metric without any of optional specifiers defined.  The identifier is arbitrary and is not
       used otherwise except for binding the below specifiers and the metric together.

       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):

              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 later  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.conf file contains many more examples.  Using tab after the colon
       can be used to complete available metricsets (with bash and zsh).

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

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

           [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/pmrep.conf
              system provided pmrep configuration file

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).

SEE ALSO

       PCPIntro(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3) and pmRegisterDerived(3).