{ "mode": "man", "parameter": "dmstats", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/dmstats/8/json", "generated": "2026-09-12T05:59:48Z", "synopsis": "dmsetup stats command [OPTIONS]\ndmstats command devicename | --major major --minor minor | -u|--uuid uuid [-v|--verbose]\ndmstats clear devicename [--allprograms|--programid id] [--allregions|--regionid id]\ndmstats create devicename...|filepath...|--alldevices [--areas nrareas|--areasize\nareasize] [--bounds histogramboundaries] [--filemap] [--follow followmode]\n[--foreground] [--nomonitor] [--nogroup] [--precise] [--start startsector --length\nlength|--segments] [--userdata userdata] [--programid id]\ndmstats delete devicename|--alldevices [--allprograms|--programid id]\n[--allregions|--regionid id]\ndmstats group [devicename|--alldevices] [--alias name] [--regions regions]\ndmstats help [-c|-C|--columns]\ndmstats list [devicename] [--histogram] [--allprograms|--programid id] [--units units]\n[--area] [--region] [--group] [--nosuffix] [--notimesuffix] [-v|--verbose]\ndmstats print [devicename] [--clear] [--allprograms|--programid id] [--allregions|--regionid\nid]\ndmstats report [devicename] [--interval seconds] [--count count] [--units units]\n[--histogram] [--allprograms|--programid id] [--allregions|--regionid id] [--area]\n[--region] [--group] [-O|--sort sortfields] [-S|--select selection] [--units units]\n[--nosuffix] [--notimesuffix]\ndmstats ungroup [devicename|--alldevices] [--groupid id]\ndmstats updatefilemap filepath [--groupid id] [--follow followmode] [--foreground]", "sections": { "NAME": { "content": "dmstats — device-mapper statistics management\n", "subsections": [] }, "SYNOPSIS": { "content": "dmsetup stats command [OPTIONS]\n\n\ndmstats command devicename | --major major --minor minor | -u|--uuid uuid [-v|--verbose]\ndmstats clear devicename [--allprograms|--programid id] [--allregions|--regionid id]\ndmstats create devicename...|filepath...|--alldevices [--areas nrareas|--areasize\nareasize] [--bounds histogramboundaries] [--filemap] [--follow followmode]\n[--foreground] [--nomonitor] [--nogroup] [--precise] [--start startsector --length\nlength|--segments] [--userdata userdata] [--programid id]\ndmstats delete devicename|--alldevices [--allprograms|--programid id]\n[--allregions|--regionid id]\ndmstats group [devicename|--alldevices] [--alias name] [--regions regions]\ndmstats help [-c|-C|--columns]\ndmstats list [devicename] [--histogram] [--allprograms|--programid id] [--units units]\n[--area] [--region] [--group] [--nosuffix] [--notimesuffix] [-v|--verbose]\ndmstats print [devicename] [--clear] [--allprograms|--programid id] [--allregions|--regionid\nid]\ndmstats report [devicename] [--interval seconds] [--count count] [--units units]\n[--histogram] [--allprograms|--programid id] [--allregions|--regionid id] [--area]\n[--region] [--group] [-O|--sort sortfields] [-S|--select selection] [--units units]\n[--nosuffix] [--notimesuffix]\ndmstats ungroup [devicename|--alldevices] [--groupid id]\ndmstats updatefilemap filepath [--groupid id] [--follow followmode] [--foreground]\n", "subsections": [] }, "DESCRIPTION": { "content": "The dmstats program manages IO statistics regions for devices that use the device-mapper dri‐\nver. Statistics regions may be created, deleted, listed and reported on using the tool.\n\nThe first argument to dmstats is a command.\n\nThe second argument is the device name, uuid or major and minor numbers.\n\nFurther options permit the selection of regions, output format control, and reporting behav‐\niour.\n\nWhen no device argument is given dmstats will by default operate on all device-mapper devices\npresent. The create and delete commands require the use of --alldevices when used in this\nway.\n", "subsections": [] }, "OPTIONS": { "content": "--alias name\nSpecify an alias name for a group.\n", "subsections": [ { "name": "--alldevices", "content": "If no device arguments are given allow operation on all devices when creating or\ndeleting regions.\n", "long": "--alldevices" }, { "name": "--allprograms", "content": "Include regions from all program IDs for list and report operations.\n", "long": "--allprograms" }, { "name": "--allregions", "content": "Include all present regions for commands that normally accept a single region identi‐\nfier.\n\n--area When peforming a list or report, include objects of type area in the results.\n\n--areas nrareas\nSpecify the number of statistics areas to create within a new region.\n\n--areasize areasize[\nb|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\nshould be divided. An optional suffix selects units of: (b)ytes, (s)ectors,\n(k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capi‐\ntalise to use multiples of 1000 (S.I.) instead of 1024.\n", "long": "--allregions" }, { "name": "--clear", "content": "When printing statistics counters, also atomically reset them to zero.\n\n--count count\nSpecify the iteration count for repeating reports. If the count argument is zero re‐\nports will continue to repeat until interrupted.\n", "long": "--clear" }, { "name": "--group", "content": "When peforming a list or report, include objects of type group in the results.\n", "long": "--group" }, { "name": "--filemap", "content": "Instead of creating regions on a device as specified by command line options, open the\nfile found at each filepath argument, and create regions corresponding to the loca‐\ntions of the on-disk extents allocated to the file(s).\n", "long": "--filemap" }, { "name": "--nomonitor", "content": "Disable the dmfilemapd daemon when creating new file mapped groups. Normally the de‐\nvice-mapper filemap monitoring daemon, dmfilemapd, is started for each file mapped\ngroup to update the set of regions as the file changes on-disk: use of this option\ndisables this behaviour.\n\nRegions in the group may still be updated with the updatefilemap command, or by\nstarting the daemon manually.\n\n--follow followmode\nSpecify the dmfilemapd file following mode. The file map monitoring daemon can monitor\nfiles in two distinct ways: the mode affects the behaviour of the daemon when a file\nunder monitoring is renamed or unlinked, and the conditions which cause the daemon to\nterminate.\n\nThe followmode argument is either \"inode\", for follow-inode mode, or \"path\", for fol‐\nlow-path.\n\nIf follow-inode mode is used, the daemon will hold the file open, and continue to up‐\ndate regions from the same file descriptor. This means that the mapping will follow\nrename, move (within the same file system), and unlink operations. This mode is useful\nif the file is expected to be moved, renamed, or unlinked while it is being monitored.\n\nIn follow-inode mode, the daemon will exit once it detects that the file has been un‐\nlinked and it is the last holder of a reference to it.\n\nIf follow-path is used, the daemon will re-open the provided path on each monitoring\niteration. This means that the group will be updated to reflect a new file being moved\nto the same path as the original file. This mode is useful for files that are expected\nto be updated via unlink and rename.\n\nIn follow-path mode, the daemon will exit if the file is removed and not replaced\nwithin a brief tolerance interval.\n\nIn either mode, the daemon exits automatically if the monitored group is removed.\n", "long": "--nomonitor" }, { "name": "--foreground", "content": "Specify that the dmfilemapd daemon should run in the foreground. The daemon will not\nfork into the background, and will replace the dmstats command that started it.\n\n--groupid id\nSpecify the group to operate on.\n\n--bounds histogramboundaries\n[ns|us|ms|s] Specify the boundaries of a latency histogram to be tracked for the re‐\ngion as a comma separated list of latency values. Latency values are given in nanosec‐\nonds. An optional unit suffix of ns,us,ms, or s may be given after each value to spec‐\nify units of nanoseconds, microseconds, miliseconds or seconds respectively.\n", "long": "--foreground" }, { "name": "--histogram", "content": "When used with the report and list commands select default fields that emphasize la‐\ntency histogram data.\n\n--interval seconds\nSpecify the interval in seconds between successive iterations for repeating reports.\nIf --interval is specified but --count is not, reports will continue to repeat until\ninterrupted.\n\n--length length[\nb|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] Specify the length of a new statistics region in sec‐\ntors. An optional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes,\n(m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use\nmultiples of 1000 (S.I.) instead of 1024.\n", "long": "--histogram" }, { "name": "-j --major _", "content": "Specify the major number.\n", "flag": "-j", "long": "--major" }, { "name": "-m --minor _", "content": "Specify the minor number.\n", "flag": "-m", "long": "--minor" }, { "name": "--nogroup", "content": "When creating regions mapping the extents of a file in the file system, do not create\na group or set an alias.\n", "long": "--nogroup" }, { "name": "--nosuffix", "content": "Suppress the suffix on output sizes. Use with --units (except h and H) if processing\nthe output.\n", "long": "--nosuffix" }, { "name": "--notimesuffix", "content": "Suppress the suffix on output time values. Histogram boundary values will be reported\nin units of nanoseconds.\n", "long": "--notimesuffix" }, { "name": "-o --options", "content": "Specify which report fields to display.\n", "flag": "-o", "long": "--options" }, { "name": "-O --sort _", "content": "Sort output according to the list of fields given. Precede any sort field with '-' for\na reverse sort on that column.\n", "flag": "-O", "long": "--sort" }, { "name": "--precise", "content": "Attempt to use nanosecond precision counters when creating new statistics regions.\n\n--programid id\nSpecify a program ID string. When creating new statistics regions this string is\nstored with the region. Subsequent operations may supply a program ID in order to se‐\nlect only regions with a matching value. The default program ID for dmstats-managed\nregions is \"dmstats\".\n", "long": "--precise" }, { "name": "--region", "content": "When peforming a list or report, include objects of type region in the results.\n\n--regionid id\nSpecify the region to operate on.\n\n--regions regionlist\nSpecify a list of regions to group. The group list is a comma-separated list of region\nidentifiers. Continuous sequences of identifiers may be expressed as a hyphen separat‐\ned range, for example: '1-10'.\n", "long": "--region" }, { "name": "--relative", "content": "If displaying the histogram report show relative (percentage) values instead of ab‐\nsolute counts.\n", "long": "--relative" }, { "name": "-S --select _", "content": "Display only rows that match selection criteria. All rows with the additional \"select‐\ned\" column (-o selected) showing 1 if the row matches the selection and 0 otherwise.\nThe selection criteria are defined by specifying column names and their valid values\nwhile making use of supported comparison operators.\n\n--start start[\nb|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E] Specify the start offset of a new statistics region\nin sectors. An optional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes,\n(m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use\nmultiples of 1000 (S.I.) instead of 1024.\n", "flag": "-S", "long": "--select" }, { "name": "--segments", "content": "When used with create, create a new statistics region for each target contained in the\ngiven device(s). This causes a separate region to be allocated for each segment of the\ndevice.\n\nThe newly created regions are automatically placed into a group unless the --nogroup\noption is given. When grouping is enabled a group alias may be specified using the\n--alias option.\n", "long": "--segments" }, { "name": "--units", "content": "[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.\nAll sizes are output in these units: (h)uman-readable, (b)ytes, (s)ectors,\n(k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capi‐\ntalise to use multiples of 1000 (S.I.) instead of 1024. Can also specify custom units\ne.g. --units 3M.\n\n--userdata userdata\nSpecify user data (a word) to be stored with a new region. The value is added to any\ninternal auxiliary data (for example, group information), and stored with the region\nin the auxdata field provided by the kernel. Whitespace is not permitted.\n", "long": "--units" }, { "name": "-u --uuid", "content": "Specify the uuid.\n", "flag": "-u", "long": "--uuid" }, { "name": "-v --verbose -v --verbose", "content": "Produce additional output.\n", "flag": "-v", "long": "--verbose" } ] }, "COMMANDS": { "content": "clear devicename [--allprograms|--programid id] [--allregions|--regionid id]\nInstructs the kernel to clear statistics counters for the speficied regions (with the\nexception of in-flight IO counters).\n\ncreate devicename...|filepath...|--alldevices [--areas nrareas|--areasize areasize]\n[--bounds histogramboundaries] [--filemap] [--follow followmode] [--foreground]\n[--nomonitor] [--nogroup] [--precise] [--start startsector --length\nlength|--segments] [--userdata userdata] [--programid id]\nCreates one or more new statistics regions on the specified device(s).\n\nThe region will span the entire device unless --start and --length or --segments are\ngiven. The --start an --length options allow a region of arbitrary length to be placed\nat an arbitrary offset into the device. The --segments option causes a new region to\nbe created for each target in the corresponding device-mapper device's table.\n\nIf the --precise option is used the command will attempt to create a region using\nnanosecond precision counters.\n\nIf --bounds is given a latency histogram will be tracked for the new region. The\nboundaries of the histogram bins are given as a comma separated list of latency val‐\nues. There is an implicit lower bound of zero on the first bin and an implicit upper\nbound of infinity (or the configured interval duration) on the final bin.\n\nLatencies are given in nanoseconds. An optional unit suffix of ns, us, ms, or s may be\ngiven after each value to specify units of nanoseconds, microseconds, miliseconds or\nseconds respectively, so for example, 10ms is equivalent to 10000000. Latency values\nwith a precision of less than one milisecond can only be used when precise timestamps\nare enabled: if --precise is not given and values less than one milisecond are used it\nwill be enabled automatically.\n\nAn optional programid or userdata string may be associated with the region. A pro‐\ngramid may then be used to select regions for subsequent list, print, and report op‐\nerations. The userdata stores an arbitrary string and is not used by dmstats or the\ndevice-mapper kernel statistics subsystem.\n\nBy default dmstats creates regions with a programid of \"dmstats\".\n\nOn success the regionid of the newly created region is printed to stdout.\n\nIf the --filemap option is given with a regular file, or list of files, as the\nfilepath argument, instead of creating regions with parameters specified on the com‐\nmand line, dmstats will open the files located at filepath and create regions corre‐\nsponding to the physical extents allocated to the file. This can be used to monitor\nstatistics for individual files in the file system, for example, virtual machine im‐\nages, swap areas, or large database files.\n\nTo work with the --filemap option, files must be located on a local file system,\nbacked by a device-mapper device, that supports physical extent data using the FIEMAP\nioctl (Ext4 and XFS for e.g.).\n\nBy default regions that map a file are placed into a group and the group alias is set\nto the basename of the file. This behaviour can be overridden with the --alias and\n--nogroup options.\n\nCreating a group that maps a file automatically starts a daemon, dmfilemapd to monitor\nthe file and update the mapping as the extents allocated to the file change. This be‐\nhaviour can be disabled using the --nomonitor option.\n\nUse the --group option to only display information for groups when listing and report‐\ning.\n\ndelete devicename|--alldevices [--allprograms|--programid id] [--allregions|--regionid id]\nDelete the specified statistics region. All counters and resources used by the region\nare released and the region will not appear in the output of subsequent list, print,\nor report operations.\n\nAll regions registered on a device may be removed using --allregions.\n\nTo remove all regions on all devices both --allregions and --alldevices must be used.\n\nIf a --groupid is given instead of a --regionid the command will attempt to delete the\ngroup and all regions that it contains.\n\nIf a deleted region is the first member of a group of regions the group will also be\nremoved.\n\ngroup [devicename|--alldevices] [--alias name] [--regions regions]\nCombine one or more statistics regions on the specified device into a group.\n\nThe list of regions to be grouped is specified with --regions and an optional alias\nmay be assigned with --alias. The set of regions is given as a comma-separated list of\nregion identifiers. A continuous range of identifers spanning from R1 to R2 may be ex‐\npressed as 'R1-R2'.\n\nRegions that have a histogram configured can be grouped: in this case the number of\nhistogram bins and their bounds must match exactly.\n\nOn success the group list and newly created groupid are printed to stdout.\n\nThe group metadata is stored with the first (lowest numbered) regionid in the group:\ndeleting this region will also delete the group and other group members will be re‐\nturned to their prior state.\n\nhelp [-c|-C|--columns]\nOutputs a summary of the commands available, optionally including the list of report\nfields.\n\nlist [devicename] [--histogram] [--allprograms|--programid id] [--units units] [--area]\n[--region] [--group] [--nosuffix] [--notimesuffix] [-v|--verbose]\nList the statistics regions, areas, or groups registered on the device. If the --all‐\nprograms switch is given all regions will be listed regardless of region program ID\nvalues.\n\nBy default only regions and groups are included in list output. If -v or --verbose is\ngiven the report will also include a row of information for each configured group and\nfor each area contained in each region displayed.\n\nRegions that contain a single area are by default omitted from the verbose list since\ntheir properties are identical to the area that they contain - to view all regions re‐\ngardless of the number of areas present use --region). To also view the areas con‐\ntained within regions use --area.\n\nIf --histogram is given the report will include the bin count and latency boundary\nvalues for any configured histograms.\n\nprint [devicename] [--clear] [--allprograms|--programid id] [--allregions|--regionid id]\nPrint raw statistics counters for the specified region or for all present regions.\n\nreport [devicename] [--interval seconds] [--count count] [--units units] [--histogram]\n[--allprograms|--programid id] [--allregions|--regionid id] [--area] [--region]\n[--group] [-O|--sort sortfields] [-S|--select selection] [--units units] [--nosuffix]\n[--notimesuffix]\nStart a report for the specified object or for all present objects. If the count argu‐\nment is specified, the report will repeat at a fixed interval set by the --interval\noption. The default interval is one second.\n\nIf the --allprograms switch is given, all regions will be listed, regardless of region\nprogram ID values.\n\nIf the --histogram is given the report will include the histogram values and latency\nboundaries.\n\nIf the --relative is used the default histogram field displays bin values as a per‐\ncentage of the total number of I/Os.\n\nObject types (areas, regions and groups) to include in the report are selected using\nthe --area, --region, and --group options.\n\nungroup [devicename|--alldevices] [--groupid id]\nRemove an existing group and return all the group's regions to their original state.\n\nThe group to be removed is specified using --groupid.\n\nupdatefilemap filepath [--groupid id] [--follow followmode] [--foreground]\nUpdate a group of dmstats regions specified by groupid, that were previously created\nwith --filemap, either directly, or by starting the monitoring daemon, dmfilemapd.\n\nThis will add and remove regions to reflect changes in the allocated extents of the\nfile on-disk, since the time that it was crated or last updated.\n\nUse of this command is not normally needed since the dmfilemapd daemon will automati‐\ncally monitor filemap groups and perform these updates when required.\n\nIf a filemapped group was created with --nomonitor, or the daemon has been killed, the\nupdatefilemap can be used to manually force an update or start a new daemon.\n\nUse --nomonitor to force a direct update and disable starting the monitoring daemon.\n\nREGIONS, AREAS, AND GROUPS\nThe device-mapper statistics facility allows separate performance counters to be maintained\nfor arbitrary regions of devices. A region may span any range: from a single sector to the\nwhole device. A region may be further sub-divided into a number of distinct areas (one or\nmore), each with its own counter set. In this case a summary value for the entire region is\nalso available for use in reports.\n\nIn addition, one or more regions on one device can be combined into a statistics group.\nGroups allow several regions to be aggregated and reported as a single entity; counters for\nall regions and areas are summed and used to report totals for all group members. Groups also\npermit the assignment of an optional alias, allowing meaningful names to be associated with\nsets of regions.\n\nThe group metadata is stored with the first (lowest numbered) regionid in the group: delet‐\ning this region will also delete the group and other group members will be returned to their\nprior state.\n\nBy default new regions span the entire device. The --start and --length options allows a re‐\ngion of any size to be placed at any location on the device.\n\nUsing offsets it is possible to create regions that map individual objects within a block de‐\nvice (for example: partitions, files in a file system, or stripes or other structures in a\nRAID volume). Groups allow several non-contiguous regions to be assembled together for re‐\nporting and data aggregation.\n\nA region may be either divided into the specified number of equal-sized areas, or into areas\nof the given size by specifying one of --areas or --areasize when creating a region with the\ncreate command. Depending on the size of the areas and the device region the final area with‐\nin the region may be smaller than requested.\n", "subsections": [ { "name": "Region identifiers", "content": "Each region is assigned an identifier when it is created that is used to reference the region\nin subsequent operations. Region identifiers are unique within a given device (including\nacross different programid values).\n\nDepending on the sequence of create and delete operations, gaps may exist in the sequence of\nregionid values for a particular device.\n\nThe regionid should be treated as an opaque identifier used to reference the region.\n" }, { "name": "Group identifiers", "content": "Groups are also assigned an integer identifier at creation time; like region identifiers,\ngroup identifiers are unique within the containing device.\n\nThe groupid should be treated as an opaque identifier used to reference the group.\n" } ] }, "FILE MAPPING": { "content": "Using --filemap, it is possible to create regions that correspond to the extents of a file in\nthe file system. This allows IO statistics to be monitored on a per-file basis, for example\nto observe large database files, virtual machine images, or other files of interest.\n\nTo be able to use file mapping, the file must be backed by a device-mapper device, and in a\nfile system that supports the FIEMAP ioctl (and which returns data describing the physical\nlocation of extents). This currently includes xfs(5) and ext4(5).\n\nBy default the regions making up a file are placed together in a group, and the group alias\nis set to the basename(3) of the file. This allows statistics to be reported for the file as\na whole, aggregating values for the regions making up the group. To see only the whole file\n(group) when using the list and report commands, use --group.\n\nSince it is possible for the file to change after the initial group of regions is created,\nthe updatefilemap command, and dmfilemapd daemon are provided to update file mapped groups\neither manually or automatically.\n", "subsections": [ { "name": "File follow modes", "content": "The file map monitoring daemon can monitor files in two distinct ways: follow-inode mode, and\nfollow-path mode.\n\nThe mode affects the behaviour of the daemon when a file under monitoring is renamed or un‐\nlinked, and the conditions which cause the daemon to terminate.\n\nIf follow-inode mode is used, the daemon will hold the file open, and continue to update re‐\ngions from the same file descriptor. This means that the mapping will follow rename, move\n(within the same file system), and unlink operations. This mode is useful if the file is ex‐\npected to be moved, renamed, or unlinked while it is being monitored.\n\nIn follow-inode mode, the daemon will exit once it detects that the file has been unlinked\nand it is the last holder of a reference to it.\n\nIf follow-path is used, the daemon will re-open the provided path on each monitoring itera‐\ntion. This means that the group will be updated to reflect a new file being moved to the same\npath as the original file. This mode is useful for files that are expected to be updated via\nunlink and rename.\n\nIn follow-path mode, the daemon will exit if the file is removed and not replaced within a\nbrief tolerance interval (one second).\n\nTo stop the daemon, delete the group containing the mapped regions: the daemon will automati‐\ncally shut down.\n\nThe daemon can also be safely killed at any time and the group kept: if the file is still be‐\ning allocated the mapping will become progressively out-of-date as extents are added and re‐\nmoved (in this case the daemon can be re-started or the group updated manually with the up‐\ndatefilemap command).\n\nSee the create command and --filemap, --follow, and --nomonitor options for further informa‐\ntion.\n" }, { "name": "Limitations", "content": "The daemon attempts to maintain good synchronisation between the file extents and the regions\ncontained in the group, however, since it can only react to new allocations once they have\nbeen written, there are inevitably some IO events that cannot be counted when a file is grow‐\ning, particularly if the file is being extended by a single thread writing beyond end-of-file\n(for example, the dd program).\n\nThere is a further loss of events in that there is currently no way to atomically resize a\ndmstats region and preserve its current counter values. This affects files when they grow by\nextending the final extent, rather than allocating a new extent: any events that had accumu‐\nlated in the region between any prior operation and the resize are lost.\n\nFile mapping is currently most effective in cases where the majority of IO does not trigger\nextent allocation. Future updates may address these limitations when kernel support is avail‐\nable.\n" } ] }, "REPORT FIELDS": { "content": "The dmstats report provides several types of field that may be added to the default field\nset, or used to create custom reports.\n\nAll performance counters and metrics are calculated per-area.\n", "subsections": [ { "name": "Derived metrics", "content": "A number of metrics fields are included that provide high level performance indicators. These\nare based on the fields provided by the conventional Linux iostat program and are derived\nfrom the basic counter values provided by the kernel for each area.\n" }, { "name": "reads_merged_per_sec", "content": "Reads merged per second.\n" }, { "name": "writes_merged_per_sec", "content": "Writes merged per second.\n" }, { "name": "reads_per_sec", "content": "Reads completed per second.\n" }, { "name": "writes_per_sec", "content": "Writes completed per second.\n" }, { "name": "read_size_per_sec", "content": "Size of data read per second.\n" }, { "name": "write_size_per_sec", "content": "Size of data written per second.\n" }, { "name": "avg_request_size", "content": "Average request size.\n" }, { "name": "queue_size", "content": "Average queue size.\n\nawait The average wait time for read and write operations.\n" }, { "name": "r_await", "content": "The average wait time for read operations.\n" }, { "name": "w_await", "content": "The average wait time for write operations.\n" }, { "name": "throughput", "content": "The device throughput in operations per second.\n" }, { "name": "service_time", "content": "The average service time (in milliseconds) for operations issued to the device.\n\nutil Percentage of CPU time during which I/O requests were issued to the device (bandwidth\nutilization for the device). Device saturation occurs when this value is close to\n100%.\n" }, { "name": "Group, region and area meta fields", "content": "Meta fields provide information about the groups, regions, or areas that the statistics val‐\nues relate to. This includes the region and area identifier, start, length, and counts, as\nwell as the program ID and user data values.\n" }, { "name": "region_id", "content": "Region identifier. This is a non-negative integer returned by the kernel when a sta‐\ntistics region is created.\n" }, { "name": "region_start", "content": "The region start location. Display units are selected by the --units option.\n" }, { "name": "region_len", "content": "The length of the region. Display units are selected by the --units option.\n" }, { "name": "area_id", "content": "Area identifier. Area identifiers are assigned by the device-mapper statistics library\nand uniquely identify each area within a region. Each ID corresponds to a distinct set\nof performance counters for that area of the statistics region. Area identifiers are\nalways monotonically increasing within a region so that higher ID values correspond to\ngreater sector addresses within the area and no gaps in the sequence of identifiers\nexist.\n" }, { "name": "area_start", "content": "The area start location. Display units are selected by the --units option.\n" }, { "name": "area_len", "content": "The length of the area. Display units are selected by the --units option.\n" }, { "name": "area_count", "content": "The number of areas in this region.\n" }, { "name": "program_id", "content": "The program ID value associated with this region.\n" }, { "name": "user_data", "content": "The user data value associated with this region.\n" }, { "name": "group_id", "content": "Group identifier. This is a non-negative integer returned by the dmstats group command\nwhen a statistics group is created.\n" }, { "name": "interval_ns", "content": "The estimated interval over which the current counter values have accumulated. The\nvalue is reported as an integer expressed in units of nanoseconds.\n" }, { "name": "interval", "content": "The estimated interval over which the current counter values have accumulated. The\nvalue is reported as a real number in units of seconds.\n" }, { "name": "Basic counters", "content": "Basic counters provide access to the raw counter data from the kernel, allowing further pro‐\ncessing to be carried out by another program.\n\nThe kernel provides thirteen separate counters for each statistics area. The first eleven of\nthese match the counters provided in /proc/diskstats or /sys/block/*/*/stat. The final pair\nprovide separate counters for read and write time.\n" }, { "name": "read_count", "content": "Count of reads completed this interval.\n" }, { "name": "reads_merged_count", "content": "Count of reads merged this interval.\n" }, { "name": "read_sector_count", "content": "Count of 512 byte sectors read this interval.\n" }, { "name": "read_time", "content": "Accumulated duration of all read requests (ns).\n" }, { "name": "write_count", "content": "Count of writes completed this interval.\n" }, { "name": "writes_merged_count", "content": "Count of writes merged this interval.\n" }, { "name": "write_sector_count", "content": "Count of 512 byte sectors written this interval.\n" }, { "name": "write_time", "content": "Accumulated duration of all write requests (ns).\n" }, { "name": "in_progress_count", "content": "Count of requests currently in progress.\n" }, { "name": "io_ticks", "content": "Nanoseconds spent servicing requests.\n" }, { "name": "queue_ticks", "content": "This field is incremented at each I/O start, I/O completion, I/O merge, or read of\nthese stats by the number of I/Os in progress multiplied by the number of milliseconds\nspent doing I/O since the last update of this field. This can provide an easy measure\nof both I/O completion time and the backlog that may be accumulating.\n" }, { "name": "read_ticks", "content": "Nanoseconds spent servicing reads.\n" }, { "name": "write_ticks", "content": "Nanoseconds spent servicing writes.\n" }, { "name": "Histogram fields", "content": "Histograms measure the frequency distribution of user specified I/O latency intervals. His‐\ntogram bin boundaries are specified when a region is created.\n\nA brief representation of the histogram values and latency intervals can be included in the\nreport using these fields.\n" }, { "name": "hist_count", "content": "A list of the histogram counts for the current statistics area in order of ascending\nlatency value. Each value represents the number of I/Os with latency times falling in‐\nto that bin's time range during the sample period.\n" }, { "name": "hist_count_bounds", "content": "A list of the histogram counts for the current statistics area in order of ascending\nlatency value including bin boundaries: each count is prefixed by the lower bound of\nthe corresponding histogram bin.\n" }, { "name": "hist_count_ranges", "content": "A list of the histogram counts for the current statistics area in order of ascending\nlatency value including bin boundaries: each count is prefixed by both the lower and\nupper bounds of the corresponding histogram bin.\n" }, { "name": "hist_percent", "content": "A list of the relative histogram values for the current statistics area in order of\nascending latency value, expressed as a percentage. Each value represents the propor‐\ntion of I/Os with latency times falling into that bin's time range during the sample\nperiod.\n" }, { "name": "hist_percent_bounds", "content": "A list of the relative histogram values for the current statistics area in order of\nascending latency value, expressed as a percentage and including bin boundaries. Each\nvalue represents the proportion of I/Os with latency times falling into that bin's\ntime range during the sample period and is prefixed with the corresponding bin's lower\nbound.\n" }, { "name": "hist_percent_ranges", "content": "A list of the relative histogram values for the current statistics area in order of\nascending latency value, expressed as a percentage and including bin boundaries. Each\nvalue represents the proportion of I/Os with latency times falling into that bin's\ntime range during the sample period and is prefixed with the corresponding bin's lower\nand upper bounds.\n" }, { "name": "hist_bounds", "content": "A list of the histogram boundary values for the current statistics area in order of\nascending latency value. The values are expressed in whole units of seconds, milisec‐\nonds, microseconds or nanoseconds with a suffix indicating the unit.\n" }, { "name": "hist_ranges", "content": "A list of the histogram bin ranges for the current statistics area in order of ascend‐\ning latency value. The values are expressed as \"LOWER-UPPER\" in whole units of sec‐\nonds, miliseconds, microseconds or nanoseconds with a suffix indicating the unit.\n" }, { "name": "hist_bins", "content": "The number of latency histogram bins configured for the area.\n" } ] }, "EXAMPLES": { "content": "Create a whole-device region with one area on vg00/lvol1\n# dmstats create vg00/lvol1\nvg00/lvol1: Created new region with 1 area(s) as region ID 0\n\nCreate a 32M region 1G into device d0\n# dmstats create --start 1G --length 32M d0\nd0: Created new region with 1 area(s) as region ID 0\n\nCreate a whole-device region with 8 areas on every device\n# dmstats create --areas 8\nvg00-lvol1: Created new region with 8 area(s) as region ID 0\nvg00-lvol2: Created new region with 8 area(s) as region ID 0\nvg00-lvol3: Created new region with 8 area(s) as region ID 0\nvg01-lvol0: Created new region with 8 area(s) as region ID 2\nvg01-lvol1: Created new region with 8 area(s) as region ID 0\nvg00-lvol2: Created new region with 8 area(s) as region ID 1\n\nDelete all regions on all devices\n# dmstats delete --alldevices --allregions\n\nCreate a whole-device region with areas 10GiB in size on vg00/lvol1 using dmsetup\n# dmsetup stats create --areasize 10G vg00/lvol1\nvg00-lvol1: Created new region with 5 area(s) as region ID 1\n\nCreate a 1GiB region with 16 areas at the start of vg00/lvol1\n# dmstats create --start 0 --len 1G --areas=16 vg00/lvol1\nvg00-lvol1: Created new region with 16 area(s) as region ID 0\n\nList the statistics regions registered on vg00/lvol1\n# dmstats list vg00/lvol1\nName RgID RStart RSize #Areas ASize ProgID\nvg00-lvol1 0 0 61.00g 1 61.00g dmstats\nvg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats\nvg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats\n\nDisplay five statistics reports for vg00/lvol1 at an interval of one second\n# dmstats report --interval 1 --count 5 vg00/lvol1\n# dmstats report\nName RgID ArID AStart ASize RRqM/s WRqM/s R/s W/s RSz/s WSz/s\nAvRqSz QSize Util% AWait RdAWa WrAWa\nvghex-lvhome 0 0 0 61.00g 0.00 0.00 0.00 218.00 0 1.04m\n4.50k 2.97 81.70 13.62 0.00 13.62\nvghex-lvhome 1 0 61.00g 19.20g 0.00 0.00 0.00 5.00 0 548.00k\n109.50k 0.14 11.00 27.40 0.00 27.40\nvghex-lvhome 2 0 80.20g 2.14g 0.00 0.00 0.00 14.00 0 1.15m\n84.00k 0.39 18.70 27.71 0.00 27.71\n\nCreate one region for reach target contained in device vg00/lvol1\n# dmstats create --segments vg00/lvol1\nvg00-lvol1: Created new region with 1 area(s) as region ID 0\nvg00-lvol1: Created new region with 1 area(s) as region ID 1\nvg00-lvol1: Created new region with 1 area(s) as region ID 2\n\nCreate regions mapping each file in the directory images/ and place them into separate\ngroups, each named after the corresponding file\n# dmstats create --filemap images/*\nimages/vm1.qcow2: Created new group with 87 region(s) as group ID 0.\nimages/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87.\nimages/vm2.qcow2: Created new group with 11 region(s) as group ID 95.\nimages/vm2-1.qcow2: Created new group with 1454 region(s) as group ID 106.\nimages/vm3.img: Created new group with 2 region(s) as group ID 1560.\n\nPrint raw counters for region 4 on device d0\n# dmstats print --regionid 4 d0\n2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41\n", "subsections": [] }, "AUTHORS": { "content": "Bryn M. Reeves \n", "subsections": [] }, "SEE ALSO": { "content": "dmsetup(8)\n\nLVM2 resource page: \u001b]8;;https://www.sourceware.org/lvm2\u001b\\https://www.sourceware.org/lvm2\u001b]8;;\u001b\\\nDevice-mapper resource page: \u001b]8;;http://sources.redhat.com/dm\u001b\\http://sources.redhat.com/dm\u001b]8;;\u001b\\\n\nDevice-mapper statistics kernel documentation\nDocumentation/device-mapper/statistics.txt\n\nLinux Jun 23 2016 DMSTATS(8)", "subsections": [] } }, "summary": "dmstats — device-mapper statistics management", "flags": [ { "flag": "", "long": "--alldevices", "arg": null, "description": "If no device arguments are given allow operation on all devices when creating or deleting regions." }, { "flag": "", "long": "--allprograms", "arg": null, "description": "Include regions from all program IDs for list and report operations." }, { "flag": "", "long": "--allregions", "arg": null, "description": "Include all present regions for commands that normally accept a single region identi‐ fier. --area When peforming a list or report, include objects of type area in the results. --areas nrareas Specify the number of statistics areas to create within a new region. --areasize areasize[ 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. Capi‐ talise to use multiples of 1000 (S.I.) instead of 1024." }, { "flag": "", "long": "--clear", "arg": null, "description": "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 re‐ ports will continue to repeat until interrupted." }, { "flag": "", "long": "--group", "arg": null, "description": "When peforming a list or report, include objects of type group in the results." }, { "flag": "", "long": "--filemap", "arg": null, "description": "Instead of creating regions on a device as specified by command line options, open the file found at each filepath argument, and create regions corresponding to the loca‐ tions of the on-disk extents allocated to the file(s)." }, { "flag": "", "long": "--nomonitor", "arg": null, "description": "Disable the dmfilemapd daemon when creating new file mapped groups. Normally the de‐ vice-mapper filemap monitoring daemon, dmfilemapd, 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 updatefilemap command, or by starting the daemon manually. --follow followmode Specify the dmfilemapd 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 which cause the daemon to terminate. The followmode argument is either \"inode\", for follow-inode mode, or \"path\", for fol‐ low-path. If follow-inode mode is used, the daemon will hold the file open, and continue to up‐ date 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 un‐ linked and it 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." }, { "flag": "", "long": "--foreground", "arg": null, "description": "Specify that the dmfilemapd 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. --bounds histogramboundaries [ns|us|ms|s] Specify the boundaries of a latency histogram to be tracked for the re‐ gion as a comma separated list of latency values. Latency values are given in nanosec‐ onds. An optional unit suffix of ns,us,ms, or s may be given after each value to spec‐ ify units of nanoseconds, microseconds, miliseconds or seconds respectively." }, { "flag": "", "long": "--histogram", "arg": null, "description": "When used with the report and list commands select default fields that emphasize la‐ tency 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 sec‐ tors. An optional suffix selects units of: (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead of 1024." }, { "flag": "-j", "long": "--major", "arg": null, "description": "Specify the major number." }, { "flag": "-m", "long": "--minor", "arg": null, "description": "Specify the minor number." }, { "flag": "", "long": "--nogroup", "arg": null, "description": "When creating regions mapping the extents of a file in the file system, do not create a group or set an alias." }, { "flag": "", "long": "--nosuffix", "arg": null, "description": "Suppress the suffix on output sizes. Use with --units (except h and H) if processing the output." }, { "flag": "", "long": "--notimesuffix", "arg": null, "description": "Suppress the suffix on output time values. Histogram boundary values will be reported in units of nanoseconds." }, { "flag": "-o", "long": "--options", "arg": null, "description": "Specify which report fields to display." }, { "flag": "-O", "long": "--sort", "arg": null, "description": "Sort output according to the list of fields given. Precede any sort field with '-' for a reverse sort on that column." }, { "flag": "", "long": "--precise", "arg": null, "description": "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 se‐ lect only regions with a matching value. The default program ID for dmstats-managed regions is \"dmstats\"." }, { "flag": "", "long": "--region", "arg": null, "description": "When peforming a list or report, include objects of type region in the results. --regionid id Specify the region to operate on. --regions regionlist 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 separat‐ ed range, for example: '1-10'." }, { "flag": "", "long": "--relative", "arg": null, "description": "If displaying the histogram report show relative (percentage) values instead of ab‐ solute counts." }, { "flag": "-S", "long": "--select", "arg": null, "description": "Display only rows that match selection criteria. All rows with the additional \"select‐ ed\" 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. --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. Capitalise to use multiples of 1000 (S.I.) instead of 1024." }, { "flag": "", "long": "--segments", "arg": null, "description": "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." }, { "flag": "", "long": "--units", "arg": null, "description": "[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. Capi‐ talise to use multiples of 1000 (S.I.) instead of 1024. Can also specify custom units e.g. --units 3M. --userdata userdata 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 auxdata field provided by the kernel. Whitespace is not permitted." }, { "flag": "-u", "long": "--uuid", "arg": null, "description": "Specify the uuid." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "Produce additional output." } ], "examples": [ "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 32M region 1G 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 --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 10GiB 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 1GiB region with 16 areas at the start of vg00/lvol1", "# dmstats create --start 0 --len 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 W/s RSz/s WSz/s", "AvRqSz QSize Util% AWait RdAWa WrAWa", "vghex-lvhome 0 0 0 61.00g 0.00 0.00 0.00 218.00 0 1.04m", "4.50k 2.97 81.70 13.62 0.00 13.62", "vghex-lvhome 1 0 61.00g 19.20g 0.00 0.00 0.00 5.00 0 548.00k", "109.50k 0.14 11.00 27.40 0.00 27.40", "vghex-lvhome 2 0 80.20g 2.14g 0.00 0.00 0.00 14.00 0 1.15m", "84.00k 0.39 18.70 27.71 0.00 27.71", "Create one region for reach 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" ], "see_also": [ { "name": "dmsetup", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/dmsetup/8/json" } ] }