1PCP-DSTAT(5) File Formats Manual PCP-DSTAT(5)
2
6 pcp-dstat - pcp-dstat configuration file
7
9 pcp-dstat is a customizable performance metrics reporting tool. It has
10 a ``plugin'' architecture, where a set of pre-defined plugins offer
11 small sets of columnar metric reports, and pcp-dstat command line op‐
12 tions select which of these plugins are used in the generated report.
13 Each plugin is defined in a section of a configuration file. A typical
15 installation will provide many configuration files, and often multiple
16 sections (plugins) within each file.
17 Configuration files are read from both a system directory and the users
19 home directory ($PCP_SYSCONF_DIR/dstat and $HOME/.pcp/dstat).
20
22 The configuration files have an ini-style syntax consisting of sections
23 (plugins) and options within sections. A section begins with the name
24 of the plugin in square brackets and continues until the next section
25 begins. An example section with two options follows:
26 [plugin]
28 option = value
29 metric.option = value2
30 A line comment starts with a hash sign (``#'') or a semicolon (``;'').
32 Inline comments are not supported.
33 There are some options which apply to the plugin as a whole, and any‐
35 thing else is considered to be a column definition. Column definitions
36 map directly to individual PCP metrics.
37 The [plugin] options
39 label (string)
40 The overall title to be used for this plugin. In the special case
41 of metrics with instances being reported as a group (see grouptype
42 below) this string may contain the %I pattern, which will be sub‐
43 stituted with the name of the instance - refer to the cpu, disk,
44 net and int(errupts) plugins for examples of this special syntax.
45 Undefined by default, set automatically to the section (plugin)
46 name.
47 width (integer)
49 The column width used for metrics in this plugin. The default is
50 5.
51 precision (integer)
53 The maximum precision to be used when reporting columns in floating
54 point for this plugin. Undefined by default, set automatically
55 based on width.
56 printtype (character)
58 Indicates the reporting style for metric values in this plugin.
59 Possible settings are d(ecimal), f(loat), p(ercent), s(tring),
60 b(its), t(ime). By default a setting will be used based on the
61 metric type and semantic - refer to PMAPI(3) for further details of
62 PCP metric metadata.
63 colorstep (integer)
65 Indicates a ``step'' at which the next color will be transitioned
66 to, when reporting metric values. As metric values change on each
67 sample, the colorstep is used to determine the increments beyond
68 which a new color is to be selected. Defaults to 1000.
69 grouptype (integer)
71 For plugins with metrics sharing the same instance domain, it is
72 possible to request more complex grouping behaviour. The default
73 behaviour is to not use instance grouping, and to report each in‐
74 stance of the metric in a separate column (the load plugin is an
75 example of this, using the kernel.all.load metric).
76 The grouping can be set at three distinct levels - 1, 2, 3 or 4.
78 Level 1 displays instances of metrics only (no totals) - this is
79 the equivalent of using the --cpu plugin on the pcp-dstat command
80 line with specific processors' utilization displayed, e.g. display‐
81 ing CPU numbers 4, 5 and 12 (-C 4,5,12). Level 2 displays the to‐
82 tal column - the sum of all instances for the specified metric(s)
83 in this plugin. Level 3 is a combination of both modes, for exam‐
84 ple using the pcp-dstat --cpu plugin with options -C 4,5,12,total.
85 Level 4 is a top-like mode, where a special "top" expression is
86 used to rank all instances - the top-most (largest) value will be
87 displayed.
88 instances (comma-separated-value string)
90 Defines the instances to be reported for the metric. The default
91 is to report all instances for set-values metrics.
92 cullinsts (regex pattern)
94 An optional regular expression that can be used to cull metric in‐
95 stances from the aggregation ('total') in generated reports. For
96 example it is common to exclude loopback devices from the network
97 interface reports, this is achieved using this option. Default is
98 to report on all instances (no culling).
99 The [plugin] metrics
101 Each plugin must have at least one metric associated with it. Any key
102 that is not one of the above global plugin options is considered to be
103 a metric specification or a metric option. These keys define the met‐
104 rics and their report formatting.
105 First and foremost, each column is typically represented by an individ‐
107 ual metric (if the metric is set-valued - i.e. it has instances - this
108 will result in multiple columns). This is specified by a new key (col‐
109 umn) being set to a metric specification. The column (key) name is an
110 arbitrary word using alphabetic characters. The metric specification
111 is any PCP metric name or derived metric specification, allowing basic
112 arithmetic calculations to be used to form this individual column. The
113 derived metric syntax is described on the pmRegisterDerived(3) manual
114 page.
115 Some examples of both forms of metric specification are given below in
117 the ``EXAMPLES'' section. Once a column has been associated with a
118 metric, other options specific to that column can be set using a dot-
119 separated syntax.
120 Metric options
122 metric.label
124 The subtitle to be used for the reported values of this metric.
125 The default label is the column name from the configuration file.
126 When set-valued PCP metrics (i.e. with instances) are being used,
128 it is often convenient to specify either the instance number or in‐
129 stance name in the heading. This is achieved using format speci‐
130 fiers - ``%d'' or ``%i'' for instance numbers (e.g. replaced by
131 ``6'' for the sixth processor), and ``%s'' or ``%I'' for instance
132 names (e.g. replaced by ``eth0'' for the ethernet interface).
133 Available instance names for any metric can be discovered via the
134 pminfo(1) or pmprobe(1) commands.
135 metric.width
137 The column width to be used when reporting values for this metric.
138 metric.unit (string)
140 Defines the unit/scale conversion for the metric. Needs to be di‐
141 mension-compatible and is used with non-string metrics. For al‐
142 lowed values, see pmrep(1).
143 metric.type (string)
145 If set to raw rate conversion for the metric will be disabled.
146 metric.precision (integer)
148 Defines precision for floating point values.
149 metric.limit (string)
151 Defines value limit filter for numeric metric values.
152
154 The following example defines a virtual filesystem plugin, with two
155 columns, defined using three PCP metrics - vfs.files.count, vfs.in‐
156 odes.count and vfs.inodes.free. The inodes metrics are combined using
157 the derived metric notation.
158 [vfs]
160 width = 6
161 label = filesystem
162 files = vfs.files.count
163 inode = vfs.inodes.count - vfs.inodes.free
164 inode.label = inodes
165 The system default pcp-dstat plugin files contain many more examples.
168
170 $HOME/.pcp/dstat/
171 private per-user configuration files
172 $PCP_SYSCONF_DIR/dstat/
174 system-wide configuration files
175
177 Environment variables with the prefix PCP_ are used to parameterize the
178 file and directory names used by PCP. On each installation, the file
179 /etc/pcp.conf contains the local values for these variables. The
180 $PCP_CONF variable may be used to specify an alternative configuration
181 file, as described in pcp.conf(5).
182 For environment variables affecting PCP tools, see pmGetOptions(3).
184
186 PCPIntro(1), pcp-dstat(1), pminfo(1), pmprobe(1), pmrep(1), PMAPI(3),
187 pmGetOptions(3), pmRegisterDerived(3) and pmrep.conf(5).
188Performance Co-Pilot PCP PCP-DSTAT(5)