1PMDADM(1)                   General Commands Manual                  PMDADM(1)
2
3
4

NAME

6       pmdadm - Device Mapper PMDA
7

DESCRIPTION

9       pmdadm  is a Performance Metrics Domain Agent (PMDA) which exports met‐
10       ric values for Device Mapper on the local system.
11
12       This PMDA collects its data through the dmsetup(8) utility and the  dm‐
13       stats  API and requires that the program is installed in order to func‐
14       tion.  In addition, at least one statistics region must be created  us‐
15       ing  the  dmstats(8) utility in order to get basic counter values.  See
16       below for examples.
17
18       Note that device-mapper statistics collection is not enabled by default
19       and is not persistent across reboots (unless a system administrator has
20       configured something to run in rc.local or equivalent).   This  is  be‐
21       cause  there  are  overheads associated with statistics collection.  In
22       addition, the pmdadm PMDA does not automatically enable any  statistics
23       collection because it may not be the only consumer of the data.
24

INSTALLATION

26       Install the DM PMDA by using the Install script as root:
27
28           # cd $PCP_PMDAS_DIR/dm
29           # ./Install
30
31       To uninstall, the following must be done as root:
32
33           # cd $PCP_PMDAS_DIR/dm
34           # ./Remove
35
36       pmdadm  is  launched  by pmcd(1) and should never be executed directly.
37       The Install and Remove scripts notify pmcd when the agent is  installed
38       or removed.
39

CONFIGURATION

41       This PMDA uses the dmstats API (the userspace device-mapper support li‐
42       brary) to capture device-mapper performance data.
43       Using this PMDA, users need the userspace device-mapper support library
44       (libdevmapper)  and the userspace command line tool dmstats(8).  Before
45       device-mapper metrics will be available  for  PCP,  statistics  regions
46       have  to  be  created.  For example, to enable basic statistics for all
47       local device-mapper logical devices, use the following command:
48
49            # dmstats create --alldevices
50
51       To create statistics regions with specified histogram  boundaries,  use
52       the following:
53
54            # dmstats create --alldevices --bounds histogram_boundaries
55
56       Specify the boundaries of a latency histogram to be tracked for the re‐
57       gion as a comma separated list of latency values.  Latency  values  are
58       given  in  nanoseconds. An optional unit suffix of ns, us, ms, or s may
59       be given after each value to specify units  of  nanoseconds,  microsec‐
60       onds, miliseconds or seconds respectively.  For example,
61
62            # dmstats create --alldevices --bounds 10us,30us,50us,70us,90us
63
64       Further details and more complex examples can be found in dmstats(8).
65

METRICS

67       Basic Counters
68           Basic counters provide access to the raw counter data from the ker‐
69           nel, allowing further processing to be carried out by another  pro‐
70           gram.
71           The  Kernel provides thirteen separate counters for each statistics
72           area.  The first eleven of these match  the  counters  provided  in
73           /proc/diskstats or /sys/block/*/*/stat. The final pair provide sep‐
74           arate counters for read and write time.
75
76           dmstats.read
77               Count of reads completed this interval  per  device-mapper  de‐
78               vice.
79
80           dmstats.reads_merged
81               Count of reads merged this interval per device-mapper device.
82
83           dmstats.read_bytes
84               Count of kbytes read this interval per device-mapper device.
85
86           dmstats.reads_time
87               Accumulated duration of all read requests per device-mapper de‐
88               vice.
89
90           dmstats.write
91               Count of writes completed this interval per  device-mapper  de‐
92               vice.
93
94           dmstats.writes_merged
95               Count  of  writes completed this interval per device-mapper de‐
96               vice.
97
98           dmstats.write_bytes
99               Count of kbytes write this interval per device-mapper device.
100
101           dmstats.writes_time
102               Accumulated duration of all write  requests  per  device-mapper
103               device.
104
105           dmstats.in_progress
106               Count  of  requests currently in progress per device-mapper de‐
107               vice.
108
109           dmstats.io_ticks
110               Nanoseconds spent servicing request per device-mapper device.
111
112           dmstats.queue_ticks
113               This field is incremented at each I/O  start,  I/O  completion,
114               I/O  merge,  or  read  of  these stats by the number of I/Os in
115               progress multiplied by the number of  nanoseconds  spent  doing
116               I/O  since  the  last update of this field. This can provide an
117               easy measure of both I/O completion time and the  backlog  that
118               may be accumulating.
119
120           dmstats.read_ticks
121               Nanoseconds spent servicing reads per device-mapper device.
122
123           dmstats.write_ticks
124               Nanoseconds spent servicing writes per device-mapper device.
125
126       Histogram fields
127           Histograms measure the frequency distribution of user specified I/O
128           latency intervals.  Histogram bin boundaries are specified  when  a
129           region is created.
130           Instance name represents devicename, region id and bin boundaries.
131
132           dmstats.histogram.hist_count
133               A  list of the histogram counts for the current statistics area
134               in order of ascending latency value. Each value represents  the
135               number  of I/Os with latency times falling into that bin's time
136               range during the sample period.
137
138           dmstats.histogram.hist.bins
139               The number of latency histogram bins configured for the area.
140

EXAMPLES

142       # dmstats create looptest0 --bounds 10us,30us,50us
143       looptest0: Created new region with 1 area(s) as region ID 0
144
145       # pminfo -f dmstats.read dmstats.histogram.hist_count
146
147       dmstats.read
148           inst [0 or "looptest0"] value 4099
149
150       dmstats.histogram.hist_count
151           inst [0 or "looptest0:0:0s"] value 1
152           inst [1 or "looptest0:0:10us"] value 3752
153           inst [2 or "looptest0:0:30us"] value 250
154           inst [3 or "looptest0:0:50us"] value 96
155

FILES

157       $PCP_PMDAS_DIR/dm/help
158           default help text file for the dm metrics
159
160       $PCP_PMDAS_DIR/dm/Install
161           installation script for the pmdadm agent
162
163       $PCP_PMDAS_DIR/dm/Remove
164           undo installation script for the pmdadm agent
165
166       $PCP_LOG_DIR/pmcd/dm.log
167           default log file for error messages from pmdadm
168

PCP ENVIRONMENT

170       Environment variables with the prefix PCP_ are used to parameterize the
171       file  and  directory  names used by PCP. On each installation, the file
172       /etc/pcp.conf contains the  local  values  for  these  variables.   The
173       $PCP_CONF  variable may be used to specify an alternative configuration
174       file, as described in pcp.conf(5).
175

SEE ALSO

177       PCPIntro(1), pmcd(1), pmstore(1), dmsetup(8) and dmstats(8).
178
179
180
181Performance Co-Pilot                  PCP                            PMDADM(1)
Impressum