Querying ZFS Storage Pool Status

The zpool list command provides several ways to request
information regarding pool status. The information available generally falls
into three categories: basic usage information, I/O statistics, and health
status. All three types of storage pool information are covered in this section.

Listing Specific Storage Pool Statistics

Specific statistics can be requested by using the -o option.
This option provides custom reports or a quick way to list pertinent information.
For example, to list only the name and size of each pool, you use the following
syntax:

Scripting ZFS Storage Pool Output

The default output for the zpool list command is
designed for readability and is not easy to use as part of a shell script.
To aid programmatic uses of the command, the -H option can
be used to suppress the column headings and separate fields by tabs, rather
than by spaces. For example, to request a list of all pool names on the system,
you would use the following syntax:

# zpool list -Ho name
tank
dozer

Here is another example:

# zpool list -H -o name,size
tank 80.0G
dozer 1.2T

Displaying ZFS Storage Pool Command History

ZFS automatically logs successful zfs and zpool commands that modify pool state information. This information can
be displayed by using the zpool history command.

For example, the following syntax displays the command output for the
root pool:

Viewing I/O Statistics for ZFS Storage Pools

To request I/O statistics for a pool or specific virtual devices, use
the zpool iostat command. Similar to the iostat command,
this command can display a static snapshot of all I/O activity, as well as
updated statistics for every specified interval. The following statistics
are reported:

alloc capacity

The amount of data currently stored in the pool or device.
This amount differs from the amount of disk space available to actual file
systems by a small margin due to internal implementation details.

Because these statistics are cumulative since boot, bandwidth might
appear low if the pool is relatively idle. You can request a more accurate
view of current bandwidth usage by specifying an interval. For example:

In this example, the command displays usage statistics for the pool tank every two seconds until you type Control-C. Alternately, you
can specify an additional count argument, which causes
the command to terminate after the specified number of iterations. For example, zpool iostat 2 3 would print a summary every two seconds for three
iterations, for a total of six seconds. If there is only a single pool, then
the statistics are displayed on consecutive lines. If more than one pool exists,
then an additional dashed line delineates each iteration to provide visual
separation.

Listing Virtual Device I/O Statistics

In addition to pool-wide I/O statistics, the zpool iostat command
can display I/O statistics for virtual devices. This command can be used to
identify abnormally slow devices or to observe the distribution of I/O generated
by ZFS. To request the complete virtual device layout as well as all I/O statistics,
use the zpool iostat -v command. For example:

Note two important points when viewing I/O statistics for virtual devices:

First, disk space usage statistics are only available for
top-level virtual devices. The way in which disk space is allocated among
mirror and RAID-Z virtual devices is particular to the implementation and
not easily expressed as a single number.

Second, the numbers might not add up exactly as you would
expect them to. In particular, operations across RAID-Z and mirrored devices
will not be exactly equal. This difference is particularly noticeable immediately
after a pool is created, as a significant amount of I/O is done directly to
the disks as part of pool creation, which is not accounted for at the mirror
level. Over time, these numbers gradually equalize. However, broken, unresponsive,
or offline devices can affect this symmetry as well.

You can use the same set of options (interval and count) when examining
virtual device statistics.

Determining the Health Status of ZFS Storage Pools

ZFS provides an integrated method of examining pool and device health.
The health of a pool is determined from the state of all its devices. This
state information is displayed by using the zpool status command.
In addition, potential pool and device failures are reported by fmd,
displayed on the system console, and logged in the /var/adm/messages file.

The device or virtual device is in normal working order. Although
some transient errors might still occur, the device is otherwise in working
order.

DEGRADED

The virtual device has experienced a failure but can still
function. This state is most common when a mirror or RAID-Z device has lost
one or more constituent devices. The fault tolerance of the pool might be
compromised, as a subsequent fault in another device might be unrecoverable.

FAULTED

The device or virtual device is completely inaccessible. This
status typically indicates total failure of the device, such that ZFS is incapable
of sending data to it or receiving data from it. If a top-level virtual device
is in this state, then the pool is completely inaccessible.

OFFLINE

The device has been explicitly taken offline by the administrator.

UNAVAIL

The device or virtual device cannot be opened. In some cases,
pools with UNAVAIL devices appear in DEGRADED mode.
If a top-level virtual device is UNAVAIL, then nothing
in the pool can be accessed.

REMOVED

The device was physically removed while the system was running.
Device removal detection is hardware-dependent and might not be supported
on all platforms.

The health of a pool is determined from the health of all its top-level
virtual devices. If all virtual devices are ONLINE, then
the pool is also ONLINE. If any one of the virtual devices
is DEGRADED or UNAVAIL, then the pool
is also DEGRADED. If a top-level virtual device is FAULTED or OFFLINE, then the pool is also FAULTED.
A pool in the FAULTED state is completely inaccessible.
No data can be recovered until the necessary devices are attached or repaired.
A pool in the DEGRADED state continues to run, but you
might not achieve the same level of data redundancy or data throughput than
if the pool were online.

Basic Storage Pool Health Status

You can quickly review pool health status by using the zpool
status command as follows:

# zpool status -x
all pools are healthy

Specific pools can be examined by specifying a pool name in the command
syntax. Any pool that is not in the ONLINE state should
be investigated for potential problems, as described in the next section.

Detailed Health Status

You can request a more detailed health summary status by using the -v option. For example:

This output displays a complete description of why the pool is in its
current state, including a readable description of the problem and a link
to a knowledge article for more information. Each knowledge article provides
up-to-date information about the best way to recover from your current problem.
Using the detailed configuration information, you can determine which device
is damaged and how to repair the pool.

In the preceding example, the faulted device should be replaced. After
the device is replaced, use the zpool online command to
bring the device online. For example:

The READ and WRITE columns provide
a count of I/O errors that occurred on the device, while the CKSUM column
provides a count of uncorrectable checksum errors that occurred on the device.
Both error counts indicate a potential device failure, and some corrective
action is needed. If non-zero errors are reported for a top-level virtual
device, portions of your data might have become inaccessible.

The errors: field identifies any known data errors.

In the preceding example output, the offline device is not causing data
errors.