How To Debug Running Docker Containers

Image by Editor | Midjourney & Canva

Containers can sometimes behave unexpectedly due to configuration issues, application bugs, or resource constraints. In this tutorial, we’ll go over the different methods to debug running containers by taking the example of a Postgres container.

Prerequisites

To follow along to this tutorial:

• You should have Docker installed in your development environment. Get Docker if you haven’t already.
• You should be comfortable with how Docker works and basic commands to pull images, start, stop, and manage containers.

Pull and Start a PostgreSQL Container

First, let’s pull the latest PostgreSQL image from DockerHub and start a container. Here, we pull postgres:16 using the docker pull command:

$ docker pull postgres:16

Once the pull is complete, you can start the postgres container with the following docker run command. Note that the POSTGRES_PASSWORD is the required environment variable you need to start the container:

$ docker run --name my_postgres -e POSTGRES_PASSWORD=my_postgres_password -d postgres

This command starts a new container named my_postgres with PostgreSQL running inside it. You can verify it by running the docker ps command:

Which outputs:

CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS         PORTS      NAMES
5cb6fabbbc8b   postgres:16   "docker-entrypoint.s…"   18 seconds ago   Up 9 seconds   5432/tcp   my_postgres

1. Inspect the Container

You can use the docker inspect command to retrieve detailed information about a container. This can be useful for checking the container’s configuration, network settings, and state:

$ docker inspect my_postgres

This command outputs a JSON object with all the details about the container. You can use tools like jq to parse and extract specific information of interest from this output.

Truncated output of docker inspect my_postgres

2. View Container Logs

The docker logs command fetches the logs from a running container. This is useful for troubleshooting issues related to the application running inside the container.

$ docker logs my_postgres

Truncated output of docker logs my_postgres

3. Execute Commands Inside the Container

Sometimes it’s helpful to get into the container and run a bunch of diagnostic commands. You can do this with the docker exec command that allows you to run commands inside a running container. This is useful for inspecting the container’s filesystem, checking environment variables, or the like.

Here’s how you can start an interactive shell session inside the running container:

$ docker exec -it my_postgres /bin/bash

This command opens an interactive bash shell inside the my_postgres container. So you can run commands from within the container.

4. Check Running Processes

The docker top command shows the running processes inside a container. This can help you identify if any processes are consuming more resources than expected or if there are any unexpected processes running:

UID                 PID                 PPID                C                   STIME               TTY                 TIME                CMD
ollama              8116                8096                0                   09:41               ?                   00:00:00            postgres
ollama              8196                8116                0                   09:41               ?                   00:00:00            postgres: checkpointer
ollama              8197                8116                0                   09:41               ?                   00:00:00            postgres: background writer
ollama              8199                8116                0                   09:41               ?                   00:00:00            postgres: walwriter
ollama              8200                8116                0                   09:41               ?                   00:00:00            postgres: autovacuum launcher
ollama              8201                8116                0                   09:41               ?                   00:00:00            postgres: logical replication launcher

5. Attach to the Container

The docker attach command allows you to attach your terminal to a running container’s main process. This can be useful for debugging interactive processes:

$ docker attach my_postgres

Note that attaching to a container is different from docker exec as it connects you to the container’s main process and streams its standard output and standard error to your terminal.

6. View Resource Usage

With the docker stats command, you can get real-time statistics on container resource usage including CPU, memory, and network. Which is helpful if you want to analyze performance issues:

$ docker stats my_postgres

Here’s a sample output:

CONTAINER ID   NAME          CPU %     MEM USAGE / LIMIT     MEM %     NET I/O       BLOCK I/O         PIDS
5cb6fabbbc8b   my_postgres   0.03%     34.63MiB / 3.617GiB   0.94%     10.6kB / 0B   38.4MB / 53.1MB   6



CONTAINER ID   NAME          CPU %     MEM USAGE / LIMIT     MEM %     NET I/O       BLOCK I/O         PIDS
5cb6fabbbc8b   my_postgres   0.03%     34.63MiB / 3.617GiB   0.94%     10.6kB / 0B   38.4MB / 53.1MB   6



CONTAINER ID   NAME          CPU %     MEM USAGE / LIMIT     MEM %     NET I/O       BLOCK I/O         PIDS
5cb6fabbbc8b   my_postgres   0.03%     34.63MiB / 3.617GiB   0.94%     10.6kB / 0B   38.4MB / 53.1MB   6


...

Debugging Docker containers involves inspecting container config, viewing logs, executing commands inside the container, and monitoring resource usage. With these techniques, you can effectively troubleshoot and resolve issues with your containerized applications. Happy debugging!

Additional Resources

Check out the following resources if you’d like to explore further:

Bala Priya C is a developer and technical writer from India. She likes working at the intersection of math, programming, data science, and content creation. Her areas of interest and expertise include DevOps, data science, and natural language processing. She enjoys reading, writing, coding, and coffee! Currently, she’s working on learning and sharing her knowledge with the developer community by authoring tutorials, how-to guides, opinion pieces, and more. Bala also creates engaging resource overviews and coding tutorials.