Documentation/admin-guide/device-mapper/statistics.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/device-mapper/statistics.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/device-mapper/statistics.rst
Extension
.rst
Size
7753 bytes
Lines
226
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=============
DM statistics
=============

Device Mapper supports the collection of I/O statistics on user-defined
regions of a DM device.	 If no regions are defined no statistics are
collected so there isn't any performance impact.  Only bio-based DM
devices are currently supported.

Each user-defined region specifies a starting sector, length and step.
Individual statistics will be collected for each step-sized area within
the range specified.

The I/O statistics counters for each step-sized area of a region are
in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
Documentation/admin-guide/iostats.rst).  But two extra counters (12 and 13) are
provided: total time spent reading and writing.  When the histogram
argument is used, the 14th parameter is reported that represents the
histogram of latencies.  All these counters may be accessed by sending
the @stats_print message to the appropriate DM device via dmsetup.

The reported times are in milliseconds and the granularity depends on
the kernel ticks.  When the option precise_timestamps is used, the
reported times are in nanoseconds.

Each region has a corresponding unique identifier, which we call a
region_id, that is assigned when the region is created.	 The region_id
must be supplied when querying statistics about the region, deleting the
region, etc.  Unique region_ids enable multiple userspace programs to
request and process statistics for the same DM device without stepping
on each other's data.

The creation of DM statistics will allocate memory via kmalloc or
fallback to using vmalloc space.  At most, 1/4 of the overall system
memory may be allocated by DM statistics.  The admin can see how much
memory is used by reading:

	/sys/module/dm_mod/parameters/stats_current_allocated_bytes

Messages
========

    @stats_create <range> <step> [<number_of_optional_arguments> <optional_arguments>...] [<program_id> [<aux_data>]]
	Create a new region and return the region_id.

	<range>
	  "-"
		whole device
	  "<start_sector>+<length>"
		a range of <length> 512-byte sectors
		starting with <start_sector>.

	<step>
	  "<area_size>"
		the range is subdivided into areas each containing
		<area_size> sectors.
	  "/<number_of_areas>"
		the range is subdivided into the specified
		number of areas.

	<number_of_optional_arguments>
	  The number of optional arguments

	<optional_arguments>
	  The following optional arguments are supported:

	  precise_timestamps
		use precise timer with nanosecond resolution
		instead of the "jiffies" variable.  When this argument is
		used, the resulting times are in nanoseconds instead of

Annotation

Implementation Notes