Documentation
¶
Overview ¶
Package report holds the data model dockdu renders. Every byte value is an int64 in bytes; -1 means unknown. Each section carries its own suggestions (commands printed as text, never executed) and the warnings that explain which parts of it are partial.
Index ¶
- Constants
- func Bytes(n int64) string
- func ShellQuote(s string) string
- func SuggestBuildxPrune(builder string) string
- func SuggestVolumeRm(name string) string
- func WriteJSON(w io.Writer, r *Report) error
- func WriteText(w io.Writer, r *Report, top int) error
- type BuildCache
- type BuildxBuilder
- type Daemon
- type Desktop
- type DiskItem
- type DiskUsage
- type Filesystem
- type ImageItem
- type Images
- type LogItem
- type Logs
- type Overlay2Usage
- type Project
- type Projects
- type Report
- type Summary
- type VolumeItem
- type Volumes
Constants ¶
const ( SuggestBuilderPruneOld = "docker builder prune --filter until=168h # unused build cache older than 7 days" SuggestBuilderPruneAll = "docker builder prune -a # all build cache not in use (next build is slower)" SuggestImagePruneDangling = "docker image prune # untagged (<none>) images only" SuggestImagePruneAll = "" /* 137-byte string literal not displayed */ SuggestLogOptsDaemon = `` /* 138-byte string literal not displayed */ SuggestDiskWalk = "" /* 174-byte string literal not displayed */ SuggestLogOptsDaemonRootless = `` /* 161-byte string literal not displayed */ SuggestLogOptsContainer = "recreate the container with --log-opt max-size=10m --log-opt max-file=3 # or --log-driver local" SuggestBuildxLs = "" /* 132-byte string literal not displayed */ )
Suggestions are printed as text and never executed. None of them touches volumes: a volume holds data that no other Docker object reproduces.
const SchemaVersion = 1
SchemaVersion identifies the JSON contract. It changes only when a field is removed, renamed or changes meaning; adding fields keeps it.
Variables ¶
This section is empty.
Functions ¶
func Bytes ¶
Bytes formats a byte count in binary units with one decimal, or "unknown" for negative values, which the model uses for "not measured".
func ShellQuote ¶ added in v0.2.0
ShellQuote returns s unchanged when it is a plain name and otherwise wraps it in single quotes, escaping embedded single quotes, so a crafted name cannot add a second command to a suggestion.
func SuggestBuildxPrune ¶ added in v0.4.0
SuggestBuildxPrune formats the prune hint for a docker-container buildx builder. The name is derived from a volume name, so it is quoted like one; with control characters it falls back to the lookup hint.
func SuggestVolumeRm ¶
SuggestVolumeRm formats the single-volume removal hint. There is no bulk form on purpose. The name comes from the daemon, so it is quoted for a POSIX shell; a name with control characters gets no command at all, because no quoting makes such a line safe to paste.
Types ¶
type BuildCache ¶
type BuildCache struct {
Records int `json:"records"`
TotalBytes int64 `json:"total_bytes"`
PrivateBytes int64 `json:"private_bytes"`
ReclaimableBytes int64 `json:"reclaimable_bytes"`
NotFreedByPrune int64 `json:"not_freed_by_prune_bytes"`
InUseBytes int64 `json:"in_use_bytes"`
// cache row contains. Daemons on API >= 1.52 include shared records in
// the row; for older daemons the client computes the row without them,
// so this is 0 and the summary subtracts nothing.
SharedCountedInDfBytes int64 `json:"shared_counted_in_df_bytes"`
// (shared records left out).
DfRowExcludesShared bool `json:"df_row_excludes_shared"`
// DfRowMismatch is true when df's row matches neither rule; the summary
// total is then a lower bound.
DfRowMismatch bool `json:"df_row_mismatch"`
// build cache record shared with an image can still keep its own copy of
// the data, so a prune frees an unknown part of SharedBytes and
// NotFreedByPrune is -1. Measured 2026-10-14: Engine 29.9 freed 72.7 of
// 140.7 MiB of shared records; Engine 28.5 on overlay2 freed none.
SharedMayBeFreedByPrune bool `json:"shared_may_be_freed_by_prune"`
// Builders are buildx builders with the docker-container driver, found
// through their state volumes. Their cache is not in df's build cache
// row or in the records above; its size is the volume's, which df
// counts under volumes. Never null.
Builders []BuildxBuilder `json:"buildx_builders"`
Suggestions []string `json:"suggestions"`
}
BuildCache follows SPEC §6.4.
type BuildxBuilder ¶ added in v0.4.0
type BuildxBuilder struct {
Node string `json:"node"`
Volume string `json:"volume"`
// Builder is the builder name derived from buildx's default node name
// <builder>0; "" when the node name does not follow it.
Builder string `json:"builder,omitempty"`
Bytes int64 `json:"bytes"`
// Reference is the volume's: "referenced" while the builder's
// container exists, "unreferenced" after `docker buildx rm
// --keep-state` or a manual container removal, or "unknown".
Reference string `json:"reference"`
}
BuildxBuilder is one docker-container buildx node and its state volume (buildx_buildkit_<node>_state, buildx driver/docker-container).
type Daemon ¶
type Daemon struct {
Host string `json:"host"`
ServerVersion string `json:"server_version"`
APIVersion string `json:"api_version"`
OperatingSystem string `json:"operating_system"`
StorageDriver string `json:"storage_driver"`
LoggingDriver string `json:"logging_driver"`
DataRoot string `json:"data_root"`
// ImageStore is "containerd" (containerd image store, the default on
// fresh Engine 29 installs and Docker Desktop) or "graphdriver"
// (overlay2 and other graph drivers). Build cache accounting differs.
ImageStore string `json:"image_store"`
// Rootless is true for a rootless daemon, whose configuration lives in
// ~/.config/docker/daemon.json instead of /etc/docker/daemon.json.
Rootless bool `json:"rootless"`
// ReportedDataRoot is the daemon\'s own data root when --data-root
// overrode it; DataRoot is then the path dockdu actually read.
ReportedDataRoot string `json:"reported_data_root,omitempty"`
}
Daemon identifies where the numbers came from.
type Desktop ¶
type Desktop struct {
Product string `json:"product"`
DiskFile string `json:"disk_file"`
ApparentBytes int64 `json:"apparent_bytes"`
AllocatedBytes int64 `json:"allocated_bytes"`
// DockerReportedBytes is Summary.DockerBytesTotal, repeated here next to
// the allocated size. The two are different measures and may overlap.
DockerReportedBytes int64 `json:"docker_reported_bytes"`
Explanation string `json:"explanation"`
}
Desktop is the macOS Docker Desktop / OrbStack section.
type DiskItem ¶ added in v0.3.0
type DiskItem struct {
Name string `json:"name"`
AllocatedBytes int64 `json:"allocated_bytes"`
Entries int64 `json:"entries"`
}
DiskItem is one top-level entry of the data root (overlay2, containerd, containers, volumes, buildkit, ...). Files directly in the root are grouped as "(files)".
type DiskUsage ¶ added in v0.3.0
type DiskUsage struct {
AllocatedBytes int64 `json:"allocated_bytes"`
Entries int64 `json:"entries"`
// Complete is false when a directory was unreadable or a budget (time,
// entry count) ran out; AllocatedBytes is then a lower bound.
Complete bool `json:"complete"`
UnreadableDirs int `json:"unreadable_dirs"`
SkippedMounts int `json:"skipped_mounts"`
// OutsideDataRootBytes is UsedBytes minus AllocatedBytes: space on the
// same filesystem that is not under the data root. Both are block
// counts of one filesystem, so the difference is meaningful; it is
// approximate (filesystem metadata, reserved blocks) and -1 unless the
// walk was complete.
OutsideDataRootBytes int64 `json:"outside_data_root_bytes"`
Items []DiskItem `json:"items"`
// Overlay2 attributes the directories under overlay2/; nil when the
// data root has none.
Overlay2 *Overlay2Usage `json:"overlay2,omitempty"`
}
DiskUsage is a du-style walk of the data root: allocated blocks, each inode counted once, symbolic links never followed, other filesystems (overlay mounts of running containers, separately mounted volumes) not entered.
type Filesystem ¶ added in v0.3.0
type Filesystem struct {
Path string `json:"path"`
SizeBytes int64 `json:"size_bytes"`
UsedBytes int64 `json:"used_bytes"`
AvailableBytes int64 `json:"available_bytes"`
// DataRoot is the measured allocation under the data root; only with
// --disk, which walks the tree.
DataRoot *DiskUsage `json:"data_root_on_disk,omitempty"`
// ClassicStoreLayers counts the image layers the classic (graph
// driver) store still records while the daemon uses the containerd
// image store. Docker hides them; their bytes are in overlay2/, which
// --disk measures. 0 otherwise.
ClassicStoreLayers int `json:"classic_store_layers"`
}
Filesystem describes the filesystem that holds the data root, from statfs. These are allocated blocks, a different measure from the logical sizes Docker reports; the two are shown side by side, never subtracted.
type ImageItem ¶
type ImageItem struct {
ID string `json:"id"`
Tags []string `json:"tags"`
Bytes int64 `json:"bytes"`
Containers int64 `json:"containers"`
Dangling bool `json:"dangling"`
// UniqueBytes is Size-SharedSize when Containers==0 and both known; -1 otherwise.
UniqueBytes int64 `json:"unique_bytes_if_removed"`
Projects []string `json:"projects,omitempty"`
}
ImageItem is one image with its unique-size rule applied.
type Images ¶
type Images struct {
Count int `json:"count"`
TotalBytes int64 `json:"total_bytes"`
Dangling int `json:"dangling"`
DanglingBytes int64 `json:"dangling_bytes"`
// DanglingUnknown counts dangling images whose unique size is unknown; DanglingBytes is then a lower bound.
DanglingUnknown int `json:"dangling_unknown"`
ReclaimableBytes int64 `json:"reclaimable_bytes"`
Items []ImageItem `json:"items"`
Suggestions []string `json:"suggestions"`
}
Images follows SPEC §6.7.
type LogItem ¶
type LogItem struct {
ContainerID string `json:"container_id"`
Name string `json:"name"`
Project string `json:"project,omitempty"`
Driver string `json:"driver"`
// Rotation is "unbounded", "bounded", "not on disk" or "unknown"
// (inspect failed or the id was rejected).
Rotation string `json:"rotation"`
MaxSize string `json:"max_size,omitempty"`
MaxFile string `json:"max_file,omitempty"`
Bytes int64 `json:"bytes"`
Files int `json:"files"`
// Measured is false when the files could not be read; Bytes is then -1
// and must not be summed.
Measured bool `json:"measured"`
Note string `json:"note,omitempty"`
}
LogItem is one container's log footprint.
type Logs ¶
type Logs struct {
TotalBytes int64 `json:"total_bytes"`
Complete bool `json:"complete"`
Items []LogItem `json:"items"`
Suggestions []string `json:"suggestions"`
}
Logs lists container log files on disk.
type Overlay2Usage ¶ added in v0.4.0
type Overlay2Usage struct {
// LayerDB is false when the layer records could not be read; nothing
// is attributed then and the byte fields are -1.
LayerDB bool `json:"layerdb_read"`
ImageLayers int `json:"image_layers"`
ImageLayerBytes int64 `json:"image_layer_bytes"`
ContainerLayers int `json:"container_layers"`
ContainerLayerBytes int64 `json:"container_layer_bytes"`
Unreferenced int `json:"unreferenced"`
UnreferencedBytes int64 `json:"unreferenced_bytes"`
// LargestUnreferenced are the largest unreferenced directories, at
// most ten, largest first.
LargestUnreferenced []DiskItem `json:"largest_unreferenced"`
// HiddenByContainerdStore is true when the daemon uses the containerd
// image store: then everything in overlay2/ belongs to the classic
// store, whose images and containers Docker hides but keeps on disk.
HiddenByContainerdStore bool `json:"hidden_by_containerd_store"`
// NotExplainedByBuildCacheBytes is UnreferencedBytes minus the build
// cache's private bytes, at least 0: unreferenced space that even
// all private build cache would not account for. Blocks on disk
// against logical sizes, so approximate. -1 when unknown or when the
// containerd image store is in use.
NotExplainedByBuildCacheBytes int64 `json:"not_explained_by_build_cache_bytes"`
// LikelyLeftovers is true when NotExplainedByBuildCacheBytes is at
// least 64 MiB and at least a tenth of overlay2/: more than block
// overhead and timing (a pull or build during the walk) explain.
LikelyLeftovers bool `json:"likely_leftovers"`
}
Overlay2Usage splits overlay2/ by what references each directory, from the graph driver's own records under image/overlay2/layerdb: image layers (sha256/*/cache-id) and container layers (mounts/*/mount-id and init-id). Everything else is unreferenced: BuildKit snapshots that are not part of an image, and directories that no image, container or build cache owns any more (interrupted pulls, builds or removals, crashes). The short-name link directory l/ is not attributed.
type Project ¶
type Project struct {
Name string `json:"name"`
Containers int `json:"containers"`
// ImageBytes counts images used only by this project.
ImageBytes int64 `json:"image_bytes"`
// SharedImageBytes counts images this project uses that other projects use
// too. They are not part of TotalBytes, so project totals stay additive.
VolumeBytes int64 `json:"volume_bytes"`
VolumesUnknown int `json:"volumes_size_unknown"`
LogBytes int64 `json:"log_bytes"`
// LogsUnknown counts containers of this project whose logs could not be
// measured; LogBytes is then a lower bound.
LogsUnknown int `json:"logs_unknown"`
TotalBytes int64 `json:"total_bytes"`
OrphanVolumes int `json:"orphan_volumes"`
DanglingImages int `json:"dangling_images"`
// StoppedOld counts non-running containers created more than 7 days ago
// (the API has no stop time).
StoppedOld int `json:"stopped_containers_created_over_7d"`
}
Project is one compose project (or the "(none)" bucket).
type Projects ¶
type Projects struct {
Items []Project `json:"items"`
TotalBytes int64 `json:"total_bytes"`
// ImageOverlapBytes is how much the image sizes summed here exceed df's
// image row, which counts every layer once: a lower bound for base
// layers shared between different images. Project image columns use
// per-image sizes, so they are not additive by this much. 0 when df's
// image row is not larger or not reported.
ImageOverlapBytes int64 `json:"image_overlap_bytes"`
Suggestions []string `json:"suggestions"`
}
Projects groups resources by compose project. Images used by more than one project appear in each project's SharedImageBytes and are excluded from the project's TotalBytes; the section TotalBytes counts them once: TotalBytes == Σ Items.TotalBytes + SharedImageBytes.
type Report ¶
type Report struct {
SchemaVersion int `json:"schema_version"`
Version string `json:"version"`
TakenAt time.Time `json:"taken_at"`
Daemon Daemon `json:"daemon"`
Summary Summary `json:"summary"`
BuildCache BuildCache `json:"build_cache"`
Logs Logs `json:"logs"`
Projects Projects `json:"projects"`
Images Images `json:"images"`
Volumes Volumes `json:"volumes"`
Desktop *Desktop `json:"desktop,omitempty"`
// Filesystem is the filesystem holding the data root; omitted when the
// data root is not visible from where dockdu runs.
Filesystem *Filesystem `json:"filesystem,omitempty"`
Warnings []string `json:"warnings"`
}
Report is the whole document `dockdu --json` serialises.
type Summary ¶
type Summary struct {
// DfReportedBytes is the sum of the four SIZE columns of `docker system df`.
DfReportedBytes int64 `json:"df_reported_bytes"`
DfImages int64 `json:"df_images_bytes"`
DfContainers int64 `json:"df_containers_bytes"`
DfVolumes int64 `json:"df_volumes_bytes"`
DfBuildCache int64 `json:"df_build_cache_bytes"`
// LogBytes is measured from files and is not part of df.
LogBytes int64 `json:"log_bytes"`
// LogBytesComplete is false when at least one container's logs could not
// be measured; LogBytes is then a lower bound.
LogBytesComplete bool `json:"log_bytes_complete"`
// image and that df counts in both rows; dockdu subtracts them once.
// It is BuildCache.SharedCountedInDfBytes: 0 for daemons whose build
// cache row already leaves shared records out.
BuildCacheSharedBytes int64 `json:"build_cache_shared_bytes"`
// DockerBytesTotal = DfReportedBytes − BuildCacheSharedBytes + LogBytes.
// Shared layers are counted once, as df does: a resource total, not a
// disk-block count.
DockerBytesTotal int64 `json:"docker_bytes_total"`
// VolumeSizesUnknown counts volumes whose size the daemon did not report
// (non-local drivers); df and the total leave them out.
VolumeSizesUnknown int `json:"volume_sizes_unknown"`
// Complete is false when the total is a lower bound: logs not fully
// measured, volume sizes unknown, df's build cache row disagreeing with
// the records, or shared build cache on the containerd image store,
// which may hold its own copy next to the image.
Complete bool `json:"complete"`
// NotShownByDf is the log bytes: the only part df does not report.
NotShownByDf int64 `json:"not_shown_by_df_bytes"`
Suggestions []string `json:"suggestions"`
}
Summary is the headline: what Docker reports, what dockdu measured on top, and the gap between the two.
type VolumeItem ¶
type VolumeItem struct {
Name string `json:"name"`
Driver string `json:"driver"`
Project string `json:"project,omitempty"`
Bytes int64 `json:"bytes"`
RefCount int64 `json:"ref_count"`
// Reference is "referenced", "unreferenced" or "unknown".
Reference string `json:"reference"`
Orphan bool `json:"orphan"`
// BuildxNode is set when the volume is the state volume of a buildx
// docker-container builder node: it holds that builder's build cache.
BuildxNode string `json:"buildx_node,omitempty"`
// Anonymous is true for a volume Docker created without a name (an
// image VOLUME or `-v /path`), labelled com.docker.volume.anonymous.
// `docker rm` without -v leaves such volumes behind.
Anonymous bool `json:"anonymous"`
}
VolumeItem is one volume.