banshee/containers-collection/containers/docker/ssh/disk

Docker disk usage, by SSH

Returns, for the images, the containers, the local volumes and the build cache of a Docker host, the space they take, the space that could be freed, how many there are and how many are in use, read by docker system df. Two watches are offered, each one set on the probe, neither checked by default. It runs docker through sudo, restricted to the one command below, or straight when the monitoring account is in the docker group.

Versions

Generic: docker system df --format '{{json .}}' is served by every Docker Engine still supported. It stays at the common level.

How it works

One command, which only reads:

sudo -n /usr/bin/docker system df --format '{{json .}}'

(without sudo -n when the variable docker:sudo is off). It writes one JSON object per type:

{"Type": "Images", "TotalCount": "5", "Active": "2", "Size": "16.43MB", "Reclaimable": "11.63MB (70%)"}

A type is named in lower case, its words joined by -: images, containers, local-volumes, build-cache.
The sizes are written by Docker in decimal units (B, kB, MB, GB, TB, PB), four significant figures, the unit right after the number (16.43MB; older documentation shows a space, which is read too), and returned in GiB, to the hundredth. A size Docker writes otherwise is not returned. The build cache's Reclaimable carries no percentage.
reclaimable is what nothing uses any more, what docker system prune would free (with --volumes for the volumes).
A Docker daemon that does not answer stops the collector critical; sudo refusing the command, docker missing, or an account outside the docker group, stop it misconfigured, with what was said. An answer with no type at all stops it misconfigured.

Prerequisites

An SSH account for monitoring, without write rights (monitoring below; put the account's name in its place).
The Docker command at /usr/bin/docker.
One of the two: - a sudoers line, the default (docker:sudo on), in /etc/sudoers.d/banshee-docker, owned by root, mode 0440, checked with visudo -cf /etc/sudoers.d/banshee-docker:

monitoring ALL=(root) NOPASSWD: /usr/bin/docker system df --format {{json .}}

The account may run, as root and without a password, this one command and nothing else (not -v, which lists every image, container and volume). The lines of all the Docker collectors together are given in the documentation of the collector of the containers. - the docker group (usermod -aG docker monitoring), with docker:sudo off. Simpler, but the docker group is worth root: whoever may talk to the Docker daemon may start a container that mounts the host's disk. The sudoers line is the choice this documentation recommends.

The fingerprint of the server's host key, set in protocol:ssh:fingerprint (not needed when the Security settings trust the first SSH fingerprint presented).

Variables

Name	Label	Says	Default
`docker:sudo`	Through sudo	runs `docker` through `sudo -n`; off when the account is in the `docker` group	on

docker:sudo is the collector's own variable: it is set on the probe, not on a folder or a host. On a host whose account is in the docker group, it is turned off on each Docker probe; duplicating a probe already set carries it to the next host.

Outputs

Name	Label	Unit	Per instance
`size`	Space used	GiB	yes, per type
`reclaimable`	Space that could be freed	GiB	yes, per type
`count`	Count	—	yes, per type
`active`	In use	—	yes, per type

Watches

Name	Title	Kind	Defaults	Checked by default
`size`	Docker space used	above a threshold, on `size`	none: the threshold depends on the disk, in GiB	no
`reclaimable`	Space to free	above a threshold, on `reclaimable`	none, in GiB	no

Whether the disk fills is the filesystem collector's, on the filesystem that holds /var/lib/docker: this one says what Docker holds on it, and what a prune would give back.

Limits

docker system df walks the images, containers and volumes to size them: on a host with many, it takes a few seconds.
Docker rounds the sizes to four figures, and the collector to the hundredth of a GiB: a type under 5 MiB reads 0.
Sources: the documentation of docker system df gives its table and its types; the fields (Type, TotalCount, Active, Size, Reclaimable) and the four type names are those of the Docker command's source (cli/command/formatter/disk_usage.go), the sizes those of go-units (HumanSize). Not run against a Docker host, nor the sudoers line against a sudo.