1PCP-DSTAT(5)                  File Formats Manual                 PCP-DSTAT(5)
2
3
4

NAME

6       pcp-dstat - pcp-dstat configuration file
7

DESCRIPTION

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
14       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
18       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

FILE FORMAT

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
27           [plugin]
28           option = value
29           metric.option = value2
30
31       A line comment starts with a hash sign (``#'') or a semicolon  (``;'').
32       Inline comments are not supported.
33
34       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
38   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
48       width (integer)
49           The  column  width used for metrics in this plugin.  The default is
50           5.
51
52       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
57       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
64       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
70       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
77           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
86       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
90       cullinsts (regex pattern)
91           An  optional  regular  expression  that  can be used to cull metric
92           instances from the aggregation ('total') in generated reports.  For
93           example  it  is common to exclude loopback devices from the network
94           interface reports, this is achieved using this option.  Default  is
95           to report on all instances (no culling).
96
97   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
103       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
113       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
118       Metric options
119
120       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
124           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
133       metric.width
134           The column width to be used when reporting values for this metric.
135
136       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
141       metric.type (string)
142           If set to raw rate conversion for the metric will be disabled.
143
144       metric.precision (integer)
145           Defines precision for floating point values.
146
147       metric.limit (string)
148           Defines value limit filter for numeric metric values.
149

EXAMPLES

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
156           [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
163
164       The system default pcp-dstat plugin files contain many more examples.
165

FILES

167       $HOME/.pcp/dstat/
168              private per-user configuration files
169
170       $PCP_ETC_DIR/pcp/dstat/
171              system-wide configuration files
172

PCP ENVIRONMENT

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
180       For environment variables affecting PCP tools, see pmGetOptions(3).
181

SEE ALSO

183       PCPIntro(1), pcp-dstat(1), pminfo(1), pmprobe(1),  pmrep(1),  PMAPI(3),
184       pmGetOptions(3), pmRegisterDerived(3) and pmrep.conf(5).
185
186
187
188Performance Co-Pilot                  PCP                         PCP-DSTAT(5)
Impressum