Btrfs has a sysfs interface to provide extra knobs.

The top level path is /sys/fs/btrfs/, and the main directory layout is the following:

Relative Path

Description

Version

features/

All supported features

3.14

UUID/

Mounted fs UUID

3.14

UUID/allocation/

Space allocation info

3.14

UUID/bdi/

Backing device info (writeback)

5.9

UUID/debug/

Debugging information (optional)

5.6

UUID/devices/NODE/

Symlink to each block device sysfs

5.6

UUID/devinfo/DEVID/

Btrfs specific info for each device

5.6

UUID/discard/

Discard stats and tunables

6.1

UUID/features/

Features of the filesystem

3.14

UUID/qgroups/

Global qgroup info

5.9

UUID/qgroups/LEVEL_ID/

Info for each qgroup

5.9

For /sys/fs/btrfs/features/ directory, each file means a supported feature of the current kernel. Most files have value 0. Otherwise it depends on the file, value 1 typically means the feature can be turned on a mounted filesystem. Some directories may depend on a feature (qgroups) or a build config option (debug and CONFIG_BTRFS_DEBUG).

For /sys/fs/btrfs/UUID/features/ directory, each file means an enabled feature on the mounted filesystem.

The features share the same name in section FILESYSTEM FEATURES.

UUID

Files in /sys/fs/btrfs/UUID/ directory are:

bg_reclaim_threshold

(RW, since: 5.19)

Used space percentage of total device space to start auto block group claim. Mostly for zoned devices.

checksum

(RO, since: 5.5)

The checksum used for the mounted filesystem. This includes both the checksum type (see section CHECKSUM ALGORITHMS) and the selected implementation (depends on kerrnel, it used to be type of harware acceleration):

crc32c (crc32c-lib)
clone_alignment

(RO, since: 3.16)

The bytes alignment for clone and dedupe ioctls.

commit_stats

(RW, since: 6.0)

The performance statistics for btrfs transaction commit since the first mount. For debugging or monitoring purposes.

Writing into this file will reset the maximum commit duration (max_commit_ms) to 0. The file looks like:

commits 70649
last_commit_ms 2
max_commit_ms 131
total_commit_ms 170840

  • commits - number of transaction commits since the first mount

  • last_commit_ms - duration in milliseconds of the last commit

  • max_commit_ms - maximum time a transaction commit took since first mount or last reset

  • total_commit_ms - sum of all transaction commit times

exclusive_operation

(RO, since: 5.10)

Show the running exclusive operation. Check section FILESYSTEM EXCLUSIVE OPERATIONS for details.

generation

(RO, since: 5.11)

Show the generation of the mounted filesystem.

label

(RW, since: 3.14)

Show the current label of the mounted filesystem, followed by a newline (which is otherwise trimmed from the label).

metadata_uuid

(RO, since: 5.0)

Show the metadata UUID of the mounted filesystem. Check metadata_uuid feature for more details.

nodesize

(RO, since: 3.14)

Show the nodesize of the mounted filesystem.

quota_override

(RW, since: 4.13)

Show the current quota override status:

  • 0 no quota override.

  • 1 quota override, writes will ignore the existing limit settings

read_policy

(RW, since: 5.11)

Show the current policy for balancing reads from devices. Currently only pid (balance using the process id (pid) value) is supported. More balancing policies are available in experimental build, namely round-robin.

sectorsize

(RO, since: 3.14)

Show the sectorsize of the mounted filesystem.

temp_fsid

(RO, since 6.7)

Indicate that this filesystem got assigned a temporary FSID at mount time, making possible to mount devices with the same FSID.

UUID/allocations

Files and directories in /sys/fs/btrfs/UUID/allocations directory are:

global_rsv_reserved

(RO, since: 3.14)

The used bytes of the global reservation.

global_rsv_size

(RO, since: 3.14)

The total size of the global reservation.

data/, metadata/ and system/ directories

(RO, since: 5.14)

Space info accounting for the 3 block group types.

UUID/allocations/{data,metadata,system}

Files in /sys/fs/btrfs/UUID/allocations/data,metadata,system directory are:

bg_reclaim_threshold

(RW, since: 5.19)

Reclaimable space percentage of block group’s size (excluding permanently unusable space) to reclaim the block group. Can be used on regular or zoned devices.

bytes_*

(RO)

Values of the corresponding data structures for the given block group type and profile that are used internally and may change rapidly depending on the load.

Complete list: bytes_may_use, bytes_pinned, bytes_readonly, bytes_reserved, bytes_used, bytes_zone_unusable

chunk_size

(RW, since: 6.0)

Show the chunk size. Can be changed for data and metadata (independently) and cannot be set for system block group type. Cannot be set for zoned devices as it depends on the fixed device zone size. Upper bound is 10% of the filesystem size, the value must be multiple of 256MiB and greater than 0.

disk_total

(RO, since: 3.14)

Total number of bytes on devices occupied by this block group type.

disk_used

(RO, since: 3.14)

Portion of disk_total in bytes which is used by this block group type.

dynamic_reclaim

(RW, since: 6.11)

Enable or disable dynamic block group reclaim. Use a calculated threshold instead of fixed valude in bg_reclaim_threshold.

flags

(RO, since: 6.11)

Raw decimal value of block group flags.

force_chunk_alloc

(RW, since: 6.0, CONFIG_BTRFS_DEBUG)

