How do the json-file driver's max-size and max-file log options stop a Docker host filling with logs?

## The failure this prevents A fleet of geospatial tile servers — Django behind gunicorn — ran with the engine defaults and an access log on every tile request. Seventeen containers on one host, several weeks uptime, and `/var/lib/docker` sat at 41 GB with individual `-json.log` files past 3 GB. Nothing had misbehaved: json-file did exactly what it is configured to do out of the box, which is to append forever. That is the whole point of `max-size` and `max-file`. They are not an optimisation; they are the only thing standing between a chatty container and a full disk. ## How rotation works Rotation is performed by the driver inside `dockerd`, not by the host's `logrotate`. When the active file reaches `max-size`, the driver renames it with a numeric suffix, shifts the older ones along, starts a fresh active file, and deletes anything beyond `max-file`. The steady-state footprint of one container is therefore bounded at about `max-size × max-file`. Two behaviours surprise people: - **`max-file` alone does nothing.** With no `max-size` there is never a rotation event, so there is never a second file to count. The pair must be set together. - **The bound is per container, not per host.** `max-size=10m, max-file=3` means 30 MB *each*. On the tile-server host that is still 510 MB of logs, which is fine — but the arithmetic is yours to do. Sizing is a host-level budget: number of containers × the per-container bound, with headroom for the images and writable layers sharing the same filesystem. ## Defaults, and the driver that has sane ones The **json-file** driver defaults to an unlimited size, a single file, and no compression. The **local** driver was added precisely to fix this: it rotates at **20 MB** across **5** files and compresses the rotated ones by default, and stores the same information in a more compact binary format instead of escaped JSON. If your only requirement is "logs on the host, bounded, readable with `docker logs`", `local` is the better default and needs no options at all. Compression is available on json-file too (`compress`, off by default). It is a real saving on text logs, at the cost of CPU when rotating and a decompression step when the file is read back. ## Configuring it Daemon-wide, in `/etc/docker/daemon.json`: ```json { "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3", "compress": "true" } } ``` Per container, when one workload needs a different budget: ``` docker run -d --log-opt max-size=64m --log-opt max-file=4 tileserv:2.4 ``` The timing rule matters more here than anywhere else: **the log configuration is resolved when the container is created**, so editing `daemon.json` and restarting the engine leaves every existing container exactly as unbounded as it was. On a host that is already in trouble, the fix is to recreate the containers with the new options — the new settings do not retroactively trim files that have already been written. ## What rotation is not Rotation is a *disk safety valve*, not a retention policy. With `10m × 3` and a busy access log at a few hundred lines a second, the oldest surviving line may be twenty minutes old — which is worse than useless during a post-incident review the next morning. If logs matter beyond the immediate present they have to leave the host, either by a collector reading these files or by a shipping driver; rotation then only has to survive the collector being briefly behind. Rotation also does not apply to every driver. With **journald**, size and retention are the journal's business and are configured in systemd, not with `max-size`. With a shipping driver such as fluentd or awslogs, nothing accumulates on the host in the first place — retention belongs to whatever receives the messages. A final operational note: these files are held open by the daemon, so deleting the active log file out from under a running container does not behave the way you would hope, and reclaiming space that has already been consumed is a separate exercise from bounding future growth. The durable fix is always the bound, applied to every container that gets created. ## Making the bound hold Because the setting is inherited from the daemon default at creation time, the reliable place to enforce it is `daemon.json` on every host, not the run command each team writes. A bound that has to be remembered will be forgotten by exactly the service that needs it, and the omission is invisible until the disk is full. Two things are worth checking periodically on a host you care about: that each running container's effective log configuration really carries a limit, and that the total the fleet is entitled to still fits the filesystem holding Docker's data root, which also carries images, writable layers and volumes. Rotation protects you from a chatty container; it does not protect you from having promised more bytes than the disk has.