NAME | DESCRIPTION | FILE FORMAT | SPECIAL SECTIONS | CUSTOM SECTIONS | METRICSET SPECIFICATION | EXAMPLE | FILES | SEE ALSO | COLOPHON

PMREP.CONF(5)                File Formats Manual               PMREP.CONF(5)

NAME         top

       pmrep.conf - pmrep configuration file

DESCRIPTION         top

       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 metric sets 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.

       Configuration file options override the corresponding built-in
       default values (if any). Command line options override the
       corresponding configuration file options (if any).

FILE FORMAT         top

       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 data types used are string (no quotes needed), integer, and bool
       (with values of yes or no).

       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         top

   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 ``|'' 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.

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

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

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

       timestamp (bool)
           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 (bool)
           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.

       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 current instances are reported)
           by default.

       omit_flat (string)
           Indicates that single-valued ``flat'' metrics are to be omitted
           when instances were requested. Corresponding command line option
           is -v.  Defaults to no.

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

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

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

       extheader (bool)
           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.

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

       interpol (bool)
           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.

       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.

       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.

       Output target specific options

           The following options are also accepted in the [options] section
           but are typically used only in custom sections as they are
           applicable only to certain output targets.

       zabbix_server (string) (zabbix output target only)
           Hostname or IP address of Zabbix server to send the metrics to.
           If a host is monitored by a proxy, proxy hostname or IP address
           should be used instead. Undefined by default.

       zabbix_port (integer) (zabbix output target only)
           Specify port number of server trapper running on the server.
           Default is 10051.

       zabbix_host (string) (zabbix output target only)
           Specify agent hostname as registered in Zabbix frontend. Host IP
           address and DNS name will not work. Undefined by default.

       zabbix_interval (string) (zabbix output target only)
           Indicates the interval to send the metrics to the Zabbix server.
           This can be longer than the generic interval to minimize the
           overhead when communicating with the server (as each send creates
           a new connection). Follows the time syntax described in
           PCPIntro(1).  Defaults to the generic interval. Zabbix tools send
           at most 250 metrics at a time. Ignored when reading metrics from
           PCP archives, in which case metrics will be sent roughly at 250
           metric batches.

   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         top

       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
           earlier in the [options] section. See below for the metricspec
           specification.

METRICSET SPECIFICATION         top

       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.

       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 a text label for the metric used by supporting
                output targets.

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

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

EXAMPLE         top

       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.

           [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

           [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
           interval = 1s
           extheader = no
           precision = 2
           sysfork = kernel.all.sysfork
           sysfork.label = proc/s
           sysfork.width = 11
           pswitch = kernel.all.pswitch
           pswitch.label = cswch/s
           pswitch.width = 8

FILES         top

       $PCP_SYSCONF_DIR/pmrep/pmrep.conf
                 System provided configuration file.

SEE ALSO         top

       PCPIntro(1), pmrep(1), __pmSpecLocalPMDA(3), pmRegisterDerived(3) and
       zbxpcp(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to man-pages@man7.org

Performance Co-Pilot                 PCP                       PMREP.CONF(5)

Pages that refer to this page: pmrep(1)