report

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
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.

View Source
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

func Bytes(n int64) string

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

func ShellQuote(s string) string

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

func SuggestBuildxPrune(builder string) string

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

func SuggestVolumeRm(name string) string

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.

func WriteJSON

func WriteJSON(w io.Writer, r *Report) error

WriteJSON renders the report as indented JSON. Lists serialise as [] and never as null so consumers can iterate without nil checks.

func WriteText

func WriteText(w io.Writer, r *Report, top int) error

WriteText renders the human-readable report (SPEC §7). top limits the rows of each list; 0 means all. Nothing here is coloured.

Types

type BuildCache

type BuildCache struct {
	Records          int   `json:"records"`
	TotalBytes       int64 `json:"total_bytes"`
	SharedBytes      int64 `json:"shared_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"`
	// SharedCountedInDfBytes is the part of SharedBytes that df's build
	// 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"`
	// DfRowExcludesShared is true when df's row follows the pre-1.52 rule
	// (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"`
	// SharedMayBeFreedByPrune is true on the containerd image store, where a
	// 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"`
	SharedBytes int64    `json:"shared_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.
	SharedImageBytes int64 `json:"shared_image_bytes"`
	ImagesShared     int   `json:"images_shared_with_other_projects"`
	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"`
	SharedImageBytes int64     `json:"shared_image_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"`
	// BuildCacheSharedBytes are build-cache bytes that also belong to an
	// 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.

type Volumes

type Volumes struct {
	Count        int          `json:"count"`
	TotalBytes   int64        `json:"total_bytes"`
	UnknownSizes int          `json:"unknown_sizes"`
	Items        []VolumeItem `json:"items"`
	Suggestions  []string     `json:"suggestions"`
}

Volumes follows SPEC §6.8.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL