'\"macro stdmacro
.\"
.\" Copyright (c) 2015 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMDADM 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdadm\f1 \- Device Mapper PMDA
.SH DESCRIPTION
.B pmdadm
is a Performance Metrics Domain Agent (PMDA) which exports
metric values for Device Mapper on the local system.
.PP
This PMDA collects its data through the
.BR dmsetup (8)
utility and the dmstats API and requires that the program is installed in order to function.
In addition, at least one statistics region must be created using the
.BR dmstats (8)
utility in order to get basic counter values.
See below for examples.
.PP
Note that device-mapper statistics collection is not enabled by default and is not
persistent across reboots (unless a system administrator has configured something to run
in
.B rc.local
or equivalent).
This is because there are overheads associated with statistics collection.
In addition, the
.B pmdadm
PMDA does not automatically enable any statistics collection
because it may not be the only consumer of the data.
.SH INSTALLATION
Install the DM PMDA by using the Install script as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/dm
# ./Install
.fi
.ft P
.RE
.sp 1
To uninstall, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/dm
# ./Remove
.fi
.ft P
.RE
.sp 1
.B pmdadm
is launched by
.BR pmcd (1)
and should never be executed directly.
The
.B Install
and
.B Remove
scripts notify
.B pmcd
when the agent is installed or removed.
.SH CONFIGURATION
This PMDA uses the dmstats API (the userspace device-mapper support library)
to capture device-mapper performance data.
.br
Using this PMDA, users need the userspace device-mapper support library (libdevmapper)
and the userspace command line tool
.BR dmstats (8).
Before device-mapper metrics will be available for PCP,
statistics regions have to be created.
For example, to enable basic statistics for all local device-mapper logical devices,
use the following command:
.P
.ft CR
.nf
.in +0.5i
# dmstats create --alldevices
.in
.fi
.PP
To create statistics regions with specified histogram boundaries, use the following:
.P
.ft CR
.nf
.in +0.5i
# dmstats create --alldevices --bounds\fP \fIhistogram_boundaries
.in
.fi
.PP
Specify the boundaries of a latency histogram to be tracked for the region as a comma
separated list of latency values. Latency values are given in nanoseconds. An optional
unit suffix of
.BR ns ,
.BR us ,
.BR ms ,
or
.BR s
may be given after each value to specify units of nanoseconds,
microseconds, miliseconds or seconds respectively.
For example,
.P
.ft CR
.nf
.in +0.5i
# dmstats create --alldevices --bounds 10us,30us,50us,70us,90us
.in
.fi
.PP
Further details and more complex examples can be found in
.BR dmstats (8).
.SH METRICS
.IP "\fBBasic Counters\fR" 4
Basic counters provide access to the raw counter data from the kernel,
allowing further processing to be carried out by another program.
.br
The Kernel provides thirteen separate counters for each statistics area.
The first eleven of these match the counters provided in /proc/diskstats
or /sys/block/*/*/stat. The final pair provide separate counters for
read and write time.
.RS 4
.IP "\fBdmstats.read\fR" 4
Count of reads completed this interval per device-mapper device.
.IP "\fBdmstats.reads_merged\fR" 4
Count of reads merged this interval per device-mapper device.
.IP "\fBdmstats.read_bytes\fR" 4
Count of kbytes read this interval per device-mapper device.
.IP "\fBdmstats.reads_time\fR" 4
Accumulated duration of all read requests per device-mapper device.
.IP "\fBdmstats.write\fR" 4
Count of writes completed this interval per device-mapper device.
.IP "\fBdmstats.writes_merged\fR" 4
Count of writes completed this interval per device-mapper device.
.IP "\fBdmstats.write_bytes\fR" 4
Count of kbytes write this interval per device-mapper device.
.IP "\fBdmstats.writes_time\fR" 4
Accumulated duration of all write requests per device-mapper device.
.IP "\fBdmstats.in_progress\fR" 4
Count of requests currently in progress per device-mapper device.
.IP "\fBdmstats.io_ticks\fR" 4
Nanoseconds spent servicing request per device-mapper device.
.IP "\fBdmstats.queue_ticks\fR" 4
This field is incremented at each I/O start, I/O completion, I/O merge,
or read of these stats by the number of I/Os in progress multiplied by
the number of nanoseconds spent doing I/O since the last update of
this field. This can provide an easy measure of both I/O completion time
and the backlog that may be accumulating.
.IP "\fBdmstats.read_ticks\fR" 4
Nanoseconds spent servicing reads per device-mapper device.
.IP "\fBdmstats.write_ticks\fR" 4
Nanoseconds spent servicing writes per device-mapper device.
.br
.RS -4
.IP "\fBHistogram fields\fR" 4
Histograms measure the frequency distribution of user specified I/O latency intervals.
Histogram bin boundaries are specified when a region is created.
.br
Instance name represents devicename, region id and bin boundaries.
.RS 4
.IP "\fBdmstats.histogram.hist_count\fR" 4
A list of the histogram counts for the current statistics area in order of
ascending latency value. Each value represents the number of I/Os with
latency times falling into that bin's time range during the sample period.
.IP "\fBdmstats.histogram.hist.bins\fR" 4
The number of latency histogram bins configured for the area.
.RE
.SH EXAMPLES
.ft CR
.nf
.in
# dmstats create looptest0 --bounds 10us,30us,50us
looptest0: Created new region with 1 area(s) as region ID 0
.in
.fi
.PP
.ft CR
.in
# pminfo -f dmstats.read dmstats.histogram.hist_count
.P
dmstats.read
    inst [0 or "looptest0"] value 4099
.P
dmstats.histogram.hist_count
    inst [0 or "looptest0:0:0s"] value 1
    inst [1 or "looptest0:0:10us"] value 3752
    inst [2 or "looptest0:0:30us"] value 250
    inst [3 or "looptest0:0:50us"] value 96
.ft 1
.SH FILES
.IP "\fB$PCP_PMDAS_DIR/dm/help\fR" 4
default help text file for the dm metrics
.IP "\fB$PCP_PMDAS_DIR/dm/Install\fR" 4
installation script for the \fBpmdadm\fR agent
.IP "\fB$PCP_PMDAS_DIR/dm/Remove\fR" 4
undo installation script for the \fBpmdadm\fR agent
.IP "\fB$PCP_LOG_DIR/pmcd/dm.log\fR" 4
default log file for error messages from \fBpmdadm\fR
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fR are used to parameterize
the file and directory names used by \fBPCP\fR. On each installation, the
file \fB/etc/pcp.conf\fR contains the local values for these variables.
The \fB$PCP_CONF\fR variable may be used to specify an alternative
configuration file, as described in \fIpcp.conf\fR(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmstore (1),
.BR dmsetup (8)
and
.BR dmstats (8).