Configure Docker log rotation with a Docker logging driver: Docker journald logging and Docker local file driver

Level: Expert
Estimated time: ~20 minutes
Goal: Configure Docker log rotation to ensure zero-downtime log management and prevent disk space exhaustion.

Introduction

Unmanaged Docker logs can rapidly exhaust server storage. By default, the Docker daemon writes logs using the json-file format without size limits. To maintain reliable infrastructure, you must configure Docker log rotation utilizing a scalable Docker logging driver. This guide details how to implement Docker log rotation globally using either Docker journald logging or the Docker local file driver. Choosing the correct configuration ensures efficient log management and system stability.

Terminology

Before proceeding, familiarize yourself with these core concepts:

• Docker: A platform for running applications in isolated environments called Containers.
• Docker logs: The output streams captured from a container's Stdout (standard output) and Stderr (standard error).
• Log rotation: The practice of archiving and purging old logs to reclaim space.
• Logging driver: The mechanism Docker uses to capture, format, and route logs.
• Journald: The systemd logging service, ideal for centralized host logging.
• Local file driver: A high-performance, built-in driver optimized for local storage.
• Json-file: The default driver that writes logs as JSON arrays.
• Docker daemon: The background service managing Docker operations.
• Daemon.json: The configuration file for the daemon.
• Log driver configuration: The global or per-container logging setup.
• Log options: Specific parameters passed to the driver.
• Max-size: The threshold size before a log file rotates.
• Max-file: The maximum number of rotated files retained.

Prerequisites

Before you begin, ensure you have:

• Operating system: Ubuntu 22.04 / 24.04 LTS, Debian 12 / 13, RHEL 9 / 10, AlmaLinux 9 / 10, Rocky Linux 9 / 10
• Docker: version 24.x or later installed
• Access: sudo privileges
• Required knowledge: Linux administration and Infrastructure as Code concepts

Step 1: Understanding Docker json-file vs local drivers

When evaluating Docker json-file vs local drivers, performance and overhead dictate the choice. The default json-file driver is simple but consumes more CPU and disk space due to JSON formatting. In contrast, the local file driver is an append-only binary format optimized specifically for rotation efficiency. In normal production workloads, using the Docker local file driver reduces disk overhead and reliably enforces rotation natively.

To check your current driver, run:

docker info --format '{{.LoggingDriver}}'

Expected output:

json-file

If you see json-file, proceed to modify the daemon.json Docker logging configuration.

Step 2: Configure Docker log rotation with the Docker local file driver

To enforce global limits across all containers, you will edit the /etc/docker/daemon.json file. This is the recommended approach for daemon.json Docker logging.

Open the configuration file:

If /etc/docker/daemon.json does not exist on your system, nano will create it on save. This is normal - Docker uses built-in defaults when the file is absent.

sudo nano /etc/docker/daemon.json

Add the following log driver configuration:

