How crashwind/docker_df works
This repository is a small, single-purpose Python CLI tool for reporting Docker disk usage. There is no multi-service architecture here: the whole project centers on one executable script, docker_df.py, plus dependency declaration in requirements.txt.
The main responsibility is to interrogate the local Docker environment and compute storage-related metrics for three Docker object types: containers, images, and layers. The script appears to support both aggregated totals and per-container queries.
The command-line interface is the primary boundary. Different flags switch the tool into distinct modes:
• discovery mode for Zabbix-style low-level discovery output,
• summed size mode for containers,
• summed size mode for layers,
• summed size mode for images,
• and a single-container lookup by name.
A key output path is Zabbix integration. In discovery mode, the tool emits JSON shaped for Zabbix discovery, specifically a data array containing {#DOCKER_CONTAINER} macros. That makes the script suitable as an external check or item source in a monitoring pipeline.
The data flow is straightforward: Docker metadata is collected locally, the script performs size aggregation or filtering, and the result is written to stdout as either a raw integer byte count or discovery JSON. There is no evidence of a database, message queue, or network service layer inside the repo.
The repository’s architectural boundary is therefore the Docker host itself. The tool depends on access to the local Docker daemon or Docker metadata available on the machine where it runs. In practice, this means the environment, not an internal subsystem, is the main dependency.
The project likely relies on Python packaging and external libraries declared in requirements.txt, but the repo structure shows no additional modules, plugins, or internal package hierarchy. That suggests the implementation is intentionally flat and operationally simple.
Operationally, the script is best viewed as a monitoring utility rather than an application. It is designed to be invoked directly from the shell or by an observability system, with no long-running process state.
For an architecture diagram, the important boxes are:
• Operator or monitoring system invoking the script,
• docker_df.py as the computation layer,
• local Docker daemon/host filesystem metadata as the data source,
• stdout as the output channel,
• and Zabbix as one consuming integration for discovery output.
Overall, this repo is a thin adapter between Docker storage metadata and monitoring-friendly output formats.
Main entry points: docker_df.py CLI router
Components 9
External actors
People and systems that invoke or consume the CLI
- Operator · Shell user, cron job, or monitoring runner invoking the tool
- Docker host · Local Docker daemon and host metadata the script depends on
CLI tool
The single script that performs all computation
- docker_df.py · Single entrypoint for Docker disk-usage reporting
docker_df.py - CLI router · Selects discovery, totals, or per-container lookup modes
docker_df.py - Docker collector · Reads local Docker objects and their size metadata
docker_df.py - Aggregator · Computes summed container, image, or layer sizes and single-container values
docker_df.py - Discovery formatter · Emits Zabbix-style discovery payloads with {#DOCKER_CONTAINER} entries
docker_df.py
Outputs
Result channels and downstream consumers
- Zabbix · Consumes discovery JSON for low-level discovery
- Stdout · Primary output channel for byte counts or discovery JSON
Connections 10
- Operator → docker_df.py: invokes · Runs the script directly from the shell or scheduler
- docker_df.py → CLI router: parses · Reads flags and selects the execution mode
- CLI router → Docker collector: loads data · Requests container, image, or layer metadata as needed
- Docker collector → Docker host: queries · Depends on local Docker access for object metadata
- CLI router → Aggregator: routes totals · Sends non-discovery modes to size computation
- Aggregator → Stdout: writes count · Outputs raw byte totals or per-container size results
- CLI router → Discovery formatter: routes discovery · Sends discovery mode to Zabbix payload generation
- Discovery formatter → Stdout: writes json · Emits discovery JSON to standard output
- Discovery formatter → Zabbix: feeds · Provides low-level discovery data to Zabbix
- docker_df.py → Stdout: prints · All modes terminate by writing to stdout