--- name: "zpool-events" section: "8" platform: "linux" package: "zfsutils-linux" version: "2.3.9-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/zpool-events" --- # zpool-events(8) list recent events generated by kernel ## NAME **zpool-events** – list recent events generated by kernel ## SYNOPSIS **zpool** **events** \[**-vHf**\] \[*pool*\] **zpool** **events** **-c** ## DESCRIPTION Lists all recent events generated by the ZFS kernel modules. These events are consumed by the [zed(8)](/zed/8.md) 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 and the following sections. ## OPTIONS - **-c** Clear all previous events. - **-f** Follow mode. - **-H** Scripted mode. Do not display headers, and separate fields by a single tab instead of arbitrary space. - **-v** Print the entire payload for each event. ## EVENTS These are the different event subclasses. The full event name would be **ereport.fs.zfs.***SUBCLASS*, but only the last part is listed here. - **checksum** Issued when a checksum error has been detected. - **io** Issued when there is an I/O error in a vdev in the pool. - **data** Issued when there have been data errors in the pool. - **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** in [zfs(4)](/zfs/4.md) for additional information regarding "hung" I/O detection and configuration. - **delay** Issued when a completed I/O request exceeds the maximum allowed time specified by the **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** module parameter. - **dio\_verify\_rd** Issued when there was a checksum verify error after a Direct I/O read has been issued. - **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)](/zfs/4.md) for more details on the **zfs\_vdev\_direct\_write\_verify** module parameter. - **config** Issued every time a vdev change have been done to the pool. - **zpool** Issued when a pool cannot be imported. - **zpool.destroy** Issued when a pool is destroyed. - **zpool.export** Issued when a pool is exported. - **zpool.import** Issued when a pool is imported. - **zpool.reguid** Issued when a REGUID (new unique identifier for the pool have been regenerated) have been detected. - **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** Issued when a vdev could not be opened (because it didn't exist for example). - **vdev.corrupt\_data** Issued when corrupt data have been detected on a vdev. - **vdev.no\_replicas** Issued when there are no more replicas to sustain the pool. This would lead to the pool being *DEGRADED*. - **vdev.bad\_guid\_sum** Issued when a missing device in the pool have been detected. - **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** Issued when the label is OK but invalid. - **vdev.bad\_ashift** Issued when the ashift alignment requirement has increased. - **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.clear** Issued when clearing device errors in a pool. Such as running **zpool** **clear** on a device in the pool. - **vdev.check** Issued when a check to see if a given vdev could be opened is started. - **vdev.spare** Issued when a spare have kicked in to replace a failed device. - **vdev.autoexpand** Issued when a vdev can be automatically expanded. - **io\_failure** Issued when there is an I/O failure in a vdev in the pool. - **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** Issued when the intent log cannot be replayed. The can occur in the case of a missing or damaged log device. - **resilver.start** Issued when a resilver is started. - **resilver.finish** Issued when the running resilver have finished. - **scrub.start** Issued when a scrub is started on a pool. - **scrub.finish** Issued when a pool has finished scrubbing. - **scrub.abort** Issued when a scrub is aborted on a pool. - **scrub.resume** Issued when a scrub is resumed on a pool. - **scrub.paused** Issued when a scrub is paused on a pool. - **bootfs.vdev.attach** ## PAYLOADS This is the payload (data, information) that accompanies an event. For [zed(8)](/zed/8.md), these are set to uppercase and prefixed with **ZEVENT\_**. - **pool** Pool name. - **pool\_failmode** Failmode - **wait**, **continue**, or **panic**. See the **failmode** property in [zpoolprops(7)](/zpoolprops/7.md) for more information. - **pool\_guid** The GUID of the pool. - **pool\_context** The load state for the pool (0=none, 1=open, 2=import, 3=tryimport, 4=recover 5=error). - **vdev\_guid** The GUID of the vdev in question (the vdev failing or operated upon with **zpool** **clear**, etc.). - **vdev\_type** Type of vdev - **disk**, **file**, **mirror**, etc. See the **Virtual** **Devices** section of [zpoolconcepts(7)](/zpoolconcepts/7.md) for more information on possible values. - **vdev\_path** Full path of the vdev, including any *-partX*. - **vdev\_devid** ID of vdev (if any). - **vdev\_fru** Physical FRU location. - **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** The ashift value of the vdev. - **vdev\_complete\_ts** The time the last I/O request completed for the specified vdev. - **vdev\_delta\_ts** The time since the last I/O request completed for the specified vdev. - **vdev\_spare\_paths** List of spares, including full path and any *-partX*. - **vdev\_spare\_guids** GUID(s) of spares. - **vdev\_read\_errors** How many read errors that have been detected on the vdev. - **vdev\_write\_errors** How many write errors that have been detected on the vdev. - **vdev\_cksum\_errors** How many checksum errors that have been detected on the vdev. - **parent\_guid** GUID of the vdev parent. - **parent\_type** Type of parent. See **vdev\_type**. - **parent\_path** Path of the vdev parent (if any). - **parent\_devid** ID of the vdev parent (if any). - **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 includes data blocks. Values \> 0 indicate metadata blocks at the appropriate level. - **zio\_blkid** The block ID for a given I/O request. - **zio\_err** The error number for a failure when handling a given I/O request, compatible with [errno(3)](/errno/3.md) with the value of **EBADE** used to indicate a ZFS checksum error. - **zio\_offset** The offset in bytes of where to write the I/O request 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. See the **I/O** **FLAGS** section for the full list of I/O flags. - **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** 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\_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** 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** Checksum algorithm used. See [zfsprops(7)](/zfsprops/7.md) for more information on the available checksum algorithms. - **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 can include some gaps of non-corruption. (See **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** 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** 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** 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** 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 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 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\_IO\_ALLOCATING | 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 | ## SEE ALSO [zfs(4)](/zfs/4.md), [zed(8)](/zed/8.md), [zpool-wait(8)](/zpool-wait/8.md)