{
  "log-driver": "local",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

Save and close the file. The new settings are written to disk. This configuration applies the driver globally. The log options instruct Docker to rotate logs when they reach 50 megabytes (max-size Docker logs) and retain a maximum of 3 files (max-file Docker logs). Note that the local driver still natively supports these explicit size and file constraints, unlike journald.

Restart the Docker daemon to apply changes. The docker.service handles containers, so restarting it applies the limits:

sudo systemctl restart docker

You will lose a few seconds of connectivity to the daemon. Once restarted, all newly created containers will use the Docker local file driver and inherit these max-size Docker logs and max-file Docker logs limits.

Additionally, understand the precedence order for logging configurations:

1. CLI flags (docker run --log-driver) override everything.
2. docker-compose.yml logging overrides operate per-service at container creation time.
3. daemon.json acts as a default global fallback for all non-explicit containers.

Step 3: Enable Docker journald logging as your Docker logging driver

Alternatively, you can route logs directly to the system's journald daemon. Docker journald logging integrates seamlessly with systemctl and external log forwarders.

Open the configuration file:

sudo nano /etc/docker/daemon.json

Replace the contents with the journald configuration. Completely replace the file contents - remove any previous log-opts entries, as journald does not support max-size or max-file options:

{
  "log-driver": "journald"
}

Save and close the file. The configuration is updated.

Restart the service. The docker.service must be reloaded to shift log management to journald:

sudo systemctl restart docker

When using Docker logs journald, the journald driver removes Docker-side rotation control. Log rotation still exists, but it is handled entirely outside Docker by the systemd journal. You will see logs routing directly to the systemd journal. These logs are indexed by container metadata fields rather than being tied to the docker.service unit.

Operationally, journald manages these logs using concrete limits configured in /etc/systemd/journald.conf, specifically SystemMaxUse, RuntimeMaxUse, and MaxRetentionSec. This carries a significant blast radius risk: journald exhaustion can affect ssh logging, kernel logs, audit logs, and all other services sharing the journal in production. Note that max-size and max-file options only apply to json-file and local drivers, not journald.

To apply changes to journald configuration:

sudo systemctl restart systemd-journald
# Or to trigger immediate rotation without a full restart:
sudo systemctl kill -s SIGUSR2 systemd-journald

Step 4: Managing journalctl output

When you configure Docker log rotation via journald, you interact with logs using journalctl instead of docker logs. The journald service processes these logs centrally.

To view logs for a specific container using Docker logs journald, run:

journalctl CONTAINER_NAME=<YOUR_CONTAINER_NAME> -o cat

Expected output:

Application started successfully

Step 5: Verification

To verify the Docker logging driver configuration on a running container, launch a test container:

docker run -d --name log-test nginx:latest

Inspect the container's log options:

docker inspect -f '{{.HostConfig.LogConfig.Type}}' log-test

Expected output for the local driver:

local

If you configured journald, the output will be journald instead.

Check the applied parameters for the local driver:

docker inspect -f '{{.HostConfig.LogConfig.Config}}' log-test

Expected output:

map[max-file:3 max-size:50m]

This confirms that your daemon.json Docker logging setup successfully applied the max-size Docker logs and max-file Docker logs parameters. Note that journald does not expose max-size or max-file options here, as rotation is deferred to the OS.

Use this command to identify any pre-existing containers still using the previous driver. The logging driver is fixed at container creation - these containers must be recreated (e.g., docker compose up -d --force-recreate) to inherit the new configuration:

docker ps -aq | xargs -r docker inspect -f '{{.Name}}: {{.HostConfig.LogConfig.Type}}'

Reverting changes

To revert the global log driver configuration back to the default format, remove the configuration from daemon.json.

Remove the file (always back up configuration files before modifying) and restart the Docker service:

sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date +%F)
sudo rm /etc/docker/daemon.json
sudo systemctl restart docker

Troubleshooting

• journalctl returns no output for CONTAINER_ID: The Docker journald driver writes the short 12-character ID to CONTAINER_ID, while docker inspect returns the full 64-character ID. Use CONTAINER_NAME or CONTAINER_ID_FULL instead.
• Existing containers still use json-file after restart: The docker update command does not change the logging driver. You must recreate the container (e.g., via docker compose down and up) to apply the new logging driver.
• max-size and max-file have no effect with journald: Log rotation for journald is managed globally via /etc/systemd/journald.conf (e.g., SystemMaxUse), not through Docker's log-opts.

Conclusion

Properly managing container output is a fundamental part of reliable infrastructure. By correctly choosing between Docker json-file vs local drivers, you prevent storage issues. Whether you configure Docker log rotation using the lightweight Docker local file driver or integrate natively via Docker journald logging, your environment is now equipped to handle massive log streams safely. Implementing these Docker log rotation practices ensures that your Docker logging driver configuration remains stable and your host resources predictable.

Document Version: 1.0
Last Updated: May 2026
Owner: Technical Documentation Team