1PMDADM(1) General Commands Manual PMDADM(1)
2
6 pmdadm - Device Mapper PMDA
7
9 pmdadm is a Performance Metrics Domain Agent (PMDA) which exports met‐
10 ric values for Device Mapper on the local system.
11 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 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
26 Install the DM PMDA by using the Install script as root:
27 # cd $PCP_PMDAS_DIR/dm
29 # ./Install
30 To uninstall, the following must be done as root:
32 # cd $PCP_PMDAS_DIR/dm
34 # ./Remove
35 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
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 # dmstats create --alldevices
50 To create statistics regions with specified histogram boundaries, use
52 the following:
53 # dmstats create --alldevices --bounds histogram_boundaries
55 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 # dmstats create --alldevices --bounds 10us,30us,50us,70us,90us
63 Further details and more complex examples can be found in dmstats(8).
65
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 dmstats.read
77 Count of reads completed this interval per device-mapper de‐
78 vice.
79 dmstats.reads_merged
81 Count of reads merged this interval per device-mapper device.
82 dmstats.read_bytes
84 Count of kbytes read this interval per device-mapper device.
85 dmstats.reads_time
87 Accumulated duration of all read requests per device-mapper de‐
88 vice.
89 dmstats.write
91 Count of writes completed this interval per device-mapper de‐
92 vice.
93 dmstats.writes_merged
95 Count of writes completed this interval per device-mapper de‐
96 vice.
97 dmstats.write_bytes
99 Count of kbytes write this interval per device-mapper device.
100 dmstats.writes_time
102 Accumulated duration of all write requests per device-mapper
103 device.
104 dmstats.in_progress
106 Count of requests currently in progress per device-mapper de‐
107 vice.
108 dmstats.io_ticks
110 Nanoseconds spent servicing request per device-mapper device.
111 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 dmstats.read_ticks
121 Nanoseconds spent servicing reads per device-mapper device.
122 dmstats.write_ticks
124 Nanoseconds spent servicing writes per device-mapper device.
125 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 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 dmstats.histogram.hist.bins
139 The number of latency histogram bins configured for the area.
140
142 # dmstats create looptest0 --bounds 10us,30us,50us
143 looptest0: Created new region with 1 area(s) as region ID 0
144 # pminfo -f dmstats.read dmstats.histogram.hist_count
146 dmstats.read
148 inst [0 or "looptest0"] value 4099
149 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
157 $PCP_PMDAS_DIR/dm/help
158 default help text file for the dm metrics
159 $PCP_PMDAS_DIR/dm/Install
161 installation script for the pmdadm agent
162 $PCP_PMDAS_DIR/dm/Remove
164 undo installation script for the pmdadm agent
165 $PCP_LOG_DIR/pmcd/dm.log
167 default log file for error messages from pmdadm
168
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
177 PCPIntro(1), pmcd(1), pmstore(1), dmsetup(8) and dmstats(8).
178Performance Co-Pilot PCP PMDADM(1)