banshee/storage-collection/storage/truenas/https/api-v2.0/disks

Disks of the pools of a TrueNAS, by its REST API

Returns, for each disk of the ZFS pools of a TrueNAS, its state and its count of read, write and checksum errors, as zpool status shows them, read from the REST API behind an API key. Four watches are offered, each one set on the probe.

Versions

Written for the REST API v2.0, which answers on TrueNAS CORE 12 and 13 and on TrueNAS SCALE up to 25.10, and was removed in TrueNAS 26. Hence the folder api-v2.0.

How it works

One GET https://<host:address>/api/v2.0/pool, the key in the header Authorization: Bearer. Each pool carries its topology, as the ZFS library of TrueNAS describes it:

"topology": {"data": [{"type": "MIRROR", "status": "ONLINE", "children": [
    {"type": "DISK", "name": "4b0f7e1c-…", "status": "ONLINE", "stats": {"read_errors": 0, "write_errors": 0, "checksum_errors": 0}, "children": []}, …]}],
  "log": [], "cache": [], "spare": [], "special": [], "dedup": []}

Every device of every group is walked, down to the disks: a mirror or a RAIDZ holds its disks, a disk being replaced holds the old and the new one.
A disk is named after its pool and the name ZFS keeps for it (tank: 4b0f7e1c-…, or tank: gptid/… on CORE), which a missing disk keeps too.
The state is the device's status in lower case: online, degraded, faulted, offline, unavail, removed; avail for a spare not in use.
The errors are the sum of the three counts since the pool was imported or the counts cleared.
Only a pool online or degraded is read: a failed pool is seen by storage/truenas/https/api-v2.0/pools.

The key comes from protocol:http:token, a secret variable: it only goes in the header. The answer is not secret.

Prerequisites

The web interface of TrueNAS reachable from the poller in HTTPS, on port 443 of the host's address, its certificate trusted by the TLS profile of the probe (a pinned fingerprint in protocol:http:fingerprint, or the certificate under protocol:tls:authorities).
An API key in protocol:http:token, of a user of the read-only administrator role where SCALE has roles.

Outputs

Name	Label	Unit	Per instance
`state`	State	—	yes, per disk
`errors`	Read, write and checksum errors	—	yes, per disk

Watches

Name	Title	Kind	Defaults	Checked by default
`not-online`	Disk not online	expected value, on `state`	warning when the state is anything but `online` or `avail`	yes
`failed`	Disk failed	state to avoid, on `state`	critical on `faulted`, `unavail`, `removed`	yes
`errors`	Disk errors	above a threshold, on `errors`	warning above 0	yes
`missing`	Disk missing	expected instances, on `state`	no disk named: it raises nothing until names are set on the probe	no

Limits

A disk outside any pool, and the health SMART reports, are not read: the disk list of the API carries neither. TrueNAS raises its own alert on a SMART failure, which storage/truenas/https/api-v2.0/alerts reads.
The errors stay counted until an administrator clears them (zpool clear): errors raises until then.
From TrueNAS 25.10.1, each call to the REST API raises a TrueNAS alert that a deprecated endpoint is used.
The address is written into the URL as is: an IPv6 address must be given as a name.
Not checked against a TrueNAS: the pool fields are those of pool.query in the API documentation of TrueNAS 25.10; the device fields are those of the ZFS library of TrueNAS (py-libzfs, ZFSVdev.asdict), which the documentation does not detail.