# pcp-dstat

## 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).
    
           filtertype (string)
               Used for plugin metrics that allow command-line instance
               filtering options.  The value of the filtertype entry should
               be appropriate for the instance select option being used as
               listed in the table below.
    
               filtertype    instance select option
               ─────────────────────────────────────
               cpu           -C
               disk          -D
               dm            -L
               md            -M
               part          -P
               int           -I
               net           -N
               net-packets   -N
               swap          -S
    
       **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



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


* * *