Implement or add documentation about `docker system df --format`

[danielhoherd]

Description

docker system df --help shows that there is a --format option:

$ docker system df --help

Usage:  docker system df [OPTIONS]

Show docker disk usage

Options:
      --format string   Pretty-print images using a Go template
  -v, --verbose         Show detailed information on space usage

There is no documentation about how to use this option though, and snips copied from the source code also do not work.

Reproduce

1. run docker system df --format='{{.ID}}'
2. Observe the following error: Template parsing error: template: :1:2: executing "" at <.ID>: can't evaluate field ID in type *formatter.diskUsageImagesContext
3. Try any other template string you can find or come up with, and observe a similar error.

Expected behavior

It is expected that options shown in the help text will work.

It is expected that when a format string is available, the variables that can be interpolated into that format string are described in documentation, and/or listed in the man page or other official documentation. EG: man stat, man date

Extra credit for having useful examples in documentation. EG in both of the above links.

docker version

Client:
 Version:           20.10.3
 API version:       1.41
 Go version:        go1.13.5
 Git commit:        48d30b5b32
 Built:             Sun Apr 24 16:58:20 2022
 OS/Arch:           linux/amd64
 Context:           default
 Experimental:      true

Server:
 Engine:
  Version:          20.10.3
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.13.5
  Git commit:       46229ca1d8
  Built:            Sun Apr 24 17:35:06 2022
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.4.13
  GitCommit:        9cc61520f4cd876b86e77edfeb88fbcd536d1f9d
 runc:
  Version:          1.0.3
  GitCommit:        f46b6ba2c9314cfc8caae24a32ec5fe9ef1059fe
 docker-init:
  Version:          0.19.0
  GitCommit:        fec3683b971d9c3ef73f284f176672c44b448662

docker info

Client:
 Context:    default
 Debug Mode: false

Server:
 Containers: 137
  Running: 108
  Paused: 0
  Stopped: 29
 Images: 343
 Server Version: 20.10.3
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 9cc61520f4cd876b86e77edfeb88fbcd536d1f9d
 runc version: f46b6ba2c9314cfc8caae24a32ec5fe9ef1059fe
 init version: fec3683b971d9c3ef73f284f176672c44b448662 (expected: de40ad007797e0dcd8b7126f27bb87401d224240)
 Security Options:
  apparmor
  seccomp
   Profile: default
 Kernel Version: 5.4.188+
 Operating System: Container-Optimized OS from Google
 OSType: linux
 Architecture: x86_64
 CPUs: 32
 Total Memory: 117.9GiB
 Name: gke-prod-cluster-terraform-2020043023-58a857b0-5rnc
 ID: 3E22:KMVD:SETY:3MQU:QZA7:OIFU:SS54:RLIT:B4SV:UTNT:VE66:4SGN
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  10.0.0.0/8
  127.0.0.0/8
 Registry Mirrors:
  https://mirror.gcr.io/
 Live Restore Enabled: true

[grimmy]

For anyone else that runs into this, you need to pass --verbose to make it work.

docker system df --verbose --format='{{range .Images}}{{.ID}}\n{{end}}'

[thaJeztah]

It depends a bit on what you want to format; without --verbose, it's possible to format the default (non-verbose) output, for example;

docker system df --format json
{"Active":"5","Reclaimable":"23.7GB (94%)","Size":"25.15GB","TotalCount":"14","Type":"Images"}
{"Active":"2","Reclaimable":"86.02kB (0%)","Size":"217.4MB","TotalCount":"4","Type":"Containers"}
{"Active":"4","Reclaimable":"624MB (21%)","Size":"2.882GB","TotalCount":"6","Type":"Local Volumes"}
{"Active":"0","Reclaimable":"10.52GB","Size":"10.52GB","TotalCount":"284","Type":"Build Cache"}


docker system df --format 'table {{.Type}}\t{{.Reclaimable}}'
TYPE            RECLAIMABLE
Images          23.7GB (94%)
Containers      86.02kB (0%)
Local Volumes   624MB (21%)
Build Cache     10.52GB

[grimmy]

Sure, but OP was trying to get a list of images by id, which you need --verbose for.

Side note, I was looking at this as an easy way to get the size of all volumes, but the size option is always humanized when makes it difficult to export to prometheus.

[thaJeztah]

Sure, but OP was trying to get a list of images by id, which you need --verbose for.

Yup! And your example made sense! I saw this ticket in my notifications to add a quick blurb (in case people do not need the verbose output, and only the default ones). Could also be useful if someone gets around to look at updating the docs 😅

but the size option is always humanized.

Yeah, mistakes were made 😞. For some of those its may be something we have to deal with (because changing could be a risk to break compatibility). OTOH, there may be various cases where nobody probably would be able to use the formatted output for anything useful, so perhaps we should just go ahead and fix those mistakes (or see if we can find good alternatives). I recall I once opened a ticket for that, but it would need evaluating where we can make changes;

• [RFD] JSON output produced by --format should not prettify values #674

when makes it difficult to export to prometheus.

I recall we once discussed (and maybe there's a tracking ticket) to also add a --size option to docker volume ls (I'd have to do a search to see if I can find it). It may be that there were (besides calculating the size being a rather heavy operation) some technical implications as well (related to volume-driver plugins?), but I need to read that back.

I wonder if it would be something that could be added to the prometheus metrics exposed by the daemon though 🤔
https://docs.docker.com/engine/daemon/prometheus/

Prometheus metrics exposed by the daemon are rather limited (and could use some TLC), but feel free to open a ticket in https://github.com/moby/moby if there's specific things you're looking for / use-cases (such things may require discussion, but describing your use-case is always a good thing as it can get such conversations started) (also see moby/moby#27307)

[danielhoherd]

I'm happy to see this discussion taking life, and I'm happy to see workarounds.

I'd like to point out this bit from the original description:

There is no documentation about how to use this option though, and snips copied from the source code also do not work.