ZPOOL-EVENTS(8)

💖 ZPOOL-EVENTS 💖

okay bestie, gather round, because this is the manual page for zpool-events — that's the System Manager's Manual entry, section 8, and she is a big one. She's the one who spills the tea on everything the ZFS kernel modules have been up to lately. ✨

---

🌸 NAME 🌸

zpool-events — list recent events generated by kernel

---

✨ SYNOPSIS ✨

zpool events [-vHf] [pool]
zpool events -c

---

🦋 DESCRIPTION 🦋

So basically, zpool events lists all the recent events that the ZFS kernel modules have generated. These events get consumed by zed(8), and zed uses them to automate the boring administrative stuff for you — like swapping a dead device out for a hot spare without you having to lift a finger. 💅

If you want the full rundown on the subclasses and event payloads that can show up, go peek at the “EVENTS” section and everything after it. 👑

---

🎀 OPTIONS 🎀

• -c — Clears out all the previous events. bye bye history 🫶
• -f — Follow mode. She stays watching. 👀
• -H — Scripted mode. No headers, no vibes, just the facts — fields get separated by a single tab instead of whatever arbitrary spacing it felt like using. ✨
• -v — Prints the entire payload</> for each event. the whole thing. all of it. no crumbs left behind. 💖

---

🔥 EVENTS 🔥

These are the different event subclasses, bestie. The full event name would be ereport.fs.zfs.SUBCLASS, but we're only listing the last part here because the rest is just... a lot. iykyk.

