Ubuntu Manpage: pcp-dstat - pcp-dstat configuration file

NAME

       pcp-dstat - pcp-dstat configuration file

DESCRIPTION

       pcp-dstat  is  a  customizable  performance  metrics  reporting tool.  It has a ``plugin''
       architecture, where a set of pre-defined plugins  offer  small  sets  of  columnar  metric
       reports,  and pcp-dstat command line options select which of these plugins are used in the
       generated report.

       Each plugin is defined in a section of a configuration file.  A typical installation  will
       provide many configuration files, and often multiple sections (plugins) within each file.

       Configuration  files  are  read  from both a system directory and the users home directory
       ($PCP_SYSCONF_DIR/dstat and $HOME/.pcp/dstat).

FILE FORMAT

The configuration files have an ini-style syntax consisting of sections (plugins) and
options within sections. A section begins with the name of the plugin in square brackets
and continues until the next section begins. An example section with two options follows:

[plugin]
option = value
metric.option = value2

A line comment starts with a hash sign (``#'') or a semicolon (``;''). Inline comments
are not supported.

There are some options which apply to the plugin as a whole, and anything else is
considered to be a column definition. Column definitions map directly to individual PCP
metrics.

The [plugin] options
label (string)
The overall title to be used for this plugin. In the special case of metrics with
instances being reported as a group (see grouptype below) this string may contain the
%I pattern, which will be substituted with the name of the instance - refer to the
cpu, disk, net and int(errupts) plugins for examples of this special syntax.
Undefined by default, set automatically to the section (plugin) name.

width (integer)
The column width used for metrics in this plugin. The default is 5.

precision (integer)
The maximum precision to be used when reporting columns in floating point for this
plugin. Undefined by default, set automatically based on width.

printtype (character)
Indicates the reporting style for metric values in this plugin. Possible settings are
d(ecimal), f(loat), p(ercent), s(tring), b(its), t(ime). By default a setting will be
used based on the metric type and semantic - refer to PMAPI(3) for further details of
PCP metric metadata.

colorstep (integer)
Indicates a ``step'' at which the next color will be transitioned to, when reporting
metric values. As metric values change on each sample, the colorstep is used to
determine the increments beyond which a new color is to be selected. Defaults to
1000.

grouptype (integer)
For plugins with metrics sharing the same instance domain, it is possible to request
more complex grouping behaviour. The default behaviour is to not use instance
grouping, and to report each instance of the metric in a separate column (the load
plugin is an example of this, using the kernel.all.load metric).

The grouping can be set at three distinct levels - 1, 2, 3 or 4. Level 1 displays
instances of metrics only (no totals) - this is the equivalent of using the --cpu
plugin on the pcp-dstat command line with specific processors' utilization displayed,
e.g. displaying CPU numbers 4, 5 and 12 (-C 4,5,12). Level 2 displays the total
column - the sum of all instances for the specified metric(s) in this plugin. Level 3
is a combination of both modes, for example using the pcp-dstat --cpu plugin with
options -C 4,5,12,total. Level 4 is a top-like mode, where a special "top" expression
is used to rank all instances - the top-most (largest) value will be displayed.

instances (comma-separated-value string)
Defines the instances to be reported for the metric. The default is to report all
instances for set-values metrics.

cullinsts (regex pattern)
An optional regular expression that can be used to cull metric instances from the
aggregation ('total') in generated reports. For example it is common to exclude
loopback devices from the network interface reports, this is achieved using this
option. Default is to report on all instances (no culling).

The [plugin] metrics
Each plugin must have at least one metric associated with it. Any key that is not one of
the above global plugin options is considered to be a metric specification or a metric
option. These keys define the metrics and their report formatting.

First and foremost, each column is typically represented by an individual metric (if the
metric is set-valued - i.e. it has instances - this will result in multiple columns).
This is specified by a new key (column) being set to a metric specification. The column
(key) name is an arbitrary word using alphabetic characters. The metric specification is
any PCP metric name or derived metric specification, allowing basic arithmetic
calculations to be used to form this individual column. The derived metric syntax is
described on the pmRegisterDerived(3) manual page.

Some examples of both forms of metric specification are given below in the ``EXAMPLES''
section. Once a column has been associated with a metric, other options specific to that
column can be set using a dot-separated syntax.

Metric options

metric.label
The subtitle to be used for the reported values of this metric. The default label is
the column name from the configuration file.

When set-valued PCP metrics (i.e. with instances) are being used, it is often
convenient to specify either the instance number or instance name in the heading.
This is achieved using format specifiers - ``%d'' or ``%i'' for instance numbers (e.g.
replaced by ``6'' for the sixth processor), and ``%s'' or ``%I'' for instance names
(e.g. replaced by ``eth0'' for the ethernet interface). Available instance names for
any metric can be discovered via the pminfo(1) or pmprobe(1) commands.

metric.width
The column width to be used when reporting values for this metric.

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

metric.type (string)
If set to raw rate conversion for the metric will be disabled.

metric.precision (integer)
Defines precision for floating point values.

metric.limit (string)
Defines value limit filter for numeric metric values.

EXAMPLES

       The following example defines a virtual filesystem plugin, with two columns, defined using
       three PCP metrics - vfs.files.count, vfs.inodes.count  and  vfs.inodes.free.   The  inodes
       metrics are combined using the derived metric notation.

           [vfs]
           width = 6
           label = filesystem
           files = vfs.files.count
           inode = vfs.inodes.count - vfs.inodes.free
           inode.label = inodes

       The system default pcp-dstat plugin files contain many more examples.

FILES

       $HOME/.pcp/dstat/
              private per-user configuration files

       $PCP_SYSCONF_DIR/dstat/
              system-wide configuration files

PCP ENVIRONMENT