# Container blocked on stdout: Docker log backpressure and rotation

Diagnose container blocked on stdout: Docker log backpressure and rotation. Evidence to collect, a worked operational example and recovery checks.

Author: Retrivium team
Updated: 2026-11-01
Canonical URL: https://retrivium.ai/journal/docker-log-rotation-application-blocking/
Language: en

Writing to stdout can delay an application when a blocking logging driver cannot keep up. Docker exposes separate controls for delivery and rotation. They address different concerns: backpressure on the process and the volume of retained log data.

## Inspect the effective logging driver

Read the running container's LogConfig through inspect. A daemon's default driver describes newly created containers, not necessarily the existing instance. Preserve the driver, mode, buffer and rotation settings. Establish whether the application writes to stdout/stderr or maintains its own files. Docker logging configuration does not automatically manage those application files. For synchronous logging, the waiting point may be inside the diagnostic write operation itself.


[Official reference 1](https://docs.docker.com/engine/logging/configure/).

## Distinguish blocking from message loss

Blocking delivery can apply backpressure to the writer. Non-blocking delivery uses an intermediate buffer; new messages are dropped when that buffer is full. This is an explicit tradeoff rather than a free performance improvement. max-buffer-size governs delivery buffering, whereas json-file max-size and max-file govern storage and rotation. Combining these settings into one “log size” hides their different application points and overflow consequences.


[Official reference 2](https://docs.docker.com/engine/logging/drivers/json-file/).

## Reproduce the stream separately

In a test environment, compare the same work with ordinary logging and with a diagnostic burst. Record operation duration, generated line count, destination availability and delivery mode. Repeat with a bounded non-blocking buffer and inspect missing messages. Use synthetic numbered records rather than secrets or customer request contents. The logging transport can be tested without bringing production data into the exercise.

| Property under test | Observable evidence |
| --- | --- |
| Backpressure | Process pauses coincide with delivery difficulty |
| Message loss | The receiver's numbered sequence contains gaps |
| Rotation | Files follow the declared rotation policy |
| Updated configuration | A new container's inspect output shows the options |

## Configure the channel for its purpose

Reduce noisy events and choose an acceptable response when the destination is unavailable. For json-file, set documented rotation options and respect the string format required in daemon options. Do not manually edit Docker-managed log files, which can interfere with the driver. Carry changed daemon defaults through to declarative container recreation during an agreed maintenance window. Separately decide which operational events need durable external storage for later investigation.

## Verify both outcomes

Recovery requires acceptable application progress and a known degree of diagnostic completeness. Repeat the original burst and compare retained file volume and gaps in numbered records. Keep driver options with the collection rules. If non-blocking delivery removes stalls but loses required events, continue designing the channel rather than declaring complete recovery. Downstream backend failures, local driver limitations and application-owned file logging should remain distinguishable in the incident record. That distinction determines which component needs capacity or configuration changes when the problem returns.

Keep numbering and emission rate identical. Otherwise lower latency may reflect a smaller input stream rather than changed delivery mode, leaving the configuration conclusion unsupported.

Related operational reading: [gpu monitoring scorecard](/journal/gpu-monitoring-scorecard/); [gpu maintenance change register](/journal/gpu-maintenance-change-register/).