Configurare la rotazione dei log di Docker con un logging driver: logging di Docker con journald e driver di file local

Livello: Esperto
Tempo stimato: ~20 minuti
Obiettivo: Configurare la rotazione dei log di Docker per garantire una gestione dei log senza downtime e prevenire l'esaurimento dello spazio su disco.

Introduzione

I log di Docker non gestiti possono esaurire rapidamente lo spazio di archiviazione del server. Per impostazione predefinita, il demone Docker scrive i log nel formato json-file senza limiti di dimensione. Per mantenere un'infrastruttura affidabile, è necessario configurare la rotazione dei log di Docker utilizzando un driver di logging di Docker scalabile. Questa guida descrive come implementare la rotazione dei log di Docker a livello globale, usando il logging di Docker tramite journald oppure il driver di file locale (local) di Docker. Scegliere la configurazione corretta garantisce una gestione efficiente dei log e la stabilità del sistema.

Terminologia

Prima di procedere, familiarizzate con i seguenti concetti fondamentali:

• Docker: una piattaforma per eseguire applicazioni in ambienti isolati chiamati container.
• Log di Docker: i flussi di output catturati da Stdout (standard output) e Stderr (standard error) di un container.
• Rotazione dei log: la pratica di archiviare ed eliminare i log vecchi per recuperare spazio.
• Driver di logging (logging driver): il meccanismo che Docker utilizza per catturare, formattare e instradare i log.
• Journald: il servizio di logging di systemd, ideale per il logging centralizzato dell'host.
• Driver di file locale (local): un driver integrato ad alte prestazioni, ottimizzato per lo storage locale.
• Json-file: il driver predefinito, che scrive i log in formato JSON.
• Demone Docker: il servizio in background che gestisce le operazioni di Docker.
• Daemon.json: il file di configurazione del demone.
• Configurazione del driver di log: l'impostazione del logging a livello globale o per singolo container.
• Opzioni di log: parametri specifici passati al driver.
• Max-size: la dimensione soglia oltre la quale un file di log viene ruotato.
• Max-file: il numero massimo di file ruotati conservati.

Prerequisiti

Prima di iniziare, assicuratevi di avere:

• Sistema operativo: Ubuntu 22.04 / 24.04 LTS, Debian 12 / 13, RHEL 9 / 10, AlmaLinux 9 / 10, Rocky Linux 9 / 10
• Docker: versione 24.x o successiva installata
• Accesso: privilegi sudo
• Conoscenze richieste: amministrazione di Linux e concetti di Infrastructure as Code

Passaggio 1: Comprendere le differenze tra i driver json-file e local di Docker

Nel valutare i driver json-file e local di Docker, la scelta dipende da prestazioni e overhead. Il driver predefinito json-file è semplice, ma consuma più CPU e spazio su disco a causa della formattazione JSON. Il driver di file local, invece, usa un formato binario append-only ottimizzato specificamente per l'efficienza della rotazione. Nei normali carichi di lavoro di produzione, il driver di file locale (local) di Docker riduce l'overhead su disco e applica la rotazione in modo nativo e affidabile.

Per verificare il driver attualmente in uso, eseguite:

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

Output previsto:

json-file

Se vedete json-file, procedete con la modifica della configurazione del logging di Docker in daemon.json.

Passaggio 2: Configurare la rotazione dei log di Docker con il driver di file locale (local)

Per applicare limiti globali a tutti i container, modificherete il file /etc/docker/daemon.json. Questo è l'approccio consigliato per la configurazione del logging di Docker in daemon.json.

Aprite il file di configurazione:

Se /etc/docker/daemon.json non esiste sul vostro sistema, nano lo creerà al salvataggio. È normale: Docker usa i valori predefiniti integrati quando il file è assente.

sudo nano /etc/docker/daemon.json

Aggiungete la seguente configurazione del driver di log:

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

Salvate e chiudete il file. Le nuove impostazioni vengono scritte su disco. Questa configurazione applica il driver a livello globale. Le opzioni di log indicano a Docker di ruotare i log quando raggiungono i 50 megabyte (max-size per i log di Docker) e di conservare al massimo 3 file (max-file per i log di Docker). Si noti che il driver local supporta ancora in modo nativo questi vincoli espliciti di dimensione e numero di file, a differenza di journald.

Riavviate il demone Docker per applicare le modifiche. Il servizio docker.service gestisce i container, quindi il suo riavvio rende effettivi i limiti:

sudo systemctl restart docker

Perderete la connettività con il demone per alcuni secondi. Dopo il riavvio, tutti i container creati successivamente useranno il driver di file locale (local) di Docker ed erediteranno questi limiti di max-size e max-file per i log di Docker.

Inoltre, tenete presente l'ordine di precedenza delle configurazioni di logging:

