Overview

This guide aims to provide some first steps in debugging Docker Layer Cache (DLC) misses within CircleCI builds. Please note that this guide is for builds on CircleCI Cloud (circleci.com), not CircleCI Server installations.

Preface

Typically, we are trying to compare two builds from the same project.
Let us call them build A and build B, where the following is true:

• build A ran before build B.
• both build A and B are creating an image from the same, unchanged Dockerfile.
• we are expecting build B to leverage some, if not all, cached layers from build A.

If the Dockerfile has been modified, this can cause the cache to bust, and result in cache misses.
Please refer to Docker documentation on the best practices for writing a Dockerfile.

Step 1: Confirm DLC is enabled

Make sure that you have enabled DLC on your build indeed.
Depending on your job's executor, you should have enabled DLC on either the Remote Docker (for Docker executor) or the Machine image definition itself (for Machine executor).

When DLC is enabled, you should be able to see `Restoring DLC` within the build output for the Spin up environment step.

Step 2: Verify that the Image is saved

To keep the cache storage optimal, CircleCI prunes images at the end of the build, under this DLC Teardown step.
Please note that this step is not charged, and does not consume credits on your end.

As of this writing, CircleCI will prune images in an order to fit the DLC storage limit (currently at 15 GiB. Please note that this limit may change in the future).

You can observe this under the build output of the DLC Teardown step.

If your image is pruned, it is not saved into the DLC cache storage then.

Subsequent builds will thus not be able to leverage DLC for the cached image layers.

To verify if your built Docker image was pruned as a result of DLC Teardown, we can list up the available Docker images at the start and end of the job.

steps:
  # check what images were saved and loaded by DLC from previous runs
  - run: |
      docker image ls
  - checkout
  - run: |
      docker image build --tag test --file Dockerfile .
  # again, check what the built images are
  - run: |
      docker image ls

This way, we can compare the image IDs against what was pruned under DLC Teardown.
We can also verify the size of our built images this way.

Outcome

You should be able to confirm if a Docker image was saved as part of the Docker Layer Cache feature.

Additional Resources: 

• Best Practices for writing a Dockerfile
• Docker Layer Caching Quickstart guide