DMSTATS(8)

📦
version 2.03.44 · 8 versions
, in arch rolling, centos-stream 10

💖 DMSTATS(8) — the maintenance commands girlie 💖

okay bestie, so dmstats is literally the Device-mapper statistics management tool, and it lives in section 8 of the manual (that's the maintenance-commands section, iykyk). she's iconic, she's powerful, and she is obsessed with IO stats. let's get into it 🦋

✨ NAME ✨

dmstats — Device-mapper statistics management 💅

🌸 SYNOPSIS 🌸

so here's the whole vibe, in exact syntax, no cap:

dmsetup stats command [OPTIONS]

dmstats command device_name|--major major --minor minor|-u|--uuid uuid
        [-v|--verbose]

dmstats clear device_name [--allprograms|--programid id] [--allregions|
        --regionid id]
dmstats create device_name ...|file_path ...|--alldevices
        [--areas nr_areas|--areasize area_size] [--bounds histogram_boundaries]
        [--filemap] [--follow follow_mode]
        [--foreground] [--nogroup] [--nomonitor] [--precise]
        [--start start_sector --length length|--segments]
        [--userdata user_data] [--programid id]
dmstats delete device_name|--alldevices [--allprograms|--programid id]
        [--allregions|--regionid id]
dmstats group [device_name|--alldevices] [--alias name]
        [--regions regions]
dmstats help [-c|-C|--columns]
dmstats list [device_name] [--allprograms|--programid id] [--area]
        [--group] [--region] [--histogram] [--nosuffix] [--notimesuffix]
        [--units units]
dmstats print [device_name] [--clear] [--allprograms|--programid id]
        [--allregions|--regionid id]
dmstats report [device_name] [--interval seconds] [--count count]
        [--units units] [--allprograms|--programid id] [--allregions|
        --regionid id] [--area] [--group] [--region] [--histogram]
        [--nosuffix] [--notimesuffix] [--units units]
        [-O|--sort sort_fields] [-S|--select selection]
dmstats ungroup [device_name|--alldevices] [--groupid id]
dmstats update_filemap file_path [--follow follow_mode] [--foreground]
        [--groupid id] [--nomonitor]

🌈 DESCRIPTION 🌈

dmstats is the program that manages IO statistics regions for devices that use the device-mapper driver. and the way that regions can be created, deleted, listed and reported on using the tool?? literally so much range. she does it all 💅

the first argument to dmstats is a command. that's the main character of the sentence, periodt.

the second argument is the device name, uuid or major and minor numbers. pick your fave, bestie.

then further options permit the selection of regions, output format control, and reporting behaviour. so you're never stuck with a vibe you don't want ✨

🫶 heads up: when no device argument is given, dmstats will by default operate on all device-mapper devices present. and the create and delete commands require the use of --alldevices when used in this way — no skipping that step, fr fr.

(part 1 of 6 — more coming, don't go anywhere 💖)

✨ OPTIONS ✨

okay bestie, this is the big one — every single flag and option, no skips, no cap. 💅

  • --alias name — set an alias name for a group. cute little nickname energy. 🎀
  • --alldevices — if no device arguments are given, allow operation on all devices when creating or deleting regions. 👑
  • --allprograms — include regions from all program IDs for list and report operations. 💜
  • --allregions — include all present regions for commands that normally accept a single region identifier. 🌈
  • --area — when performing a list or report, include objects of type area in the results. 📍
  • --areas nr_areas — specify the number of statistics areas to create within a new region. 🧩
  • --areasize area_size[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — specify the size of areas into which a new region should be divided. An optional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalize to use multiples of 1000 (S.I.) instead of 1024. ✨
  • --bounds histogram_boundaries[ns|us|ms|s] — 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, milliseconds or seconds respectively. 🦋
  • --clear — when printing statistics counters, also atomically reset them to zero. 🧼
  • --count count — specify the iteration count for repeating reports. If the count argument is zero reports will continue to repeat until interrupted. 🔁
  • --group — when performing a list or report, include objects of type group in the results. 👯
  • --filemap — instead of creating regions on a device as specified by command line options, open the file found at each file_path argument, and create regions corresponding to the locations of the on-disk extents allocated to the file(s). 🗺️
  • --follow follow_mode — specify the dmfilemapd(8) file following mode. The file map monitoring daemon can monitor files in two distinct ways: the mode affects the behaviour of the daemon when a file under monitoring is renamed or unlinked, and the conditions that cause the daemon to terminate.
    • The follow_mode argument is either "inode", for follow-inode mode, or "path", for follow-path mode.
    • If follow-inode mode is used, the daemon will hold the file open, and continue to update regions from the same file descriptor. This means that the mapping will follow rename, move (within the same file system), and unlink operations. This mode is useful if the file is expected to be moved, renamed, or unlinked while it is being monitored.
    • In follow-inode mode, the daemon will exit once it detects that the file has been unlinked and the daemon is the last holder of a reference to it.
    • If follow-path is used, the daemon will re-open the provided path on each monitoring iteration. This means that the group will be updated to reflect a new file being moved to the same path as the original file. This mode is useful for files that are expected to be updated via unlink and rename.
    • In follow-path mode, the daemon will exit if the file is removed and not replaced within a brief tolerance interval.
    • In either mode, the daemon exits automatically if the monitored group is removed.
  • --foreground — specify that the dmfilemapd(8) daemon should run in the foreground. The daemon will not fork into the background, and will replace the dmstats command that started it. 🎀
  • --groupid id — specify the group to operate on. 🫶
  • --histogram — when used with the report and list commands select default fields that emphasize latency histogram data. 📊
  • --interval seconds — specify the interval in seconds between successive iterations for repeating reports. If --interval is specified but --count is not, reports will continue to repeat until interrupted. ⏱️
  • --length length[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — specify the length of a new statistics region in sectors. An optional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalize to use multiples of 1000 (S.I.) instead of 1024. 📏
  • -j|--major major — specify the major number. 🔢
  • -m|--minor minor — specify the minor number. 🔢
  • --nogroup — when creating regions mapping the extents of a file in the file system, do not create a group or set an alias. 🙅‍♀️
  • --nomonitor — disable the dmfilemapd(8) daemon when creating new file mapped groups. Normally the device-mapper filemap monitoring daemon dmfilemapd(8), is started for each file mapped group to update the set of regions as the file changes on disk: use of this option disables this behaviour.
    • Regions in the group may still be updated with the update_filemap command, or by starting the daemon manually.
  • --nosuffix — suppress the suffix on output sizes. Use with --units (except h and H) if processing the output. 🚫
  • --notimesuffix — suppress the suffix on output time values. Histogram boundary values will be reported in units of nanoseconds. ⏳
  • -o|--options — specify which report fields to display. 🧾
  • --precise — attempt to use nanosecond precision counters when creating new statistics regions. 🎯
  • --programid id — specify a program ID string. When creating new statistics regions this string is stored with the region. Subsequent operations may supply a program ID in order to select only regions with a matching value. The default program ID for dmstats-managed regions is "dmstats". 🆔
  • --region — when performing a list or report, include objects of type region in the results. 🌍
  • --regionid id — specify the region to operate on. 🎯
  • --regions region_list — specify a list of regions to group. The group list is a comma-separated list of region identifiers. Continuous sequences of identifiers may be expressed as a hyphen-separated range, for example: '1–10'. 🔗
  • --relative — if displaying the histogram report show relative (percentage) values instead of absolute counts. 📈
  • --segments — when used with create, create a new statistics region for each target contained in the given device(s). This causes a separate region to be allocated for each segment of the device.
    • The newly created regions are automatically placed into a group unless the --nogroup option is given. When grouping is enabled a group alias may be specified using the --alias option.
  • -S|--select selection — display only rows that match selection criteria; all rows then include the additional "selected" column (-o selected), showing 1 if the row matches the selection and 0 otherwise. The selection criteria are defined by specifying column names and their valid values while making use of supported comparison operators. 🔍
  • -O|--sort sort_fields — sort output according to the list of fields given. Precede any sort field with - for a reverse sort on that column. 🔄
  • --start start[b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — specify the start offset of a new statistics region in sectors. An optional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalize to use multiples of 1000 (S.I.) instead of 1024. 🚀
  • --units [units][h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] — set the display units for report output. All sizes are output in these units: (h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalize to use multiples of 1000 (S.I.) instead of 1024. Can also specify custom units e.g. --units 3M. 📐
  • --userdata user_data — specify user data (a word) to be stored with a new region. The value is added to any internal auxiliary data (for example, group information), and stored with the region in the aux_data field provided by the kernel. Whitespace is not permitted. 🏷️
  • -u|--uuid — specify the UUID. 🆔
  • -v|--verbose [-v|--verbose] — produce additional output. 🗣️

✨ COMMANDS ✨

okay bestie, here's the whole menu of things you can actually do with dmstats 💅 every single command, no skips, no "and the rest is obvious" energy. buckle up.

🧼 clear

clear device_name [--allprograms|--programid id] [--allregions|
       --regionid id]

This one tells the kernel to clear the statistics counters for the regions you point at — with exactly one exception: the in-flight IO counters. those ones do not get cleared. don't @ me, that's just how it is. 💀

🌱 create

create device_name ...|file_path ...|--alldevices [--areas nr_areas|
       --areasize area_size] [--bounds histogram_boundaries] [--filemap]
       [--follow follow_mode] [--foreground] [--nogroup] [--nomonitor]
       [--precise] [--start start_sector --length length|--segments]
       [--userdata user_data] [--programid id]

Creates one or more brand-new statistics regions on the device(s) you named. this is the glow-up command ✨

So the region is gonna span the entire device unless you give it --start and --length, or --segments. The --start and --length options let you drop a region of whatever arbitrary length you want at whatever arbitrary offset into the device. And --segments? That makes a whole new region for each target in the corresponding device-mapper device's table. one region per target, slay.

If you use --precise, the command will attempt to create a region using nanosecond precision counters. fancy timestamps, we love her.

If --bounds is given, a latency histogram gets tracked for the new region. The boundaries of the histogram bins are given as a comma-separated list of latency values. There's an implicit lower bound of zero on the first bin, and an implicit upper bound of infinity (or the configured interval duration) on the final bin. sneaky little bounds, iconic.

Latencies are given in nanoseconds. You can also tack on an optional unit suffix of ns, us, ms, or s after each value to specify units of nanoseconds, microseconds, milliseconds or seconds respectively — so like, 10 ms is equivalent to 10,000,000 ns. math is math 🧮 Latency values with a precision of less than one millisecond can only be used when precise timestamps are enabled: if --precise is not given and values less than one millisecond are used, it will be enabled automatically. the command got you, fr fr.

An optional program_id or user_data string may be associated with the region. A program_id may then be used to select regions for subsequent list, print, and report operations. The user_data stores an arbitrary string and is not used by dmstats or the device-mapper kernel statistics subsystem — it's just vibes, a lil free-text box for you.

By default, dmstats creates regions with a program_id of "dmstats". 🎀

On success the region_id of the newly created region is printed to stdout. congrats, you made a region 💖

Now, the file stuff 👇

If the --filemap option is given with a regular file, or a list of files, as the file_path argument, then instead of creating regions with parameters specified on the command line, dmstats will open the files located at file_path and create regions corresponding to the physical extents allocated to the file. This can be used to monitor statistics for individual files in the file system — for example, virtual machine images, swap areas, or large database files.

To work with the --filemap option, files must be located on a local file system, backed by a device-mapper device, that supports physical extent data using the FIEMAP ioctl (e.g. Ext4 and XFS). no local fs, no fiemap, no dice.

By default, regions that map a file are placed into a group and the group alias is set to the basename of the file. This behaviour can be overridden with the --alias and --nogroup options.

Creating a group that maps a file automatically starts a daemon, dmfilemapd(8), to monitor the file and update the mapping as the extents allocated to the file change. This behaviour can be disabled using the --nomonitor option. (yes, a whole daemon. she's got a job and she's doing it 🫶)

Use the --group option to display information only for groups when listing and reporting.

🗑️ delete

delete device_name|--alldevices [--allprograms|--programid id]
       [--allregions|--regionid id]

Deletes the statistics region you specify. All counters and resources used by the region are released and the region will not appear in the output of subsequent list, print, or report operations. gone. poof. 💨

All regions registered on a device may be removed using --allregions.

To remove all regions on all devices, both --allregions and --alldevices must be used. both. together. besties.

If a --groupid is given instead of a --regionid, the command will attempt to delete the group and all regions that it contains.

And if a deleted region is the first member of a group of regions, the group will also be removed. bye group, we hardly knew ye 😭

🫂 group

group [device_name|--alldevices] [--alias name] [--regions regions]

Combines one or more statistics regions on the specified device into a group. friendship bracelet for your regions 💞

The list of regions to be grouped is specified with --regions, and an optional alias may be assigned with --alias. The set of regions is given as a comma-separated list of region identifiers. A continuous range of identifiers spanning from R1 to R2 may be expressed as 'R1-R2'. ranges!! so convenient.

Regions that have a histogram configured can be grouped: in this case the number of histogram bins and their bounds must match exactly. no mismatched bins in this house.

On success the group list and newly created group_id are printed to stdout. 💅

The group metadata is stored with the first (lowest numbered) region_id in the group: deleting this region will also delete the group, and other group members will be returned to their prior state. so like, that one region is holding the whole group's keys. protect her.

🆘 help

help [-c|-C|--columns]

Outputs a summary of the commands available, optionally including the list of report fields. it's the "hey what do i do now" command, always there for you 🫶

📋 list

list [device_name] [--allprograms|--programid id] [--area] [--group]
       [--region] [--histogram] [--nosuffix] [--notimesuffix]
       [--units units]

List the statistics regions, areas, or groups registered on the device. If the --allprograms switch is given, all regions will be listed regardless of region program ID values.

By default only regions and groups are included in list output. If -v or --verbose is given, the report will also include a row of information for each configured group and for each area contained in each region displayed. verbose = she's showing everything ✨

Regions that contain a single area are by default omitted from the verbose list, since their properties are identical to the area that they contain — to view all regions regardless of the number of areas present, use --region. To also view the areas contained within regions, use --area.

If --histogram is given, the report will include the bin count and latency boundary values for any configured histograms. 📊

🖨️ print

print [device_name] [--clear] [--allprograms|--programid id]
       [--allregions|--regionid id]

Print raw statistics counters for the specified region or for all present regions. raw numbers, no garnish, just data 🧚

📈 report

report [device_name] [--interval seconds] [--count count]
       [--units units] [--allprograms|--programid id] [--allregions|
       --regionid id] [--area] [--group] [--region] [--histogram]
       [--nosuffix] [--notimesuffix] [--units units]
       [-O|--sort sort_fields] [-S|--select selection]

Start a report for the specified object or for all present objects. If the count argument is specified, the report will repeat at a fixed interval set by the --interval option. The default interval is one second. tick tock, tick tock ⏰

If the --allprograms switch is given, all regions will be listed, regardless of region program ID values.

If --histogram is given, the report will include the histogram values and latency boundaries.

If --relative is used, the default histogram field displays bin values as a percentage</> of the total number of I/Os. percentages are so much cuter than raw numbers honestly.

Object types (areas, regions and groups) to include in the report are selected using the --area, --region, and --group options.

💔 ungroup

ungroup [device_name|--alldevices] [--groupid id]

Remove an existing group and return all the group's regions to their original state. it's the breakup command, but make it administrative 😭💔

The group to be removed is specified using --groupid.

🔄 update_filemap

update_filemap file_path [--follow follow_mode] [--foreground]
       [--groupid id] [--nomonitor]

Update a group of dmstats regions specified by group_id, that were previously created with --filemap, either directly, or by starting the monitoring daemon dmfilemapd(8). keeping the file mapping fresh, no cap ✨

This will add and remove regions to reflect changes in the allocated extents of the file on disk since it was created or last updated.

Use of this command is not normally needed, since the dmfilemapd(8) daemon will automatically monitor filemap groups and perform these updates when required. she handles it, you can chill 💅

If a filemapped group was created with --nomonitor, or the daemon has been killed, then update_filemap can be used to manually force an update or start a new daemon.

Use --nomonitor to force a direct update and disable starting the monitoring daemon.

💖 REGIONS, AREAS, AND GROUPS 💖

okay so this is the part where it gets good. The device-mapper statistics facility lets you keep separate performance counters for literally any arbitrary region of a device. A region can span any range — from a single sector all the way up to the whole entire device. And a region can be broken down further into a bunch of distinct areas (one or more, no cap), and each area gets its own little counter set. When you do that, you also get a summary value for the whole region that you can use in reports. bestie that's so convenient.

On top of that, one or more regions on a single device can be combined into a statistics group. Groups let several regions get aggregated and reported as one single entity — counters for every region and every area get summed up and used to report totals for all the group members. Groups also let you assign an optional alias, so you can give meaningful names to sets of regions. iconic behavior tbh.

⚠️ real talk: the group metadata is stored with the first (lowest numbered) region_id in the group. So deleting that region also deletes the group, and the other group members get returned to their prior state. do not forget this one. 💀

By default, new regions span the entire device. The --start and --length options let you place a region of any size at any location on the device. ✨

Using offsets, you can create regions that map individual objects within a block device — think partitions, files in a file system, or stripes and other structures in a RAID volume. And groups let several non-contiguous regions get assembled together for reporting and data aggregation. 🌈

A region can be either divided into the specified number of equal-sized areas, or into areas of the given size by specifying one of --areas or --areasize when you create a region with the create command. Heads up though: depending on the size of the areas and the device region, that final area within the region might come out smaller than you asked for. it's giving "close enough" 🫶

🎀 Region identifiers

Every region gets assigned an identifier when it's created, and that's what you use to reference it in all your later operations. Region identifiers are unique within a given device — and yes, that includes across different program_id values.

Depending on the sequence of create and delete operations, there can be gaps in the sequence of region_id values for a particular device. so don't freak out if the numbers skip around, that's just how it is.

Treat the region_id as an opaque identifier — it's just a handle for referencing the region. no cap.

🦋 Group identifiers

Groups also get assigned an integer identifier at creation time, and just like region identifiers, group identifiers are unique within the containing device.

The group_id should also be treated as an opaque identifier used to reference the group. same energy, different noun 💅

🌸 FILE MAPPING 🌸

Using --filemap, you can create regions that correspond to the extents of a file in the file system. This means you can monitor IO statistics on a per-file basis — like, say, to keep an eye on huge database files, virtual machine images, or literally any other file you're obsessed with. 👑

To use file mapping, the file has to be on a file system backed by a device-mapper device that supports the FIEMAP ioctl and returns data describing the physical location of extents. Currently that includes xfs(5) and ext4(5). so those two are the vibe. 🍓

By default, the regions making up a file get placed together in a group, and the group alias is set to the basename(3) of the file. That way you can report statistics for the file as a whole, aggregating values for all the regions making up the group. And if you want to see only the whole file (the group) when you use the list and report commands, use --group. ✨

Since the file can totally change after the initial group of regions is created, there's the update_filemap command and the dmfilemapd(8) daemon — so you can update file mapped groups either manually or automatically. slay.

🧚 File follow modes

The file map monitoring daemon can monitor files in two distinct ways: follow-inode mode and follow-path mode.

The mode changes how the daemon behaves when a file it's monitoring gets renamed or unlinked, and it also changes the conditions that make the daemon terminate.

If follow-inode mode is used, the daemon will hold the file open and keep updating regions from that same file descriptor. This means the mapping will follow rename, move (within the same file system), and unlink operations. So this mode is your bestie if the file is expected to be moved, renamed, or unlinked while it's being monitored. 🫶

In follow-inode mode, the daemon will exit once it detects that the file has been unlinked and the daemon is the last holder of a reference to it.

If follow-path is used, the daemon will re-open the provided path on every single monitoring iteration. That means the group gets updated to reflect a new file being moved to the same path as the original file. This mode is perfect for files that are expected to be updated via unlink and rename. 🌈

In follow-path mode, the daemon will exit if the file is removed and not replaced within a brief tolerance interval (one second).

To stop the daemon, just delete the group containing the mapped regions — the daemon will automatically shut down. 💅

The daemon can also be safely killed at any time with the group kept. But here's the catch: if the file is still being allocated, the mapping will become progressively out-of-date as extents are added and removed. In that case, you can restart the daemon or update the group manually with the update_filemap command. ⭐

See the create command and the --filemap, --follow, and --nomonitor options for further information. iykyk.

🙈 Limitations

The daemon tries its best to maintain good synchronization between the file extents and the regions contained in the group, but — because it can only react to new allocations once they have been written — there are inevitably some I/O events that just cannot be counted when a file is growing. This hits especially hard if the file is being extended by a single thread writing beyond end-of-file (for example, the dd(1) program). 😭

Events may also be lost because there is currently no way to atomically resize a dmstats region and preserve its current counter values. This affects files when they grow by extending the final extent, rather than allocating a new extent: any events that had accumulated in the region between any prior operation and the resize are lost. gone. poof. 💀

File mapping is currently most effective in cases where the majority of I/O does not trigger extent allocation. Future updates may address these limitations when kernel support is available. so... watch this space. 👀

✨ REPORT FIELDS ✨

okay so the dmstats report gives you a bunch of different types of field, right? and you can totally add them to the default field set, or use them to build your own custom reports from scratch. your report, your rules 💅

big thing to know: all performance counters and metrics are calculated per-area. every single one. no cap.

🌸 Derived metrics 🌸

so there's a whole crew of metric fields that hand you high-level performance indicators, and they're basically the glow-up version of the fields from the conventional Linux iostat program — they're all derived from the basic counter values the kernel gives you for each area. so like, the receipts come from the kernel, and these fields do the math for you 🧮✨

  • reads_merged_per_sec — reads merged per second.
  • writes_merged_per_sec — writes merged per second.
  • reads_per_sec — reads completed per second.
  • writes_per_sec — writes completed per second.
  • read_size_per_sec — size of data read per second.
  • write_size_per_sec — size of data written per second.
  • avg_request_size — average request size.
  • queue_size — average queue size.
  • await — the average wait time for read and write operations.
  • r_await — the average wait time for read operations.
  • w_await — the average wait time for write operations.
  • throughput — the device throughput, in operations per second.
  • service_time — the average service time (in milliseconds, bestie) for operations issued to the device.
  • util — percentage of elapsed time during which I/O requests were issued to the device (that's the bandwidth utilization for the device, iykyk). and heads up: device saturation occurs when this value gets close to 100% 👀🔥

🦋 Group, region and area meta fields 🦋

meta fields are the ones that spill the tea about which groups, regions, or areas the statistics values actually relate to. so that's the region and area identifier, start, length, and counts, plus the program ID and user data values. the whole context package, basically 🎀

  • region_id — the region identifier. it's a non-negative integer that the kernel hands back when a statistics region gets created.
  • region_start — where the region starts. the display units are chosen by the --units option.
  • region_len — how long the region is. display units again come from --units.
  • area_id — the area identifier. these are assigned by the device-mapper statistics library and they uniquely identify each area inside a region. every ID maps to a distinct set of performance counters for that area of the statistics region. and here's the vibe: area identifiers are always monotonically increasing within a region, so higher ID values line up with greater sector addresses within the area, and there are no gaps in the sequence of identifiers. clean and orderly, we love to see it ✨
  • area_start — where the area starts. display units selected by --units.
  • area_len — the length of the area. you already know: --units picks the display units.
  • area_count — the number of areas in this region.
  • program_id — the program ID value associated with this region.
  • user_data — the user data value associated with this region.
  • group_id — the group identifier. it's a non-negative integer returned by the dmstats group command when a statistics group is created.
  • interval_ns — the estimated interval over which the current counter values have accumulated. reported as an integer, expressed in units of nanoseconds.
  • interval — same estimated interval, same accumulated-counter-values situation, but reported as a real number in units of seconds.

💜 Basic counters 💜

basic counters give you direct access to the raw counter data straight from the kernel, so another program can do further processing on it. raw data, no filter, iconic 💅

so the kernel provides thirteen separate counters for each statistics area. the first eleven of these match the counters you'd find in /proc/diskstats or /sys/block/*/*/stat. and the final pair? those give you separate counters for read and write time. cute.

  • read_count — count of reads completed this interval.
  • reads_merged_count — count of reads merged this interval.
  • read_sector_count — count of 512-byte sectors read this interval.
  • read_time — accumulated duration of all read requests (ns).
  • write_count — count of writes completed this interval.
  • writes_merged_count — count of writes merged this interval.
  • write_sector_count — count of 512-byte sectors written this interval.
  • write_time — accumulated duration of all write requests (ns).
  • in_progress_count — count of requests currently in progress.
  • io_ticks — nanoseconds spent servicing requests.
  • queue_ticks — okay this one's a whole thing: this field gets 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 milliseconds spent doing I/O since the last update of this field. and why do we care? because it can give you an easy measure of both I/O completion time and the backlog that may be accumulating. two-for-one, slay.
  • read_ticks — nanoseconds spent servicing reads.
  • write_ticks — nanoseconds spent servicing writes.

🎀 Histogram fields 🎀

histograms measure the frequency distribution of user-specified I/O latency intervals. the histogram bin boundaries get specified when a region is created. periodt.

and you can drop a brief representation of the histogram values and latency intervals into the report using these fields 👇

  • 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.
  • hist_count_bounds — a list of the histogram counts for the current statistics area, in order of ascending latency value, including bin boundaries: each count is prefixed by the lower bound of the corresponding histogram bin.
  • hist_count_ranges — a list of the histogram counts for the current statistics area, in order of ascending latency value, including bin boundaries: each count is prefixed by both the lower and upper bounds of the corresponding histogram bin.
  • hist_percent — a list of the relative histogram values for the current statistics area, in order of ascending latency value, expressed as a percentage. each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period.
  • hist_percent_bounds — a list of the relative histogram values for the current statistics area, in order of ascending latency value, expressed as a percentage and including bin boundaries. each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period, and it's prefixed with the corresponding bin's lower bound.
  • hist_percent_ranges — a list of the relative histogram values for the current statistics area, in order of ascending latency value, expressed as a percentage and including bin boundaries. each value represents the proportion of I/Os with latency times falling into that bin's time range during the sample period, and it's prefixed with the corresponding bin's lower and upper bounds.
  • hist_bounds — a list of the histogram boundary values for the current statistics area, in order of ascending latency value. the values are expressed in whole units of seconds, milliseconds, microseconds or nanoseconds, with a suffix indicating the unit.
  • hist_ranges — a list of the histogram bin ranges for the current statistics area, in order of ascending latency value. the values are expressed as "LOWER-UPPER" in whole units of seconds, milliseconds, microseconds or nanoseconds, with a suffix indicating the unit.
  • hist_bins — the number of latency histogram bins configured for the area.

💖 EXAMPLES 💖

Okay bestie, this is the part where it all clicks. Real commands, real output, no cap. Watch and learn ✨

Create a whole-device region with one area on vg00/lvol1 🎀

# dmstats create vg00/lvol1
vg00/lvol1: Created new region with 1 area(s) as region ID 0

Create a 32 MiB region 1 GiB into device d0 🦋

# dmstats create --start 1G --length 32M d0
d0: Created new region with 1 area(s) as region ID 0

Create a whole-device region with 8 areas on every device 🌸

# dmstats create --alldevices --areas 8
vg00-lvol1: Created new region with 8 area(s) as region ID 0
vg00-lvol2: Created new region with 8 area(s) as region ID 0
vg00-lvol3: Created new region with 8 area(s) as region ID 0
vg01-lvol0: Created new region with 8 area(s) as region ID 2
vg01-lvol1: Created new region with 8 area(s) as region ID 0
vg00-lvol2: Created new region with 8 area(s) as region ID 1

Delete all regions on all devices 💅

# dmstats delete --alldevices --allregions

Create a whole-device region with areas 10 GiB in size on vg00/lvol1 using dmsetup 👑

# dmsetup stats create --areasize 10G vg00/lvol1
vg00-lvol1: Created new region with 5 area(s) as region ID 1

Create a 1 GiB region with 16 areas at the start of vg00/lvol1 🍓

# dmstats create --start 0 --length 1G --areas=16 vg00/lvol1
vg00-lvol1: Created new region with 16 area(s) as region ID 0

List the statistics regions registered on vg00/lvol1 ✨

# dmstats list vg00/lvol1
Name         RgID RStart  RSize  #Areas ASize  ProgID
vg00-lvol1    0    0      61.00g  1     61.00g dmstats
vg00-lvol1    1   61.00g  19.20g  1     19.20g dmstats
vg00-lvol1    2   80.20g   2.14g  1      2.14g dmstats

Display five statistics reports for vg00/lvol1 at an interval of one second ⏱️

# dmstats report --interval 1 --count 5 vg00/lvol1
# dmstats report
Name        RgID ArID AStart ASize  RRqM/s WRqM/s R/s →
vg00-lvol1   0    0    0    61.00g  0.00   0.00  0.00
vg00-lvol1   1    0  61.00g 19.20g  0.00   0.00  0.00
vg00-lvol1   2    0  80.20g  2.14g  0.00   0.00  0.00

→ W/s  RSz/s  WSz/s   AvRqSz  QSize Util% AWait RdAWa WrAWa
218.00 0.00     1.04m   4.50k 2.97  81.70 13.62 0.00  13.62
  5.00 0.00   548.00k 109.50k 0.14  11.00 27.40 0.00  27.40
 14.00 0.00     1.15m  84.00k 0.39  18.70 27.71 0.00  27.71
That little → in there? It's the manpage telling you the row wraps around, bestie. The header got too long for one line so it just keeps going. It's giving ✨sideways✨.

Create one region for each target contained in device vg00/lvol1 🌈

# dmstats create --segments vg00/lvol1
vg00-lvol1: Created new region with 1 area(s) as region ID 0
vg00-lvol1: Created new region with 1 area(s) as region ID 1
vg00-lvol1: Created new region with 1 area(s) as region ID 2

Create regions mapping each file in the directory images/ and place them into separate groups, each named after the corresponding file. 🧚

# dmstats create --filemap images/*
images/vm1.qcow2: Created new group with 87 region(s) as group ID 0.
images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87.
images/vm2.qcow2: Created new group with 11 region(s) as group ID 95.
images/vm2-1.qcow2: Created new group with 1454 region(s) as group ID 106.
images/vm3.img: Created new group with 2 region(s) as group ID 1560.

Print raw counters for region 4 on device d0 🔥

# dmstats print --regionid 4 d0
2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41

🫶 AUTHORS 🫶

  • Bryn M. Reeves

The icon who built this. Respect. 👑

💜 SEE ALSO 💜

Documentation/device-mapper/statistics.txt

And that's the whole page, bestie!! 🎉 Go forth and measure literally every I/O your kernel does. Slay. 💅✨

This one's from the Linux fam, dated Mar 23 2025, and it's filed under DMSTATS(8) — iykyk. 🦋🌸🎀

📦 where this page comes from