1. I flag della CLI (docker run --log-driver) hanno la precedenza su tutto.
2. Gli override di logging in docker-compose.yml operano per singolo servizio al momento della creazione del container.
3. daemon.json funge da valore predefinito globale per tutti i container senza impostazioni esplicite.

Passaggio 3: Abilitare il logging di Docker tramite journald come driver di logging di Docker

In alternativa, è possibile instradare i log direttamente al demone journald del sistema. Il logging di Docker tramite journald si integra perfettamente con systemctl e con i forwarder di log esterni.

Aprite il file di configurazione:

sudo nano /etc/docker/daemon.json

Sostituite il contenuto con la configurazione di journald. Sostituite completamente il contenuto del file e rimuovete ogni precedente voce log-opts, poiché journald non supporta le opzioni max-size e max-file:

{
  "log-driver": "journald"
}

Salvate e chiudete il file. La configurazione è aggiornata.

Riavviate il servizio. È necessario ricaricare docker.service per spostare la gestione dei log su journald:

sudo systemctl restart docker

Quando si usano i log di Docker con journald, il driver journald elimina il controllo della rotazione lato Docker. La rotazione dei log continua a esistere, ma è gestita interamente al di fuori di Docker dal journal di systemd. I log vengono instradati direttamente al journal di systemd e sono indicizzati tramite i campi di metadati del container, anziché essere legati all'unit docker.service.

Dal punto di vista operativo, journald gestisce questi log con limiti concreti configurati in /etc/systemd/journald.conf, in particolare SystemMaxUse, RuntimeMaxUse e MaxRetentionSec. Ciò comporta un rischio significativo in termini di raggio d'impatto (blast radius): in produzione, l'esaurimento di journald può compromettere il logging di ssh, i log del kernel, i log di audit e tutti gli altri servizi che condividono il journal. Si noti che le opzioni max-size e max-file si applicano solo ai driver json-file e local, non a journald.

Per applicare le modifiche alla configurazione di journald:

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

Passaggio 4: Gestire l'output di journalctl

Quando configurate la rotazione dei log di Docker tramite journald, interagite con i log usando journalctl anziché docker logs. Il servizio journald elabora questi log in modo centralizzato.

Per visualizzare i log di un container specifico con i log di Docker in journald, eseguite:

journalctl CONTAINER_NAME=<YOUR_CONTAINER_NAME> -o cat

Output previsto:

Application started successfully

Passaggio 5: Verifica

Per verificare la configurazione del driver di logging di Docker su un container in esecuzione, avviate un container di test:

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

Ispezionate le opzioni di log del container:

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

Output previsto per il driver local:

local

Se avete configurato journald, l'output sarà invece journald.

Controllate i parametri applicati per il driver local:

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

Output previsto:

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

Questo conferma che la vostra configurazione del logging di Docker in daemon.json ha applicato correttamente i parametri max-size e max-file per i log di Docker. Si noti che journald non espone qui le opzioni max-size e max-file, poiché la rotazione è demandata al sistema operativo.

Usate questo comando per individuare i container preesistenti che utilizzano ancora il driver precedente. Il driver di logging è fissato alla creazione del container: questi container devono essere ricreati (ad esempio con docker compose up -d --force-recreate) per ereditare la nuova configurazione:

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

Ripristino delle modifiche

Per riportare la configurazione globale del driver di log al formato predefinito, rimuovete la configurazione da daemon.json.

Rimuovete il file (eseguite sempre un backup dei file di configurazione prima di modificarli) e riavviate il servizio Docker:

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

Risoluzione dei problemi

• journalctl non restituisce alcun output per CONTAINER_ID: il driver journald di Docker scrive in CONTAINER_ID l'ID breve di 12 caratteri, mentre docker inspect restituisce l'ID completo di 64 caratteri. Usate invece CONTAINER_NAME o CONTAINER_ID_FULL.
• I container esistenti usano ancora json-file dopo il riavvio: il comando docker update non modifica il driver di logging. È necessario ricreare il container (ad esempio con docker compose down e poi up) per applicare il nuovo driver di logging.
• max-size e max-file non hanno effetto con journald: la rotazione dei log per journald è gestita globalmente tramite /etc/systemd/journald.conf (ad esempio SystemMaxUse), non attraverso le log-opts di Docker.

Conclusione

Gestire correttamente l'output dei container è una parte fondamentale di un'infrastruttura affidabile. Scegliendo correttamente tra i driver json-file e local di Docker, evitate problemi di spazio. Sia che configuriate la rotazione dei log di Docker con il leggero driver di file locale (local) di Docker, sia che vi integriate in modo nativo tramite il logging di Docker con journald, il vostro ambiente è ora pronto a gestire in sicurezza grandi flussi di log. L'adozione di queste pratiche di rotazione dei log di Docker garantisce che la configurazione del vostro driver di logging di Docker resti stabile e che le risorse dell'host siano prevedibili.

Versione del documento: 1.0
Ultimo aggiornamento: maggio 2026
Responsabile: Team di documentazione tecnica