Ubuntu Manpage: pmdadm - Device Mapper PMDA

name
description
installation
files
dmstats metric
examples
pcp environment
see also

NAME

       pmdadm - Device Mapper PMDA

DESCRIPTION

       pmdadm  is a Performance Metrics Domain Agent (PMDA) which exports metric values for Device Mapper on the
       local system.

       This PMDA collects its data through the dmsetup(8) utility, dmstats API and requires that the program  is
       installed in order to function.

       In  addition,  at  least  a statistics region must be created to use dmstats(8) in order to get the basic
       counter value.

       Further details on device mapper can be found at http://redhat.com

INSTALLATION

       Install the DM PMDA by using the Install script as root:

             # cd $PCP_PMDAS_DIR/dm
             # ./Install

       To uninstall, do the following as root:

             # cd $PCP_PMDAS_DIR/dm
             # ./Remove

       pmdadm is launched by pmcd(1) and should never be executed directly.   The  Install  and  Remove  scripts
       notify pmcd when the agent is installed or removed.

FILES

       $PCP_PMDAS_DIR/dm/help
           default help text file for the dm metrics

       $PCP_PMDAS_DIR/dm/Install
           installation script for the pmdadm agent

       $PCP_PMDAS_DIR/dm/Remove
           undo installation script for the pmdadm agent

       $PCP_LOG_DIR/pmcd/dm.log
           default log file for error messages from pmdadm

dmstats metric

This PMDA use the dmstats API (the userspace device-mapper support library) to allow dmstats performance
data.
Using this PMDA, users need the userspace device-mapper support library (libdevmapper) and the userspace
command line tool (dmstats). Before getting the statistics metric, statistics regions have to be
created. When creating the statistics regions of all device-mapper device under /dev/mapper as below:

# dmstats create --alldevices

When creating the statistics regions with specified histogram boundaries as below:

# dmstats create --alldevices --bounds histogram_boundaries

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 ns, us, ms, or s may
be given after each value to specify units of nanoseconds, microseconds, miliseconds or seconds
respectively.
Further Detail on dmstats(8) can be found at man page.

Basic Counters
Basic counters provide access to the raw counter data from the kernel, allowing further processing to
be carried out by another program.
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.

dmstats.read
Count of reads completed this interval per device-mapper device.

dmstats.reads_merged
Count of reads merged this interval per device-mapper device.

dmstats.read_bytes
Count of kbytes read this interval per device-mapper device.

dmstats.reads_time
Accumulated duration of all read requests per device-mapper device.

dmstats.write
Count of writes completed this interval per device-mapper device.

dmstats.writes_merged
Count of writes completed this interval per device-mapper device.

dmstats.write_bytes
Count of kbytes write this interval per device-mapper device.

dmstats.writes_time
Accumulated duration of all write requests per device-mapper device.

dmstats.in_progress
Count of requests currently in progress per device-mapper device.

dmstats.io_ticks
Nanoseconds spent servicing request per device-mapper device.

dmstats.queue_ticks
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.

dmstats.read_ticks
Nanoseconds spent servicing reads per device-mapper device.

dmstats.write_ticks
Nanoseconds spent servicing writes per device-mapper device.

Histogram fields
Histograms measure the frequency distribution of user specified I/O latency intervals. Histogram bin
boundaries are specified when a region is created.
Instance name represents devicename, region id and bin boundaries.

dmstats.histogram.hist_count
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.

dmstats.histogram.hist.bins
The number of latency histogram bins configured for the area.

Examples

            # dmstats create looptest0 --bounds 10us,30us,50us
            looptest0: Created new region with 1 area(s) as region ID 0

            # pminfo -f dmstats.read dmstats.histogram.hist_count
            dmstats.read
                inst [0 or "looptest0"] value 4099

            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

PCP ENVIRONMENT

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