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
12 options 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_ETC_DIR/pcp/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
74 instance 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 or 3.
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
82 total 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 instances (comma-separated-value string)
87 Defines the instances to be reported for the metric. The default
88 is to report all instances for set-values metrics.
89 cullinsts (regex pattern)
91 An optional regular expression that can be used to cull metric
92 instances from the generated reports. For example it is common to
93 exclude loopback devices from the network interface reports, this
94 is achieved using this option. Default is to report on all
95 instances (no culling).
96 The [plugin] metrics
98 Each plugin must have at least one metric associated with it. Any key
99 that is not one of the above global plugin options is considered to be
100 a metric specification or a metric option. These keys define the met‐
101 rics and their report formatting.
102 First and foremost, each column is typically represented by an individ‐
104 ual metric (if the metric is set-valued - i.e. it has instances - this
105 will result in multiple columns). This is specified by a new key (col‐
106 umn) being set to a metric specification. The column (key) name is an
107 arbitrary word using alphabetic characters. The metric specification
108 is any PCP metric name or derived metric specification, allowing basic
109 arithmetic calculations to be used to form this individual column. The
110 derived metric syntax is described on the pmRegisterDerived(3) manual
111 page.
112 Some examples of both forms of metric specification are given below in
114 the ``EXAMPLES'' section. Once a column has been associated with a
115 metric, other options specific to that column can be set using a dot-
116 separated syntax.
117 Metric options
119 metric.label
121 The subtitle to be used for the reported values of this metric.
122 The default label is the column name from the configuration file.
123 When set-valued PCP metrics (i.e. with instances) are being used,
125 it is often convenient to specify either the instance number or
126 instance name in the heading. This is achieved using format speci‐
127 fiers - ``%d'' or ``%i'' for instance numbers (e.g. replaced by
128 ``6'' for the sixth processor), and ``%s'' or ``%I'' for instance
129 names (e.g. replaced by ``eth0'' for the ethernet interface).
130 Available instance names for any metric can be discovered via the
131 pminfo(1) or pmprobe(1) commands.
132 metric.width
134 The column width to be used when reporting values for this metric.
135 metric.unit (string)
137 Defines the unit/scale conversion for the metric. Needs to be
138 dimension-compatible and is used with non-string metrics. For
139 allowed values, see pmrep(1).
140 metric.type (string)
142 If set to raw rate conversion for the metric will be disabled.
143 metric.precision (integer)
145 Defines precision for floating point values.
146 metric.limit (string)
148 Defines value limit filter for numeric metric values.
149
151 The following example defines a virtual filesystem plugin, with two
152 columns, defined using three PCP metrics - vfs.files.count,
153 vfs.inodes.count and vfs.inodes.free. The inodes metrics are combined
154 using the derived metric notation.
155 [vfs]
157 width = 6
158 label = filesystem
159 files = vfs.files.count
160 inode = vfs.inodes.count - vfs.inodes.free
161 inode.label = inodes
162 The system default pcp-dstat plugin files contain many more examples.
165
167 $HOME/.pcp/dstat/
168 private per-user configuration files
169 $PCP_ETC_DIR/pcp/dstat/
171 system-wide configuration files
172
174 Environment variables with the prefix PCP_ are used to parameterize the
175 file and directory names used by PCP. On each installation, the file
176 /etc/pcp.conf contains the local values for these variables. The
177 $PCP_CONF variable may be used to specify an alternative configuration
178 file, as described in pcp.conf(5).
179 For environment variables affecting PCP tools, see pmGetOptions(3).
181
183 PCPIntro(1), pcp-dstat(1), pminfo(1), pmprobe(1), pmrep(1), PMAPI(3),
184 pmGetOptions(3), pmRegisterDerived(3) and pmrep.conf(5).
185Performance Co-Pilot PCP PCP-DSTAT(5)