1.\" SPDX-License-Identifier: CDDL-1.0 2.\" 3.\" CDDL HEADER START 4.\" 5.\" The contents of this file are subject to the terms of the 6.\" Common Development and Distribution License (the "License"). 7.\" You may not use this file except in compliance with the License. 8.\" 9.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10.\" or https://opensource.org/licenses/CDDL-1.0. 11.\" See the License for the specific language governing permissions 12.\" and limitations under the License. 13.\" 14.\" When distributing Covered Code, include this CDDL HEADER in each 15.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16.\" If applicable, add the following below this CDDL HEADER, with the 17.\" fields enclosed by brackets "[]" replaced with your own identifying 18.\" information: Portions Copyright [yyyy] [name of copyright owner] 19.\" 20.\" CDDL HEADER END 21.\" 22.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. 23.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved. 24.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved. 25.\" Copyright (c) 2017 Datto Inc. 26.\" Copyright (c) 2018 George Melikov. All Rights Reserved. 27.\" Copyright 2017 Nexenta Systems, Inc. 28.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved. 29.\" Copyright (c) 2024, 2025, Klara, Inc. 30.\" 31.Dd July 3, 2025 32.Dt ZPOOL-EVENTS 8 33.Os 34. 35.Sh NAME 36.Nm zpool-events 37.Nd list recent events generated by kernel 38.Sh SYNOPSIS 39.Nm zpool 40.Cm events 41.Op Fl vHf 42.Op Ar pool 43.Nm zpool 44.Cm events 45.Fl c 46. 47.Sh DESCRIPTION 48Lists all recent events generated by the ZFS kernel modules. 49These events are consumed by the 50.Xr zed 8 51and used to automate administrative tasks such as replacing a failed device 52with a hot spare. 53For more information about the subclasses and event payloads 54that can be generated see 55.Sx EVENTS 56and the following sections. 57. 58.Sh OPTIONS 59.Bl -tag -compact -width Ds 60.It Fl c 61Clear all previous events. 62.It Fl f 63Follow mode. 64.It Fl H 65Scripted mode. 66Do not display headers, and separate fields by a 67single tab instead of arbitrary space. 68.It Fl v 69Print the entire payload for each event. 70.El 71. 72.Sh EVENTS 73These are the different event subclasses. 74The full event name would be 75.Sy ereport.fs.zfs.\& Ns Em SUBCLASS , 76but only the last part is listed here. 77.Pp 78.Bl -tag -compact -width "vdev.bad_guid_sum" 79.It Sy checksum 80Issued when a checksum error has been detected. 81.It Sy io 82Issued when there is an I/O error in a vdev in the pool. 83.It Sy data 84Issued when there have been data errors in the pool. 85.It Sy deadman 86Issued when an I/O request is determined to be "hung", this can be caused 87by lost completion events due to flaky hardware or drivers. 88See 89.Sy zfs_deadman_failmode 90in 91.Xr zfs 4 92for additional information regarding "hung" I/O detection and configuration. 93.It Sy delay 94Issued when a completed I/O request exceeds the maximum allowed time 95specified by the 96.Sy zio_slow_io_ms 97module parameter. 98This can be an indicator of problems with the underlying storage device. 99The number of delay events is ratelimited by the 100.Sy zfs_slow_io_events_per_second 101module parameter. 102.It Sy dio_verify_rd 103Issued when there was a checksum verify error after a Direct I/O read has been 104issued. 105.It Sy dio_verify_wr 106Issued when there was a checksum verify error after a Direct I/O write has been 107issued. 108This event can only take place if the module parameter 109.Sy zfs_vdev_direct_write_verify 110is not set to zero. 111See 112.Xr zfs 4 113for more details on the 114.Sy zfs_vdev_direct_write_verify 115module parameter. 116.It Sy config_sync 117Issued every time a vdev change have been done to the pool. 118.It Sy zpool 119Issued when a pool cannot be imported. 120.It Sy pool_create 121Issued when a pool is created. 122.It Sy pool_destroy 123Issued when a pool is destroyed. 124.It Sy pool_export 125Issued when a pool is exported. 126.It Sy pool_import 127Issued when a pool is imported. 128.It Sy pool_reguid 129Issued when a REGUID (new unique identifier for the pool have been regenerated) 130have been detected. 131.It Sy vdev.unknown 132Issued when the vdev is unknown. 133Such as trying to clear device errors on a vdev that have failed/been kicked 134from the system/pool and is no longer available. 135.It Sy vdev.open_failed 136Issued when a vdev could not be opened (because it didn't exist for example). 137.It Sy vdev.corrupt_data 138Issued when corrupt data have been detected on a vdev. 139.It Sy vdev.no_replicas 140Issued when there are no more replicas to sustain the pool. 141This would lead to the pool being 142.Em DEGRADED . 143.It Sy vdev.bad_guid_sum 144Issued when a missing device in the pool have been detected. 145.It Sy vdev.too_small 146Issued when the system (kernel) have removed a device, and ZFS 147notices that the device isn't there any more. 148This is usually followed by a 149.Sy probe_failure 150event. 151.It Sy vdev.bad_label 152Issued when the label is OK but invalid. 153.It Sy vdev.bad_ashift 154Issued when the ashift alignment requirement has increased. 155.It Sy vdev_remove 156Issued when a vdev is detached from a mirror (or a spare detached from a 157vdev where it have been used to replace a failed drive - only works if 158the original drive have been re-added). 159.It Sy vdev_remove_aux 160Issued when an auxiliary vdev is removed. 161.It Sy vdev_remove_dev 162Issued when a specific device is removed from a vdev. 163.It Sy vdev_clear 164Issued when clearing device errors in a pool. 165Such as running 166.Nm zpool Cm clear 167on a device in the pool. 168.It Sy vdev_check 169Issued when a check to see if a given vdev could be opened is started. 170.It Sy vdev_spare 171Issued when a spare have kicked in to replace a failed device. 172.It Sy vdev_autoexpand 173Issued when a vdev can be automatically expanded. 174.It Sy vdev_add 175Issued when a vdev is added to a pool. 176.It Sy vdev_attach 177Issued when a vdev is attached to a mirror or raidz vdev type. 178.It Sy vdev_online 179Issued when an offline vdev is brought online 180.It Sy io_failure 181Issued when there is an I/O failure in a vdev in the pool. 182.It Sy probe_failure 183Issued when a probe fails on a vdev. 184This would occur if a vdev 185have been kicked from the system outside of ZFS (such as the kernel 186have removed the device). 187.It Sy log_replay 188Issued when the intent log cannot be replayed. 189The can occur in the case of a missing or damaged log device. 190.It Sy resilver_start 191Issued when a resilver is started. 192.It Sy resilver_finish 193Issued when the running resilver have finished. 194.It Sy scrub_start 195Issued when a scrub is started on a pool. 196.It Sy scrub_finish 197Issued when a pool has finished scrubbing. 198.It Sy scrub_abort 199Issued when a scrub is aborted on a pool. 200.It Sy scrub_resume 201Issued when a scrub is resumed on a pool. 202.It Sy scrub_paused 203Issued when a scrub is paused on a pool. 204.It Sy errorscrub_start 205Issued when a errorscrub is started on a pool. 206.It Sy errorscrub_finish 207Issued when a pool has finished errorscrubbing. 208.It Sy errorscrub_abort 209Issued when a errorscrub is aborted on a pool. 210.It Sy errorscrub_resume 211Issued when a errorscrub is resumed on a pool. 212.It Sy errorscrub_paused 213Issued when a errorscrub is paused on a pool. 214.It Sy trim_start 215Issued when a trim is started on a pool. 216.It Sy trim_finish 217Issued when a pool has finished trimbing. 218.It Sy trim_cancel 219Issued when a trim is canceled on a pool. 220.It Sy trim_resume 221Issued when a trim is resumed on a pool. 222.It Sy trim_suspend 223Issued when a trim is suspend on a pool. 224.It Sy authentication 225Issued when there is a decryption / authentication error. 226.It Sy config_cache_write 227Issued when the config cache file cannot be written. 228.It Sy bootfs_vdev_attach 229Issued when a vdev is attached to a root pool with the bootfs property set. 230.It Sy sitout 231Issued when a 232.Sy RAIDZ 233or 234.Sy DRAID 235vdev triggers the 236.Sy autosit 237logic. 238This logic detects when a disk in such a vdev is significantly slower than its 239peers, and sits them out temporarily to preserve the performance of the pool. 240.El 241. 242.Sh PAYLOADS 243This is the payload (data, information) that accompanies an 244event. 245.Pp 246For 247.Xr zed 8 , 248these are set to uppercase and prefixed with 249.Sy ZEVENT_ . 250.Pp 251.Bl -tag -compact -width "vdev_cksum_errors" 252.It Sy pool 253Pool name. 254.It Sy pool_failmode 255Failmode - 256.Sy wait , 257.Sy continue , 258or 259.Sy panic . 260See the 261.Sy failmode 262property in 263.Xr zpoolprops 7 264for more information. 265.It Sy pool_guid 266The GUID of the pool. 267.It Sy pool_context 268The load state for the pool (0=none, 1=open, 2=import, 3=tryimport, 4=recover 2695=error). 270.It Sy vdev_guid 271The GUID of the vdev in question (the vdev failing or operated upon with 272.Nm zpool Cm clear , 273etc.). 274.It Sy vdev_type 275Type of vdev - 276.Sy disk , 277.Sy file , 278.Sy mirror , 279etc. 280See the 281.Sy Virtual Devices 282section of 283.Xr zpoolconcepts 7 284for more information on possible values. 285.It Sy vdev_path 286Full path of the vdev, including any 287.Em -partX . 288.It Sy vdev_devid 289ID of vdev (if any). 290.It Sy vdev_fru 291Physical FRU location. 292.It Sy vdev_state 293State of vdev (0=uninitialized, 1=closed, 2=offline, 3=removed, 4=failed to 294open, 5=faulted, 6=degraded, 7=healthy). 295.It Sy vdev_ashift 296The ashift value of the vdev. 297.It Sy vdev_complete_ts 298The time the last I/O request completed for the specified vdev. 299.It Sy vdev_delta_ts 300The time since the last I/O request completed for the specified vdev. 301.It Sy vdev_spare_paths 302List of spares, including full path and any 303.Em -partX . 304.It Sy vdev_spare_guids 305GUID(s) of spares. 306.It Sy vdev_read_errors 307How many read errors that have been detected on the vdev. 308.It Sy vdev_write_errors 309How many write errors that have been detected on the vdev. 310.It Sy vdev_cksum_errors 311How many checksum errors that have been detected on the vdev. 312.It Sy parent_guid 313GUID of the vdev parent. 314.It Sy parent_type 315Type of parent. 316See 317.Sy vdev_type . 318.It Sy parent_path 319Path of the vdev parent (if any). 320.It Sy parent_devid 321ID of the vdev parent (if any). 322.It Sy zio_objset 323The object set number for a given I/O request. 324.It Sy zio_object 325The object number for a given I/O request. 326.It Sy zio_level 327The indirect level for the block. 328Level 0 is the lowest level and includes data blocks. 329Values > 0 indicate metadata blocks at the appropriate level. 330.It Sy zio_blkid 331The block ID for a given I/O request. 332.It Sy zio_err 333The error number for a failure when handling a given I/O request, 334compatible with 335.Xr errno 3 336with the value of 337.Sy EBADE 338used to indicate a ZFS checksum error. 339.It Sy zio_offset 340The offset in bytes of where to write the I/O request for the specified vdev. 341.It Sy zio_size 342The size in bytes of the I/O request. 343.It Sy zio_flags 344The current flags describing how the I/O request should be handled. 345See the 346.Sy I/O FLAGS 347section for the full list of I/O flags. 348.It Sy zio_stage 349The current stage of the I/O in the pipeline. 350See the 351.Sy I/O STAGES 352section for a full list of all the I/O stages. 353.It Sy zio_pipeline 354The valid pipeline stages for the I/O. 355See the 356.Sy I/O STAGES 357section for a full list of all the I/O stages. 358.It Sy zio_priority 359The queue priority of the I/O request. 360See the 361.Sy I/O PRIORITIES 362section for a full list of all the I/O priorities. 363.It Sy zio_tyoe 364The type of the I/O request. 365See the 366.Sy I/O TYPES 367section for a full list of all the I/O types. 368.It Sy zio_delay 369The time elapsed (in nanoseconds) waiting for the block layer to complete the 370I/O request. 371Unlike 372.Sy zio_delta , 373this does not include any vdev queuing time and is 374therefore solely a measure of the block layer performance. 375.It Sy zio_timestamp 376The time when a given I/O request was submitted. 377.It Sy zio_delta 378The time required to service a given I/O request. 379.It Sy prev_state 380The previous state of the vdev. 381.It Sy cksum_algorithm 382Checksum algorithm used. 383See 384.Xr zfsprops 7 385for more information on the available checksum algorithms. 386.It Sy cksum_byteswap 387Whether or not the data is byteswapped. 388.It Sy bad_ranges 389.No [\& Ns Ar start , end ) 390pairs of corruption offsets. 391Offsets are always aligned on a 64-bit boundary, 392and can include some gaps of non-corruption. 393(See 394.Sy bad_ranges_min_gap ) 395.It Sy bad_ranges_min_gap 396In order to bound the size of the 397.Sy bad_ranges 398array, gaps of non-corruption 399less than or equal to 400.Sy bad_ranges_min_gap 401bytes have been merged with 402adjacent corruption. 403Always at least 8 bytes, since corruption is detected on a 64-bit word basis. 404.It Sy bad_range_sets 405This array has one element per range in 406.Sy bad_ranges . 407Each element contains 408the count of bits in that range which were clear in the good data and set 409in the bad data. 410.It Sy bad_range_clears 411This array has one element per range in 412.Sy bad_ranges . 413Each element contains 414the count of bits for that range which were set in the good data and clear in 415the bad data. 416.It Sy bad_set_bits 417If this field exists, it is an array of 418.Pq Ar bad data No & ~( Ns Ar good data ) ; 419that is, the bits set in the bad data which are cleared in the good data. 420Each element corresponds a byte whose offset is in a range in 421.Sy bad_ranges , 422and the array is ordered by offset. 423Thus, the first element is the first byte in the first 424.Sy bad_ranges 425range, and the last element is the last byte in the last 426.Sy bad_ranges 427range. 428.It Sy bad_cleared_bits 429Like 430.Sy bad_set_bits , 431but contains 432.Pq Ar good data No & ~( Ns Ar bad data ) ; 433that is, the bits set in the good data which are cleared in the bad data. 434.El 435. 436.Sh I/O STAGES 437The ZFS I/O pipeline is comprised of various stages which are defined below. 438The individual stages are used to construct these basic I/O 439operations: Read, Write, Free, Claim, Flush and Trim. 440These stages may be 441set on an event to describe the life cycle of a given I/O request. 442.Pp 443.TS 444tab(:); 445l l l . 446Stage:Bit Mask:Operations 447_:_:_ 448ZIO_STAGE_OPEN:0x00000001:RWFCXT 449 450ZIO_STAGE_READ_BP_INIT:0x00000002:R----- 451ZIO_STAGE_WRITE_BP_INIT:0x00000004:-W---- 452ZIO_STAGE_FREE_BP_INIT:0x00000008:--F--- 453ZIO_STAGE_ISSUE_ASYNC:0x00000010:-WF--T 454ZIO_STAGE_WRITE_COMPRESS:0x00000020:-W---- 455 456ZIO_STAGE_ENCRYPT:0x00000040:-W---- 457ZIO_STAGE_CHECKSUM_GENERATE:0x00000080:-W---- 458 459ZIO_STAGE_NOP_WRITE:0x00000100:-W---- 460 461ZIO_STAGE_BRT_FREE:0x00000200:--F--- 462 463ZIO_STAGE_DDT_READ_START:0x00000400:R----- 464ZIO_STAGE_DDT_READ_DONE:0x00000800:R----- 465ZIO_STAGE_DDT_WRITE:0x00001000:-W---- 466ZIO_STAGE_DDT_FREE:0x00002000:--F--- 467 468ZIO_STAGE_GANG_ASSEMBLE:0x00004000:RWFC-- 469ZIO_STAGE_GANG_ISSUE:0x00008000:RWFC-- 470 471ZIO_STAGE_DVA_THROTTLE:0x00010000:-W---- 472ZIO_STAGE_DVA_ALLOCATE:0x00020000:-W---- 473ZIO_STAGE_DVA_FREE:0x00040000:--F--- 474ZIO_STAGE_DVA_CLAIM:0x00080000:---C-- 475 476ZIO_STAGE_READY:0x00100000:RWFCIT 477 478ZIO_STAGE_VDEV_IO_START:0x00200000:RW--XT 479ZIO_STAGE_VDEV_IO_DONE:0x00400000:RW--XT 480ZIO_STAGE_VDEV_IO_ASSESS:0x00800000:RW--XT 481 482ZIO_STAGE_CHECKSUM_VERIFY:0x01000000:R----- 483ZIO_STAGE_DIO_CHECKSUM_VERIFY:0x02000000:-W---- 484 485ZIO_STAGE_DONE:0x04000000:RWFCXT 486.TE 487. 488.Sh I/O FLAGS 489Every I/O request in the pipeline contains a set of flags which describe its 490function and are used to govern its behavior. 491These flags will be set in an event as a 492.Sy zio_flags 493payload entry. 494.Pp 495.TS 496tab(:); 497l l . 498Flag:Bit Mask 499_:_ 500ZIO_FLAG_DONT_AGGREGATE:0x00000001 501ZIO_FLAG_IO_REPAIR:0x00000002 502ZIO_FLAG_SELF_HEAL:0x00000004 503ZIO_FLAG_RESILVER:0x00000008 504ZIO_FLAG_SCRUB:0x00000010 505ZIO_FLAG_SCAN_THREAD:0x00000020 506ZIO_FLAG_PHYSICAL:0x00000040 507 508ZIO_FLAG_CANFAIL:0x00000080 509ZIO_FLAG_SPECULATIVE:0x00000100 510ZIO_FLAG_CONFIG_WRITER:0x00000200 511ZIO_FLAG_DONT_RETRY:0x00000400 512ZIO_FLAG_NODATA:0x00001000 513ZIO_FLAG_INDUCE_DAMAGE:0x00002000 514 515ZIO_FLAG_ALLOC_THROTTLED:0x00004000 516ZIO_FLAG_IO_RETRY:0x00008000 517ZIO_FLAG_PROBE:0x00010000 518ZIO_FLAG_TRYHARD:0x00020000 519ZIO_FLAG_OPTIONAL:0x00040000 520 521ZIO_FLAG_DONT_QUEUE:0x00080000 522ZIO_FLAG_DONT_PROPAGATE:0x00100000 523ZIO_FLAG_IO_BYPASS:0x00200000 524ZIO_FLAG_IO_REWRITE:0x00400000 525ZIO_FLAG_RAW_COMPRESS:0x00800000 526ZIO_FLAG_RAW_ENCRYPT:0x01000000 527 528ZIO_FLAG_GANG_CHILD:0x02000000 529ZIO_FLAG_DDT_CHILD:0x04000000 530ZIO_FLAG_GODFATHER:0x08000000 531ZIO_FLAG_NOPWRITE:0x10000000 532ZIO_FLAG_REEXECUTED:0x20000000 533ZIO_FLAG_DELEGATED:0x40000000 534ZIO_FLAG_FASTWRITE:0x80000000 535.TE 536. 537.Sh I/O TYPES 538Every I/O request in the pipeline has a single type value. 539This value describes the kind of low-level work the I/O represents. 540This value will be set in an event as a 541.Sy zio_type 542payload entry. 543.Pp 544.TS 545tab(:); 546l l l . 547Type:Value:Description 548_:_:_ 549ZIO_TYPE_NULL:0x0:internal I/O sync point 550ZIO_TYPE_READ:0x1:data read 551ZIO_TYPE_WRITE:0x2:data write 552ZIO_TYPE_FREE:0x3:block free 553ZIO_TYPE_CLAIM:0x4:block claim (ZIL replay) 554ZIO_TYPE_FLUSH:0x5:disk cache flush request 555ZIO_TYPE_TRIM:0x6:trim (discard) 556.TE 557. 558.Sh I/O PRIORITIES 559Every I/O request in the pipeline has a single priority value. 560This value is used by the queuing code to decide which I/O to issue next. 561This value will be set in an event as a 562.Sy zio_priority 563payload entry. 564.Pp 565.TS 566tab(:); 567l l l . 568Type:Value:Description 569_:_:_ 570ZIO_PRIORITY_SYNC_READ:0x0: 571ZIO_PRIORITY_SYNC_WRITE:0x1:ZIL 572ZIO_PRIORITY_ASYNC_READ:0x2:prefetch 573ZIO_PRIORITY_ASYNC_WRITE:0x3:spa_sync() 574ZIO_PRIORITY_SCRUB:0x4:asynchronous scrub/resilver reads 575ZIO_PRIORITY_REMOVAL:0x5:reads/writes for vdev removal 576ZIO_PRIORITY_INITIALIZING:0x6:initializing I/O 577ZIO_PRIORITY_TRIM:0x7:trim I/O (discard) 578ZIO_PRIORITY_REBUILD:0x8:reads/writes for vdev rebuild 579ZIO_PRIORITY_NOW:0xa:non-queued i/os (e.g. free) 580.TE 581. 582.Sh SEE ALSO 583.Xr zfs 4 , 584.Xr zed 8 , 585.Xr zpool-wait 8 586