(Privileged write.) Force allocation of a new chunk of this block group type. Note his can cause ENOSPC, users should know what they’re doing.

periodic_reclaim

(RW, since: 6.11)

Enable or disable periodic block group reclaim based on bg_reclaim_threshold.

reclaim_bytes

(RO, since: 6.11)

Monotonically increasing counter of reclaimed bytes.

reclaim_count

(RO, since: 6.11)

Monotonically increasing counter of block group reclaim attempts.

reclaim_errors

(RO, since: 6.11)

Monotonically increasing counter of reclaim errors.

size_classes

(RO, since: 6.3)

Numbers of block groups of a given class based on heuristics that measure extent length, age and fragmentation.

none 136
small 374
medium 282
large 93
total_bytes

(RO, since: 3.14)

Total bytes.

UUID/bdi

Symlink to the sysfs directory of the backing device info (BDI), which is related to writeback process and infrastructure.

UUID/devices

Files in /sys/fs/btrfs/UUID/devices directory are symlinks named after device nodes (e.g. sda, dm-0) and pointing to their sysfs directory.

UUID/devinfo

The directory contains subdirectories named after device ids (numeric values). Each subdirectory has information about the device of the given devid.

UUID/devinfo/DEVID

Files in /sys/fs/btrfs/UUID/devinfo/DEVID directory are:

error_stats

(RO, since: 5.14)

Show device stats of this device, same as btrfs device stats (btrfs-device(8)).

write_errs 0
read_errs 0
flush_errs 0
corruption_errs 0
generation_errs 0
fsid

(RO, since: 5.17)

Show the fsid which the device belongs to. It can be different than the UUID if it’s a seed device.

in_fs_metadata

(RO, since: 5.6)

Show whether we have found the device. Should always be 1, as if this turns to 0, the DEVID directory would get removed automatically.

missing

(RO, since: 5.6)

Show whether the device is considered missing by the kernel module.

replace_target

(RO, since: 5.6)

Show whether the device is the replace target. If no device replace is running, this value is 0.

scrub_speed_max

(RW, since: 5.14)

Show the scrub speed limit for this device. The unit is Bytes/s. 0 means no limit. The value can be set but is not persistent and not preserved beyond mount.

writeable

(RO, since: 5.6)

Show if the device is writeable.

UUID/qgroups

Files in /sys/fs/btrfs/UUID/qgroups/ directory are:

drop_subtree_threshold

(RW, since: 6.1)

Show the subtree drop threshold to automatically mark qgroup inconsistent.

When dropping large subvolumes with qgroup enabled, there would be a huge load for qgroup accounting. If we have a subtree whose level is larger than or equal to this value, we will not trigger qgroup account at all, but mark qgroup inconsistent to avoid the huge workload.

Default value is 3, which means that trees of low height will be accounted properly as this is sufficiently fast. The value was 8 until 6.13 where no subtree drop can trigger qgroup rescan making it less useful.

Lower value can reduce qgroup workload, at the cost of extra qgroup rescan to re-calculate the numbers.

enabled

(RO, since: 6.1)

Show if qgroup is enabled. Also, if qgroup is disabled, the qgroups directory will be removed automatically.

inconsistent

(RO, since: 6.1)

Show if the qgroup numbers are inconsistent. If 1, it’s recommended to do a qgroup rescan.

mode

(RO, since: 6.7)

Show which quota mode is enabled, can be qgroup for full accounting or squota for simplified accounting.

UUID/qgroups/LEVEL_ID

Files in each /sys/fs/btrfs/UUID/qgroups/LEVEL_ID/ directory are:

exclusive

(RO, since: 5.9)

Show the exclusively owned bytes of the qgroup.

limit_flags

(RO, since: 5.9)

Show the numeric value of the limit flags. If 0, means no limit implied.

max_exclusive

(RO, since: 5.9)

Show the limits on exclusively owned bytes.

max_referenced

(RO, since: 5.9)

Show the limits on referenced bytes.

referenced

(RO, since: 5.9)

Show the referenced bytes of the qgroup.

rsv_data

(RO, since: 5.9)

Show the reserved bytes for data.

rsv_meta_pertrans

(RO, since: 5.9)

Show the reserved bytes for per transaction metadata.

rsv_meta_prealloc

(RO, since: 5.9)

Show the reserved bytes for preallocated metadata.

UUID/discard

Files in /sys/fs/btrfs/UUID/discard/ directory are:

discardable_bytes

(RO, since: 6.1)

Show amount of bytes that can be discarded in the async discard and nodiscard mode.

discardable_extents

(RO, since: 6.1)

Show number of extents to be discarded in the async discard and nodiscard mode.

discard_bitmap_bytes

(RO, since: 6.1)

Show amount of discarded bytes from data tracked as bitmaps.

discard_extent_bytes

(RO, since: 6.1)

Show amount of discarded extents from data tracked as bitmaps.

discard_bytes_saved

(RO, since: 6.1)

Show the amount of bytes that were reallocated without being discarded.

kbps_limit

(RW, since: 6.1)

Tunable limit of kilobytes per second issued as discard IO in the async discard mode.

iops_limit

(RW, since: 6.1)

Tunable limit of number of discard IO operations to be issued in the async discard mode.

max_discard_size

(RW, since: 6.1)

Tunable limit for size of one IO discard request.