pmdadm(1)

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
13       dmstats  API  and  requires  that  the program is installed in order to
14       function.  In addition, at least one statistics region must be  created
15       using 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
21       because  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    ($PCP_PMDAS_DIR    is    usually
29       /var/lib/pcp/pmdas)
30             # ./Install
31
32       To uninstall, do the following as root:
33
34             # cd $PCP_PMDAS_DIR/dm
35             # ./Remove
36
37       pmdadm is launched by pmcd(1) and should never  be  executed  directly.
38       The  Install and Remove scripts notify pmcd when the agent is installed
39       or removed.
40

CONFIGURATION

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

METRICS

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

EXAMPLES

143            # dmstats create looptest0 --bounds 10us,30us,50us
144            looptest0: Created new region with 1 area(s) as region ID 0
145
146            # pminfo -f dmstats.read dmstats.histogram.hist_count
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