Read XFS Quota Manager Statistics with xqmstats

xqmstats prints the XFS Quota Manager's live dquot counters, and reading it right beats guessing why quota enforcement seems slow. You will check whether the running kernel exposes the interface at all, and record a useful result without changing any quota configuration. The command is a read-only report: it does not enable XFS quotas, alter limits or repair a busy quota manager.

The examples are based on xqmstats from quota package version 4.06-1build6, with the installed manual page as the behaviour reference. Allow about ten minutes. You need a shell, the quota package, and an XFS-capable running kernel. Ordinary users can normally run the report; use elevated privileges only if your local permissions require it.

Checkpoint: If you only need to know whether the command can report on this host, complete steps 1 to 3. Continue to step 4 when you need to preserve or compare the counters.

1. Confirm the installed command

Check the executable and package version before relying on output in a ticket or monitoring note. These are ordinary, read-only commands:

$ command -v xqmstats
/usr/sbin/xqmstats
$ dpkg-query -W -f='${Package} ${Version}\n' quota
quota 4.06-1build6

Your package revision may differ. Keep the version beside any captured result because output and error wording can vary between releases.

The installed synopsis has no operands and no options. Run the command exactly as a report, rather than adding guessed switches:

$ xqmstats

2. Understand what the report measures

When the XFS interface is available, the program queries the kernel's XFS Quota Manager dquot statistics. A dquot is the in-kernel quota record associated with a filesystem object and its accounting identity. The counters describe manager activity, not a user's remaining allowance.

The report contains eight fields:

Field	What to use it for
reclaims	Count of dquot reclaim operations.
missed reclaims	Reclaim attempts that were missed.
dquot dups	Duplicate dquot events reported by the manager.
cache misses	Lookups that did not find the dquot in cache.
cache hits	Lookups satisfied by the cache.
dquot wants	Requests for a dquot from the manager.
shake reclaims	Reclaims caused by cache pressure or a cache shake.
inact reclaims	Reclaims associated with inactive dquots.

These are cumulative kernel counters. A high value is not automatically an incident, and a single sample does not show a rate. Compare two samples taken under similar workload if you need to see activity over time.

3. Handle an unsupported-kernel result

On a host without the required XFS proc interface, the command exits non-zero and reports an error such as:

$ xqmstats
xqmstats: The running kernel does not support XFS
$ printf 'exit status: %s\n' "$?"
exit status: 1

This means the report could not be obtained from the running kernel. It does not mean that changing a quota file or rerunning the command with sudo will create the interface. Check the kernel and filesystem design first:

$ test -r /proc/fs/xfs/xqm && echo 'XFS quota manager interface is readable' || echo 'XFS quota manager interface is unavailable'
$ findmnt -t xfs

An empty findmnt result means there are no mounted XFS filesystems to inspect at that moment. Do not treat this read-only diagnostic as proof that every XFS quota feature is enabled. If XFS is required, investigate the host's kernel, modules, mounts and quota policy through your normal change process. Enabling or changing quotas can affect a live service, so do not experiment on production to make this command return data.

4. Capture a sample safely

Once xqmstats succeeds, save a timestamped sample for comparison. The command writes text to standard output and does not modify the kernel counters:

$ sample="/tmp/xqmstats-$(date +%Y%m%d-%H%M%S).txt"
$ { date --iso-8601=seconds; xqmstats; } | tee "$sample"
2026-09-28T12:00:00+01:00
XFS Quota Manager dquot statistics
  reclaims:        42
  missed reclaims: 0
  dquot dups:       0
  cache misses:     17
  cache hits:       96
  dquot wants:      113
  shake reclaims:   3
  inact reclaims:   39

The values above are illustrative; your counters and spacing will differ. The temporary file is disposable. If you need a durable record, move or copy it into your approved diagnostics store after checking that it contains no sensitive host information.

Take a second sample later and compare the fields, rather than comparing absolute values from unrelated machines:

$ sleep 60
$ xqmstats

A counter that increases during the interval records activity during that interval. A counter that stays unchanged is not evidence that quota enforcement is broken: it may simply mean that no matching manager activity occurred.

5. Avoid common interpretation traps

Do not look for options. The manual documents none. Use the command with no arguments.
Do not confuse manager statistics with quota usage. Use the quota tools and filesystem-specific checks intended for limits and usage; these counters describe internal manager activity.
Do not infer a rate from one sample. Record two samples with an interval and account for workload changes.
Do not hide a failure with redirection. Check the exit status and keep standard error visible when collecting diagnostics.
Do not add sudo by habit. It cannot add XFS support to the running kernel and can make automated diagnostics harder to audit.

Done means

Version recorded. The installed xqmstats path and quota package version are noted.
Exit status checked. You ran the no-option command and confirmed how it exited.
Counters understood. You can distinguish the eight manager counters from user quota usage.
Unsupported kernel diagnosed correctly. A missing XFS interface is treated as a host capability issue, not repaired by guessing.
Samples are comparable. Any comparison uses timestamped samples and leaves quota configuration unchanged.