How to use docker buildx history logs command to view build logs

Introduction

In this lab, you will learn how to use the docker buildx history logs command to view the logs of your Docker builds. You will start by building a Docker image and examining its history to understand the build process and identify the build reference.

You will then use the build reference to retrieve and view the detailed logs of a specific build. Finally, you will explore how to view these build logs with different progress output types, providing insights into the build execution and troubleshooting potential issues.

Skills Graph

Build an image and view its history

In this step, you will learn how to build a Docker image from a Dockerfile and view its history. The history shows the layers that make up the image and the commands used to create each layer.

First, let's create a simple Dockerfile in your ~/project directory. This Dockerfile will create an image based on the ubuntu image and install the curl package.

cd ~/project
nano Dockerfile

Add the following content to the Dockerfile:

FROM ubuntu:latest
RUN apt-get update && apt-get install -y curl

Save the file and exit the editor (Ctrl+X, Y, Enter).

Now, let's build the Docker image using the docker build command. We will tag the image with the name my-ubuntu-curl and the tag latest. The . at the end of the command indicates that the Dockerfile is in the current directory.

docker build -t my-ubuntu-curl:latest .

You will see output indicating the build process, showing each step defined in the Dockerfile being executed.

After the build is complete, you can view the history of the image using the docker history command.

docker history my-ubuntu-curl:latest

The output will show a table with information about each layer, including the layer ID, creation time, size, and the command used to create it. This history is useful for understanding how an image was built and for debugging purposes.

Find the build reference from history

In the previous step, you built a Docker image and viewed its history. The history output includes a "BUILD REFERENCE" column. This reference is a unique identifier for the build process that created the image. It's different from the image ID and is specifically related to the build itself, not the resulting image layers.

Let's look at the history again to identify the build reference.

docker history my-ubuntu-curl:latest

In the output, look for the line corresponding to the build process. It will typically be the first line (excluding the base image layers) and will have a value in the "BUILD REFERENCE" column. This value is a long string of characters.

For example, the output might look something like this (the exact values will differ):

IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT   BUILD REFERENCE
a1b2c3d4e5f6   2 hours ago    /bin/sh -c #(nop)  CMD ["/bin/bash"]            0B
g7h8i9j0k1l2   2 hours ago    /bin/sh -c #(nop) ADD file:abcdef1234567890...   73.9MB
m3n4o5p6q7r8   2 hours ago    /bin/sh -c apt-get update && apt-get install...   30MB      buildkit.dockerfile.v0   buildkit:abcdef1234567890abcdef1234567890

In this example, the build reference is buildkit:abcdef1234567890abcdef1234567890. Note that the build reference often starts with buildkit: followed by a unique identifier.

You will need this build reference in the next step to view the logs of the specific build process. Copy the build reference from your output.

View the logs of a specific build using its reference

In the previous step, you identified the build reference from the image history. This build reference allows you to view the detailed logs of that specific build process. This is particularly useful for debugging build failures or understanding the exact output generated during the build.

To view the logs of a specific build, you use the docker buildx logs command followed by the build reference. Remember to replace YOUR_BUILD_REFERENCE with the actual build reference you found in the previous step.

docker buildx logs YOUR_BUILD_REFERENCE

For example, if your build reference was buildkit:abcdef1234567890abcdef1234567890, the command would be:

docker buildx logs buildkit:abcdef1234567890abcdef1234567890

Executing this command will display the complete output from the build process, including the output from each RUN instruction in your Dockerfile. You will see the output of apt-get update and apt-get install -y curl as they were executed during the image build.

This provides a much more detailed view of the build process compared to the summary shown during the docker build command.

View logs with different progress output types

In this step, you will explore different ways to view the build progress output when building a Docker image. The docker build command provides various options to control how the build progress is displayed.

By default, docker build uses a progress output that shows the status of each step as it's being executed. Let's rebuild the image to see this default output again.

docker build -t my-ubuntu-curl:latest .

You will observe the familiar output showing steps like "Step 1/2", "Step 2/2", and the output from the RUN command.

Now, let's try a different progress output type using the --progress flag. The plain output type displays the build process in a more verbose, line-by-line format, which can be helpful for seeing the exact commands being run and their output without the progress bar.

docker build --progress=plain -t my-ubuntu-curl:latest .

Compare the output of this command with the default output. You will see a more detailed log of each action taken during the build.

Another useful progress output type is tty. This is the default when building interactively in a terminal and provides a dynamic progress bar. However, explicitly specifying it can be useful in certain scripting scenarios.

docker build --progress=tty -t my-ubuntu-curl:latest .

You should see the interactive progress bar again, similar to the initial build.

Understanding these different progress output types allows you to choose the best way to monitor your Docker builds, whether you need a concise summary or detailed logs for debugging.

Summary

In this lab, you learned how to build a Docker image from a Dockerfile and view its history using the docker build and docker history commands. You created a simple Dockerfile, built an image tagged my-ubuntu-curl:latest, and examined the history output to understand the layers and commands involved in the build process.

You then learned how to identify the unique build reference from the docker history output. This build reference is crucial for accessing specific build-related information, such as the build logs, which you will explore in subsequent steps.