table of contents
|PCP-DSTAT(5)||File Formats Manual||PCP-DSTAT(5)|
pcp-dstat - pcp-dstat configuration file
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_ETC_DIR/pcp/dstat and $HOME/.pcp/dstat).
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¶
The grouping can be set at three distinct levels - 1, 2 or 3. 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.
instances (comma-separated-value string)
cullinsts (regex pattern)
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.
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.
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.
- private per-user configuration files
- system-wide configuration files
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).
PCPIntro(1), pcp-dstat(1), pminfo(1), pmprobe(1), pmrep(1), PMAPI(3), pmGetOptions(3), pmRegisterDerived(3) and pmrep.conf(5).