ZPOOL-EVENTS(8) System Manager's Manual ZPOOL-EVENTS(8) # [NAME](#NAME) `zpool-events` — list recent events generated by kernel # [SYNOPSIS](#SYNOPSIS) `zpool` `events` \[`-vHf`] \[`pool`] `zpool` `events` `-c` # [DESCRIPTION](#DESCRIPTION) Lists all recent events generated by the ZFS kernel modules. These events are consumed by the [zed(8)](/man/os/zfs/zed.8) and used to automate administrative tasks such as replacing a failed device with a hot spare. For more information about the subclasses and event payloads that can be generated see [EVENTS](#EVENTS) and the following sections. # [OPTIONS](#OPTIONS) [`-c`](#c) Clear all previous events. [`-f`](#f) Follow mode. [`-H`](#H) Scripted mode. Do not display headers, and separate fields by a single tab instead of arbitrary space. [`-v`](#v) Print the entire payload for each event. # [EVENTS](#EVENTS) These are the different event subclasses. The full event name would be [**ereport.fs.zfs.**](#ereport.fs.zfs.)[*SUBCLASS*](#SUBCLASS), but only the last part is listed here. [**checksum**](#checksum) Issued when a checksum error has been detected. [**io**](#io) Issued when there is an I/O error in a vdev in the pool. [**data**](#data) Issued when there have been data errors in the pool. [**deadman**](#deadman) Issued when an I/O request is determined to be "hung", this can be caused by lost completion events due to flaky hardware or drivers. See [**zfs\_deadman\_failmode**](#zfs_deadman_failmode) in [zfs(4)](/man/os/zfs/zfs.4) for additional information regarding "hung" I/O detection and configuration. [**delay**](#delay) Issued when a completed I/O request exceeds the maximum allowed time specified by the [**zio\_slow\_io\_ms**](#zio_slow_io_ms) module parameter. This can be an indicator of problems with the underlying storage device. The number of delay events is ratelimited by the [**zfs\_slow\_io\_events\_per\_second**](#zfs_slow_io_events_per_second) module parameter. [**dio\_verify\_rd**](#dio_verify_rd) Issued when there was a checksum verify error after a Direct I/O read has been issued. [**dio\_verify\_wr**](#dio_verify_wr) Issued when there was a checksum verify error after a Direct I/O write has been issued. This event can only take place if the module parameter **zfs\_vdev\_direct\_write\_verify** is not set to zero. See [zfs(4)](/man/os/zfs/zfs.4) for more details on the **zfs\_vdev\_direct\_write\_verify** module parameter. [**config\_sync**](#config_sync) Issued every time a vdev change have been done to the pool. [**zpool**](#zpool) Issued when a pool cannot be imported. [**pool\_create**](#pool_create) Issued when a pool is created. [**pool\_destroy**](#pool_destroy) Issued when a pool is destroyed. [**pool\_export**](#pool_export) Issued when a pool is exported. [**pool\_import**](#pool_import) Issued when a pool is imported. [**pool\_reguid**](#pool_reguid) Issued when a REGUID (new unique identifier for the pool have been regenerated) have been detected. [**vdev.unknown**](#vdev.unknown) Issued when the vdev is unknown. Such as trying to clear device errors on a vdev that have failed/been kicked from the system/pool and is no longer available. [**vdev.open\_failed**](#vdev.open_failed) Issued when a vdev could not be opened (because it didn't exist for example). [**vdev.corrupt\_data**](#vdev.corrupt_data) Issued when corrupt data have been detected on a vdev. [**vdev.no\_replicas**](#vdev.no_replicas) Issued when there are no more replicas to sustain the pool. This would lead to the pool being [*DEGRADED*](#DEGRADED). [**vdev.bad\_guid\_sum**](#vdev.bad_guid_sum) Issued when a missing device in the pool have been detected. [**vdev.too\_small**](#vdev.too_small) Issued when the system (kernel) have removed a device, and ZFS notices that the device isn't there any more. This is usually followed by a **probe\_failure** event. [**vdev.bad\_label**](#vdev.bad_label) Issued when the label is OK but invalid. [**vdev.bad\_ashift**](#vdev.bad_ashift) Issued when the ashift alignment requirement has increased. [**vdev\_remove**](#vdev_remove) Issued when a vdev is detached from a mirror (or a spare detached from a vdev where it have been used to replace a failed drive - only works if the original drive have been re-added). [**vdev\_remove\_aux**](#vdev_remove_aux) Issued when an auxiliary vdev is removed. [**vdev\_remove\_dev**](#vdev_remove_dev) Issued when a specific device is removed from a vdev. [**vdev\_clear**](#vdev_clear) Issued when clearing device errors in a pool. Such as running `zpool` `clear` on a device in the pool. [**vdev\_check**](#vdev_check) Issued when a check to see if a given vdev could be opened is started. [**vdev\_spare**](#vdev_spare) Issued when a spare have kicked in to replace a failed device. [**vdev\_autoexpand**](#vdev_autoexpand) Issued when a vdev can be automatically expanded. [**vdev\_add**](#vdev_add) Issued when a vdev is added to a pool. [**vdev\_attach**](#vdev_attach) Issued when a vdev is attached to a mirror or raidz vdev type. [**vdev\_online**](#vdev_online) Issued when an offline vdev is brought online [**io\_failure**](#io_failure) Issued when there is an I/O failure in a vdev in the pool. [**probe\_failure**](#probe_failure) Issued when a probe fails on a vdev. This would occur if a vdev have been kicked from the system outside of ZFS (such as the kernel have removed the device). [**log\_replay**](#log_replay) Issued when the intent log cannot be replayed. The can occur in the case of a missing or damaged log device. [**resilver\_start**](#resilver_start) Issued when a resilver is started. [**resilver\_finish**](#resilver_finish) Issued when the running resilver have finished. [**scrub\_start**](#scrub_start) Issued when a scrub is started on a pool. [**scrub\_finish**](#scrub_finish) Issued when a pool has finished scrubbing. [**scrub\_abort**](#scrub_abort) Issued when a scrub is aborted on a pool. [**scrub\_resume**](#scrub_resume) Issued when a scrub is resumed on a pool. [**scrub\_paused**](#scrub_paused) Issued when a scrub is paused on a pool. [**errorscrub\_start**](#errorscrub_start) Issued when a errorscrub is started on a pool. [**errorscrub\_finish**](#errorscrub_finish) Issued when a pool has finished errorscrubbing. [**errorscrub\_abort**](#errorscrub_abort) Issued when a errorscrub is aborted on a pool. [**errorscrub\_resume**](#errorscrub_resume) Issued when a errorscrub is resumed on a pool. [**errorscrub\_paused**](#errorscrub_paused) Issued when a errorscrub is paused on a pool. [**trim\_start**](#trim_start) Issued when a trim is started on a pool. [**trim\_finish**](#trim_finish) Issued when a pool has finished trimbing. [**trim\_cancel**](#trim_cancel) Issued when a trim is canceled on a pool. [**trim\_resume**](#trim_resume) Issued when a trim is resumed on a pool. [**trim\_suspend**](#trim_suspend) Issued when a trim is suspend on a pool. [**authentication**](#authentication) Issued when there is a decryption / authentication error. [**config\_cache\_write**](#config_cache_write) Issued when the config cache file cannot be written. [**bootfs\_vdev\_attach**](#bootfs_vdev_attach) Issued when a vdev is attached to a root pool with the bootfs property set. [**sitout**](#sitout) Issued when a [**RAIDZ**](#RAIDZ) or [**DRAID**](#DRAID) vdev triggers the [**autosit**](#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. # [PAYLOADS](#PAYLOADS) This is the payload (data, information) that accompanies an event. For [zed(8)](/man/os/zfs/zed.8), these are set to uppercase and prefixed with [**ZEVENT\_**](#ZEVENT_). [**pool**](#pool) Pool name. [**pool\_failmode**](#pool_failmode) Failmode - [**wait**](#wait), [**continue**](#continue), or [**panic**](#panic). See the [**failmode**](#failmode) property in [zpoolprops(7)](/man/os/zfs/zpoolprops.7) for more information. [**pool\_guid**](#pool_guid) The GUID of the pool. [**pool\_context**](#pool_context) The load state for the pool (0=none, 1=open, 2=import, 3=tryimport, 4=recover 5=error). [**vdev\_guid**](#vdev_guid) The GUID of the vdev in question (the vdev failing or operated upon with `zpool` `clear`, etc.). [**vdev\_type**](#vdev_type) Type of vdev - [**disk**](#disk), [**file**](#file), [**mirror**](#mirror), etc. See the [**Virtual Devices**](#Virtual) section of [zpoolconcepts(7)](/man/os/zfs/zpoolconcepts.7) for more information on possible values. [**vdev\_path**](#vdev_path) Full path of the vdev, including any *-partX*. [**vdev\_devid**](#vdev_devid) ID of vdev (if any). [**vdev\_fru**](#vdev_fru) Physical FRU location. [**vdev\_state**](#vdev_state) State of vdev (0=uninitialized, 1=closed, 2=offline, 3=removed, 4=failed to open, 5=faulted, 6=degraded, 7=healthy). [**vdev\_ashift**](#vdev_ashift) The ashift value of the vdev. [**vdev\_complete\_ts**](#vdev_complete_ts) The time the last I/O request completed for the specified vdev. [**vdev\_delta\_ts**](#vdev_delta_ts) The time since the last I/O request completed for the specified vdev. [**vdev\_spare\_paths**](#vdev_spare_paths) List of spares, including full path and any *-partX*. [**vdev\_spare\_guids**](#vdev_spare_guids) GUID(s) of spares. [**vdev\_read\_errors**](#vdev_read_errors) How many read errors that have been detected on the vdev. [**vdev\_write\_errors**](#vdev_write_errors) How many write errors that have been detected on the vdev. [**vdev\_cksum\_errors**](#vdev_cksum_errors) How many checksum errors that have been detected on the vdev. [**parent\_guid**](#parent_guid) GUID of the vdev parent. [**parent\_type**](#parent_type) Type of parent. See **vdev\_type**. [**parent\_path**](#parent_path) Path of the vdev parent (if any). [**parent\_devid**](#parent_devid) ID of the vdev parent (if any). [**zio\_objset**](#zio_objset) The object set number for a given I/O request. [**zio\_object**](#zio_object) The object number for a given I/O request. [**zio\_level**](#zio_level) The indirect level for the block. Level 0 is the lowest level and includes data blocks. Values > 0 indicate metadata blocks at the appropriate level. [**zio\_blkid**](#zio_blkid) The block ID for a given I/O request. [**zio\_err**](#zio_err) The error number for a failure when handling a given I/O request, compatible with [errno(3)](/man/os/zfs/errno.3) with the value of [**EBADE**](#EBADE) used to indicate a ZFS checksum error. [**zio\_offset**](#zio_offset) The offset in bytes of where to write the I/O request for the specified vdev. [**zio\_size**](#zio_size) The size in bytes of the I/O request. [**zio\_flags**](#zio_flags) The current flags describing how the I/O request should be handled. See the **I/O FLAGS** section for the full list of I/O flags. [**zio\_stage**](#zio_stage) The current stage of the I/O in the pipeline. See the **I/O STAGES** section for a full list of all the I/O stages. [**zio\_pipeline**](#zio_pipeline) The valid pipeline stages for the I/O. See the **I/O STAGES** section for a full list of all the I/O stages. [**zio\_priority**](#zio_priority) The queue priority of the I/O request. See the **I/O PRIORITIES** section for a full list of all the I/O priorities. [**zio\_tyoe**](#zio_tyoe) The type of the I/O request. See the **I/O TYPES** section for a full list of all the I/O types. [**zio\_delay**](#zio_delay) The time elapsed (in nanoseconds) waiting for the block layer to complete the I/O request. Unlike **zio\_delta**, this does not include any vdev queuing time and is therefore solely a measure of the block layer performance. [**zio\_timestamp**](#zio_timestamp) The time when a given I/O request was submitted. [**zio\_delta**](#zio_delta) The time required to service a given I/O request. [**prev\_state**](#prev_state) The previous state of the vdev. [**cksum\_algorithm**](#cksum_algorithm) Checksum algorithm used. See [zfsprops(7)](/man/os/zfs/zfsprops.7) for more information on the available checksum algorithms. [**cksum\_byteswap**](#cksum_byteswap) Whether or not the data is byteswapped. [**bad\_ranges**](#bad_ranges) [\[](#_)`start`, `end`) pairs of corruption offsets. Offsets are always aligned on a 64-bit boundary, and can include some gaps of non-corruption. (See **bad\_ranges\_min\_gap**) [**bad\_ranges\_min\_gap**](#bad_ranges_min_gap) In order to bound the size of the **bad\_ranges** array, gaps of non-corruption less than or equal to **bad\_ranges\_min\_gap** bytes have been merged with adjacent corruption. Always at least 8 bytes, since corruption is detected on a 64-bit word basis. [**bad\_range\_sets**](#bad_range_sets) This array has one element per range in **bad\_ranges**. Each element contains the count of bits in that range which were clear in the good data and set in the bad data. [**bad\_range\_clears**](#bad_range_clears) This array has one element per range in **bad\_ranges**. Each element contains the count of bits for that range which were set in the good data and clear in the bad data. [**bad\_set\_bits**](#bad_set_bits) If this field exists, it is an array of (`bad data` & ~(`good data`)); that is, the bits set in the bad data which are cleared in the good data. Each element corresponds a byte whose offset is in a range in **bad\_ranges**, and the array is ordered by offset. Thus, 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**](#bad_cleared_bits) Like **bad\_set\_bits**, but contains (`good data` & ~(`bad data`)); that is, the bits set in the good data which are cleared in the bad data. # [I/O STAGES](#I/O_STAGES) The ZFS I/O pipeline is comprised of various stages which are defined below. The individual stages are used to construct these basic I/O operations: Read, Write, Free, Claim, Flush and Trim. These stages may be set on an event to describe the life cycle of a given I/O request. Stage Bit Mask Operations * * * * * * * * * ZIO\_STAGE\_OPEN 0x00000001 RWFCXT ZIO\_STAGE\_READ\_BP\_INIT 0x00000002 R----- ZIO\_STAGE\_WRITE\_BP\_INIT 0x00000004 -W---- ZIO\_STAGE\_FREE\_BP\_INIT 0x00000008 --F--- ZIO\_STAGE\_ISSUE\_ASYNC 0x00000010 -WF--T ZIO\_STAGE\_WRITE\_COMPRESS 0x00000020 -W---- ZIO\_STAGE\_ENCRYPT 0x00000040 -W---- ZIO\_STAGE\_CHECKSUM\_GENERATE 0x00000080 -W---- ZIO\_STAGE\_NOP\_WRITE 0x00000100 -W---- ZIO\_STAGE\_DDT\_READ\_START 0x00000200 R----- ZIO\_STAGE\_DDT\_READ\_DONE 0x00000400 R----- ZIO\_STAGE\_DDT\_WRITE 0x00000800 -W---- ZIO\_STAGE\_DDT\_FREE 0x00001000 --F--- ZIO\_STAGE\_BRT\_FREE 0x00002000 --F--- ZIO\_STAGE\_GANG\_ASSEMBLE 0x00004000 RWFC-- ZIO\_STAGE\_GANG\_ISSUE 0x00008000 RWFC-- ZIO\_STAGE\_DVA\_THROTTLE 0x00010000 -W---- ZIO\_STAGE\_DVA\_ALLOCATE 0x00020000 -W---- ZIO\_STAGE\_DVA\_FREE 0x00040000 --F--- ZIO\_STAGE\_DVA\_CLAIM 0x00080000 ---C-- ZIO\_STAGE\_READY 0x00100000 RWFCIT ZIO\_STAGE\_VDEV\_IO\_START 0x00200000 RW--XT ZIO\_STAGE\_VDEV\_IO\_DONE 0x00400000 RW--XT ZIO\_STAGE\_VDEV\_IO\_ASSESS 0x00800000 RW--XT ZIO\_STAGE\_CHECKSUM\_VERIFY 0x01000000 R----- ZIO\_STAGE\_DIO\_CHECKSUM\_VERIFY 0x02000000 -W---- ZIO\_STAGE\_DONE 0x04000000 RWFCXT # [I/O FLAGS](#I/O_FLAGS) Every I/O request in the pipeline contains a set of flags which describe its function and are used to govern its behavior. These flags will be set in an event as a **zio\_flags** payload entry. Flag Bit Mask * * * * * * ZIO\_FLAG\_DONT\_AGGREGATE 0x00000001 ZIO\_FLAG\_IO\_REPAIR 0x00000002 ZIO\_FLAG\_SELF\_HEAL 0x00000004 ZIO\_FLAG\_RESILVER 0x00000008 ZIO\_FLAG\_SCRUB 0x00000010 ZIO\_FLAG\_SCAN\_THREAD 0x00000020 ZIO\_FLAG\_PHYSICAL 0x00000040 ZIO\_FLAG\_CANFAIL 0x00000080 ZIO\_FLAG\_SPECULATIVE 0x00000100 ZIO\_FLAG\_CONFIG\_WRITER 0x00000200 ZIO\_FLAG\_DONT\_RETRY 0x00000400 ZIO\_FLAG\_NODATA 0x00001000 ZIO\_FLAG\_INDUCE\_DAMAGE 0x00002000 ZIO\_FLAG\_ALLOC\_THROTTLED 0x00004000 ZIO\_FLAG\_IO\_RETRY 0x00008000 ZIO\_FLAG\_PROBE 0x00010000 ZIO\_FLAG\_TRYHARD 0x00020000 ZIO\_FLAG\_OPTIONAL 0x00040000 ZIO\_FLAG\_DONT\_QUEUE 0x00080000 ZIO\_FLAG\_DONT\_PROPAGATE 0x00100000 ZIO\_FLAG\_IO\_BYPASS 0x00200000 ZIO\_FLAG\_IO\_REWRITE 0x00400000 ZIO\_FLAG\_RAW\_COMPRESS 0x00800000 ZIO\_FLAG\_RAW\_ENCRYPT 0x01000000 ZIO\_FLAG\_GANG\_CHILD 0x02000000 ZIO\_FLAG\_DDT\_CHILD 0x04000000 ZIO\_FLAG\_GODFATHER 0x08000000 ZIO\_FLAG\_NOPWRITE 0x10000000 ZIO\_FLAG\_REEXECUTED 0x20000000 ZIO\_FLAG\_DELEGATED 0x40000000 ZIO\_FLAG\_FASTWRITE 0x80000000 # [I/O TYPES](#I/O_TYPES) Every I/O request in the pipeline has a single type value. This value describes the kind of low-level work the I/O represents. This value will be set in an event as a [**zio\_type**](#zio_type) payload entry. Type Value Description * * * * * * * * * ZIO\_TYPE\_NULL 0x0 internal I/O sync point ZIO\_TYPE\_READ 0x1 data read ZIO\_TYPE\_WRITE 0x2 data write ZIO\_TYPE\_FREE 0x3 block free ZIO\_TYPE\_CLAIM 0x4 block claim (ZIL replay) ZIO\_TYPE\_FLUSH 0x5 disk cache flush request ZIO\_TYPE\_TRIM 0x6 trim (discard) # [I/O PRIORITIES](#I/O_PRIORITIES) Every I/O request in the pipeline has a single priority value. This value is used by the queuing code to decide which I/O to issue next. This value will be set in an event as a **zio\_priority** payload entry. Type Value Description * * * * * * * * * ZIO\_PRIORITY\_SYNC\_READ 0x0 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) # [SEE ALSO](#SEE_ALSO) [zfs(4)](/man/os/zfs/zfs.4), [zed(8)](/man/os/zfs/zed.8), [zpool-wait(8)](/man/os/zfs/zpool-wait.8) July 3, 2025 OpenZFS --- Document: zpool-events(8) from zfs 2.4.4-r3 (Chainguard OS) Source: https://github.com/openzfs/zfs