# pmrep.conf

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


* * *