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