• checksum — Fired off when a checksum error has been detected. 🩹
• io — Fired off when there's an I/O error in a vdev in the pool.
• data — Fired off when there have been data errors in the pool. 😭
• deadman — Fired off when an I/O request gets determined to be "hung". This can happen because of lost completion events caused by flaky hardware or flaky drivers. Peep zfs_deadman_failmode in zfs(4) for the full scoop on "hung" I/O detection and how it's configured.
• delay — Fired off when a completed I/O request takes longer than the max allowed time, which is specified by the zio_slow_io_ms module parameter. This is often giving "something is wrong with the underlying storage device". 👀 The number of delay events is ratelimited by the zfs_slow_io_events_per_second module parameter.
• dio_verify_rd — Fired off when there was a checksum verify error after a Direct I/O read has been issued.
• dio_verify_wr — Fired off when there was a checksum verify error after a Direct I/O write has been issued. This one can only happen if the module parameter zfs_vdev_direct_write_verify is not set to zero. See zfs(4) for more deets on the zfs_vdev_direct_write_verify module parameter.
• config_sync — Fired off every single time a vdev change has been done to the pool.
• zpool — Fired off when a pool cannot be imported. 💀
• pool_create — Fired off when a pool is created. 👶✨
• pool_destroy — Fired off when a pool is destroyed. 💀
• pool_export — Fired off when a pool is exported.
• pool_import — Fired off when a pool is imported.
• pool_reguid — Fired off when a REGUID has been detected — that's when a new unique identifier for the pool has been regenerated. 🆔
• vdev.unknown — Fired off when the vdev is unknown. Like, say, when you're trying to clear device errors on a vdev that has failed or been kicked from the system/pool and is no longer available. shruggie.
• vdev.open_failed — Fired off when a vdev could not be opened — because it didn't exist, for example. 🙈
• vdev.corrupt_data — Fired off when corrupt data has been detected on a vdev.
• vdev.no_replicas — Fired off when there are no more replicas left to sustain the pool. This would lead to the pool being DEGRADED. not the vibe. 😭
• vdev.bad_guid_sum — Fired off when a missing device in the pool has been detected.
• vdev.too_small — Fired off when the system (kernel) has removed a device and ZFS notices the device isn't there anymore. This is usually followed by a probe_failure event, so watch for the sequel.
• vdev.bad_label — Fired off when the label is OK but invalid. 🤨
• vdev.bad_ashift — Fired off when the ashift alignment requirement has increased.
• vdev_remove — Fired off when a vdev is detached from a mirror — or when a spare is detached from a vdev where it has been used to replace a failed drive. And heads up: this only works if the original drive has been re-added. 👑
• vdev_remove_aux — Fired off when an auxiliary vdev is removed.
• vdev_remove_dev — Fired off when a specific device is removed from a vdev.
• vdev_clear — Fired off when clearing device errors in a pool. Like when you run zpool clear on a device in the pool. 🧹✨
• vdev_check — Fired off when a check to see if a given vdev could be opened is started.
• vdev_spare — Fired off when a spare has kicked in to replace a failed device. slay, spare. 🦸
• vdev_autoexpand — Fired off when a vdev can be automatically expanded.
• vdev_add — Fired off when a vdev is added to a pool.
• vdev_attach — Fired off when a vdev is attached to a mirror or raidz vdev type.
• vdev_online — Fired off when an offline vdev is brought online. welcome back babe 🫶
• io_failure — Fired off when there is an I/O failure in a vdev in the pool.
• probe_failure — Fired off when a probe fails on a vdev. This would occur if a vdev has been kicked from the system outside of ZFS — like when the kernel has removed the device. 🙈
• log_replay — Fired off when the intent log cannot be replayed. This can occur in the case of a missing or damaged log device. 💀
• resilver_start — Fired off when a resilver is started.
• resilver_finish — Fired off when the running resilver has finished. 🎉
• scrub_start — Fired off when a scrub is started on a pool.
• scrub_finish — Fired off when a pool has finished scrubbing. ✨
• scrub_abort — Fired off when a scrub is aborted on a pool.
• scrub_resume — Fired off when a scrub is resumed on a pool.
• scrub_paused — Fired off when a scrub is paused on a pool.
• errorscrub_start — Fired off when an errorscrub is started on a pool.
• errorscrub_finish — Fired off when a pool has finished errorscrubbing. ✨
• errorscrub_abort — Fired off when an errorscrub is aborted on a pool.
• errorscrub_resume — Fired off when an errorscrub is resumed on a pool.
• errorscrub_paused — Fired off when an errorscrub is paused on a pool.
• trim_start — Fired off when a trim is started on a pool.
• trim_finish — Fired off when a pool has finished trimbing. (yes it says trimbing. we don't make the rules, we just report them. 😭)
• trim_cancel — Fired off when a trim is canceled on a pool.
• trim_resume — Fired off when a trim is resumed on a pool.
• trim_suspend — Fired off when a trim is suspend on a pool.
• authentication — Fired off when there is a decryption / authentication error. 🔐
• config_cache_write — Fired off when the config cache file cannot be written.
• bootfs_vdev_attach — Fired off when a vdev is attached to a root pool with the bootfs property set. 👟
• sitout — Fired off when a RAIDZ or DRAID vdev triggers the autosit logic. This logic detects when a disk in such a vdev is significantly slower than its peers, and sits them out temporarily to preserve the performance of the pool. time out, bestie, think about what you did. 🪑

💾 PAYLOADS 💾

Okay bestie, so when an event pops off, it comes with a payload — that's just the data/information riding along with it. Think of it as the event's little purse full of receipts. 👜✨

Heads up: for zed(8), all of these get uppercased and prefixed with ZEVENT_. So pool shows up as ZEVENT_POOL. iykyk 💅

• pool — the pool's name, obviously. 💖
• pool_failmode — the failmode, which is one of wait, continue, or panic. Go peep the failmode property in zpoolprops(7) if you want the full tea.
• pool_guid — the GUID of the pool. 🔑
• pool_context — the pool's load state: 0=none, 1=open, 2=import, 3=tryimport, 4=recover, 5=error.
• vdev_guid — the GUID of the vdev in question (aka the vdev that's failing, or the one being operated on with zpool clear, etc.).
• vdev_type — what kind of vdev it is: disk, file, mirror, etc. The Virtual Devices section of zpoolconcepts(7) has all the possible values if you wanna go deeper. 🦋
• vdev_path — the full path of the vdev, -partX and all.
• vdev_devid — the vdev's ID, if it's got one.
• vdev_fru — the physical FRU location.
• vdev_state — the vdev's state: 0=uninitialized, 1=closed, 2=offline, 3=removed, 4=failed to open, 5=faulted, 6=degraded, 7=healthy.
• vdev_ashift — the vdev's ashift value.
• vdev_complete_ts — the time the last I/O request finished for that vdev.
• vdev_delta_ts — how much time has passed since the last I/O request finished for that vdev.
• vdev_spare_paths — a list of spares, full path plus any -partX included.
• vdev_spare_guids — the GUID(s) of the spares.
• vdev_read_errors — how many read errors got detected on the vdev. 😭
• vdev_write_errors — how many write errors got detected on the vdev.
• vdev_cksum_errors — how many checksum errors got detected on the vdev.
• parent_guid — GUID of the vdev's parent.
• parent_type — type of the parent. Same deal as vdev_type.
• parent_path — path of the vdev's parent, if there is one.
• parent_devid — ID of the vdev's parent, if there is one.
• zio_objset — the object set number for a given I/O request.
• zio_object — the object number for a given I/O request.
• zio_level — the indirect level for the block. Level 0 is the lowest level and it's where the data blocks live. Values > 0 mean metadata blocks at the matching level.
• zio_blkid — the block ID for a given I/O request.
• zio_err — the error number for a failure while handling a given I/O request. It plays nice with errno(3), and the value EBADE gets used to signal a ZFS checksum error. 💀
• zio_offset — the offset in bytes of where the I/O request should be written for the specified vdev.
• zio_size — the size in bytes of the I/O request.
• zio_flags — the current flags describing how the I/O request should be handled. The I/O FLAGS section below has the whole list, no gatekeeping.
• zio_stage — the current stage of the I/O in the pipeline. I/O STAGES section has every single one.
• zio_pipeline — the valid pipeline stages for the I/O. Again, see I/O STAGES.
• zio_priority — the queue priority of the I/O request. See I/O PRIORITIES for the full roster.
• zio_tyoe — the type of the I/O request. See I/O TYPES below for all of them. ✨
• zio_delay — the time elapsed (in nanoseconds) spent waiting for the block layer to complete the I/O request. Unlike zio_delta, this does not include any vdev queuing time, so it's purely a measure of block layer performance. Very demure, very mindful. 🎀
• zio_timestamp — the time when a given I/O request was submitted.
• zio_delta — the time required to service a given I/O request.
• prev_state — the previous state of the vdev.
• cksum_algorithm — which checksum algorithm was used. zfsprops(7) has the details on what's available.
• cksum_byteswap — whether or not the data is byteswapped.
• bad_ranges — [start, end) pairs of corruption offsets. Offsets are always aligned on a 64-bit boundary, and they can include some gaps of non-corruption. (See bad_ranges_min_gap below.)
• bad_ranges_min_gap — to keep the size of the bad_ranges array under control, gaps of non-corruption that are less than or equal to bad_ranges_min_gap bytes have been merged into the adjacent corruption. It's always at least 8 bytes, since corruption is detected on a 64-bit word basis. 🧐
• bad_range_sets — this array has one element per range in bad_ranges. Each element holds the count of bits in that range which were clear in the good data and set in the bad data.
• bad_range_clears — this array has one element per range in bad_ranges. Each element holds the count of bits for that range which were set in the good data and clear in the bad data.
• bad_set_bits — if this field exists, it's an array of (bad data & ~(good data)) — that is, the bits that are set in the bad data and cleared in the good data. Each element corresponds to a byte whose offset falls in a range in bad_ranges, and the array is ordered by offset. So the first element is the first byte in the first bad_ranges range, and the last element is the last byte in the last bad_ranges range.
• bad_cleared_bits — same energy as bad_set_bits, except it holds (good data & ~(bad data)) — the bits set in the good data which are cleared in the bad data.

---

🔧 I/O STAGES 🔧

The ZFS I/O pipeline is made up of a bunch of stages, all defined below. Those individual stages get combined to build these basic I/O operations: Read, Write, Free, Claim, Flush and Trim. And a stage can get set on an event to describe the life cycle of a given I/O request. Main character journey, fr. 👑

• ZIO_STAGE_OPEN — bit mask 0x00000001 — operations: RWFCXT
• ZIO_STAGE_READ_BP_INIT — bit mask 0x00000002 — operations: R-----
• ZIO_STAGE_WRITE_BP_INIT — bit mask 0x00000004 — operations: -W----
• ZIO_STAGE_FREE_BP_INIT — bit mask 0x00000008 — operations: --F---
• ZIO_STAGE_ISSUE_ASYNC — bit mask 0x00000010 — operations: -WF--T
• ZIO_STAGE_WRITE_COMPRESS — bit mask 0x00000020 — operations: -W----
• ZIO_STAGE_ENCRYPT — bit mask 0x00000040 — operations: -W----
• ZIO_STAGE_CHECKSUM_GENERATE — bit mask 0x00000080 — operations: -W----
• ZIO_STAGE_NOP_WRITE — bit mask 0x00000100 — operations: -W----
• ZIO_STAGE_DDT_READ_START — bit mask 0x00000200 — operations: R-----
• ZIO_STAGE_DDT_READ_DONE — bit mask 0x00000400 — operations: R-----
• ZIO_STAGE_DDT_WRITE — bit mask 0x00000800 — operations: -W----
• ZIO_STAGE_DDT_FREE — bit mask 0x00001000 — operations: --F---
• ZIO_STAGE_BRT_FREE — bit mask 0x00002000 — operations: --F---
• ZIO_STAGE_GANG_ASSEMBLE — bit mask 0x00004000 — operations: RWFC--
• ZIO_STAGE_GANG_ISSUE — bit mask 0x00008000 — operations: RWFC--
• ZIO_STAGE_DVA_THROTTLE — bit mask 0x00010000 — operations: -W----
• ZIO_STAGE_DVA_ALLOCATE — bit mask 0x00020000 — operations: -W----
• ZIO_STAGE_DVA_FREE — bit mask 0x00040000 — operations: --F---
• ZIO_STAGE_DVA_CLAIM — bit mask 0x00080000 — operations: ---C--
• ZIO_STAGE_READY — bit mask 0x00100000 — operations: RWFCIT
• ZIO_STAGE_VDEV_IO_START — bit mask 0x00200000 — operations: RW--XT
• ZIO_STAGE_VDEV_IO_DONE — bit mask 0x00400000 — operations: RW--XT
• ZIO_STAGE_VDEV_IO_ASSESS — bit mask 0x00800000 — operations: RW--XT
• ZIO_STAGE_CHECKSUM_VERIFY — bit mask 0x01000000 — operations: R-----
• ZIO_STAGE_DIO_CHECKSUM_VERIFY — bit mask 0x02000000 — operations: -W----
• ZIO_STAGE_DONE — bit mask 0x04000000 — operations: RWFCXT

---

🚩 I/O FLAGS 🚩

Every single I/O request in the pipeline carries a set of flags that describe what it's doing and govern how it behaves. These flags get set in an event as a zio_flags payload entry. 💅

• ZIO_FLAG_DONT_AGGREGATE — bit mask 0x00000001
• ZIO_FLAG_IO_REPAIR — bit mask 0x00000002
• ZIO_FLAG_SELF_HEAL — bit mask 0x00000004
• ZIO_FLAG_RESILVER — bit mask 0x00000008
• ZIO_FLAG_SCRUB — bit mask 0x00000010
• ZIO_FLAG_SCAN_THREAD — bit mask 0x00000020
• ZIO_FLAG_PHYSICAL — bit mask 0x00000040
• ZIO_FLAG_CANFAIL — bit mask 0x00000080
• ZIO_FLAG_SPECULATIVE — bit mask 0x00000100
• ZIO_FLAG_CONFIG_WRITER — bit mask 0x00000200
• ZIO_FLAG_DONT_RETRY — bit mask 0x00000400
• ZIO_FLAG_NODATA — bit mask 0x00001000
• ZIO_FLAG_INDUCE_DAMAGE — bit mask 0x00002000
• ZIO_FLAG_ALLOC_THROTTLED — bit mask 0x00004000
• ZIO_FLAG_IO_RETRY — bit mask 0x00008000
• ZIO_FLAG_PROBE — bit mask 0x00010000
• ZIO_FLAG_TRYHARD — bit mask 0x00020000
• ZIO_FLAG_OPTIONAL — bit mask 0x00040000
• ZIO_FLAG_DONT_QUEUE — bit mask 0x00080000
• ZIO_FLAG_DONT_PROPAGATE — bit mask 0x00100000
• ZIO_FLAG_IO_BYPASS — bit mask 0x00200000
• ZIO_FLAG_IO_REWRITE — bit mask 0x00400000
• ZIO_FLAG_RAW_COMPRESS — bit mask 0x00800000
• ZIO_FLAG_RAW_ENCRYPT — bit mask 0x01000000
• ZIO_FLAG_GANG_CHILD — bit mask 0x02000000
• ZIO_FLAG_DDT_CHILD — bit mask 0x04000000
• ZIO_FLAG_GODFATHER — bit mask 0x08000000
• ZIO_FLAG_NOPWRITE — bit mask 0x10000000
• ZIO_FLAG_REEXECUTED — bit mask 0x20000000
• ZIO_FLAG_DELEGATED — bit mask 0x40000000
• ZIO_FLAG_FASTWRITE — bit mask 0x80000000

---

🎯 I/O TYPES 🎯

Every I/O request in the pipeline has exactly one type value. That value describes the kind of low-level work the I/O represents, and it gets set in an event as a zio_type payload entry. One job, one label, periodt. 🌸

• ZIO_TYPE_NULL — value 0x0 — internal I/O sync point
• ZIO_TYPE_READ — value 0x1 — data read
• ZIO_TYPE_WRITE — value 0x2 — data write
• ZIO_TYPE_FREE — value 0x3 — block free
• ZIO_TYPE_CLAIM — value 0x4 — block claim (ZIL replay)
• ZIO_TYPE_FLUSH — value 0x5 — disk cache flush request
• ZIO_TYPE_TRIM — value 0x6 — trim (discard)

🌈 I/O PRIORITIES 🌈

ok so every single I/O request floatin' around in the pipeline has exactly one priority value, bestie. just the one. and the queuing code uses it to decide which I/O gets to go next — like a lil line at the club and the bouncer's checkin' priorities 💅. this value shows up in an event as the zio_priority payload entry, so you can ~literally~ see it. slay.

• ZIO_PRIORITY_SYNC_READ → 0x0 — no description given, it's just the vibe ✨
• ZIO_PRIORITY_SYNC_WRITE → 0x1 — ZIL
• ZIO_PRIORITY_ASYNC_READ → 0x2 — prefetch
• ZIO_PRIORITY_ASYNC_WRITE → 0x3 — spa_sync()
• ZIO_PRIORITY_SCRUB → 0x4 — asynchronous scrub/resilver reads
• ZIO_PRIORITY_REMOVAL → 0x5 — reads/writes for vdev removal
• ZIO_PRIORITY_INITIALIZING → 0x6 — initializing I/O
• ZIO_PRIORITY_TRIM → 0x7 — trim I/O (discard)
• ZIO_PRIORITY_REBUILD → 0x8 — reads/writes for vdev rebuild
• ZIO_PRIORITY_NOW → 0xa — non-queued i/os (e.g. free)

ngl if you noticed 0x9 isn't in the list… yeah. that's just how it is. no cap, that's the original, we don't make the rules 👑

---

👑 SEE ALSO 👑

go read these next, fr fr — they're the whole friend group:

• zfs(4)
• zed(8)
• zpool-wait(8)

---

ok and that's the whole page, bestie!! 🎀 you made it to the end of part 3, which means you now know everything about zpool events, and honestly? main character energy. go forth and zpool events responsibly 💖

this icon was brought to you by OpenZFS, dated July 3, 2025, and filed under ZPOOL-EVENTS(8) — periodt. 🦋✨