Comprehensive Guide to Viewing Docker Image Build Logs: From Basic Commands to Advanced Techniques

Core Challenges in Viewing Docker Image Build Logs

Within the Docker ecosystem, container log viewing is relatively straightforward, but accessing logs during image builds is often overlooked. The output of commands executed during image construction (such as npm install) is crucial for debugging and monitoring, yet Docker's default build output is typically simplified, making detailed analysis difficult.

Revolutionary Improvements with BuildKit

With the introduction of BuildKit, the Docker build system has seen significant enhancements. The --progress=plain option has become a key tool for viewing complete build output. This option forces Docker to display all build step outputs in raw format, including the full standard output and standard error streams of each RUN command.

Basic usage example:

docker build -t my-image --progress=plain .

To ensure completely uncached build logs, combine with the --no-cache option:

docker build --no-cache --progress=plain -t my-image .

BuildKit also provides other progress output options: auto (default, intelligent display), tty (suitable for interactive terminals), and plain (raw output).

Log Strategies for Traditional Build Methods

For environments without BuildKit enabled, it can be temporarily disabled via an environment variable:

DOCKER_BUILDKIT=0 docker build -t my-image .

In traditional builds, if --rm=true is not used during construction, all intermediate containers are preserved. Logs from these containers can be viewed using the docker logs command:

docker logs $container_id

Another effective method is redirecting build output to an external file:

docker build -t my-image . | tee my-image.build.log

This approach displays the complete build process output in the terminal while simultaneously saving it to a file for later analysis.

Practical Methods for Embedding Logs in Images

While it is generally recommended to keep logs outside images to reduce size, certain scenarios require embedding build logs within the image. This can be achieved using the tee command:

RUN my-install-cmd | tee /logs/my-install-cmd.log

After building, embedded logs can be viewed through temporary containers:

docker run --rm my-image cat /logs/my-install-cmd.log

Note that this method increases layer size, and log files permanently reside within the image.

Auxiliary Tools and Best Practices

The docker history command, while not showing command output, provides build history of image layers:

docker history my-image

This is valuable for understanding image composition, identifying cache usage, and debugging build issues. Each layer displays the command that created it, helping developers trace the build process.

In practical development, it is advisable to choose appropriate log viewing strategies based on specific needs: use --progress=plain for detailed output during development debugging; consider outputting logs to external file systems for production builds; and utilize docker history for audit trails when analyzing build history.

BuildKit's concurrent build features may affect log output order, which should be noted when using --progress=plain. Additionally, for security and image optimization, sensitive information should not be leaked through build logs.