bionic (5) pmrep.conf.5.gz

Provided by: pcp_4.0.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 (string)
           Indicates that incompatible metrics are to be ignored.  Corresponding  command  line  option  is  -I.
           Defaults to no.

       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.

       omit_flat (string)
           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).