How to debug running Docker containers

Sometimes containers may behave unexpectedly due to configuration issues, application errors, or resource limitations. In this tutorial, we will go through the different methods for debugging running containers using a Postgres container as an example.

Prerequisites

To follow this tutorial:

• You must have Docker installed in your development environment. Get Docker If you haven't already.
• You should be comfortable with how Docker works and the basic commands for pulling images, starting, stopping, and managing containers.

Extract 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 command docker pull domain:

$ docker pull postgres:16

Once the extraction is complete, you can start the postgres container with the following docker run command. Note that 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 called my_postgres with PostgreSQL running inside it. You can check this by running the docker ps domain:

What 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 container configuration, network settings, and status:

$ docker inspect my_postgres

This command generates a JSON object with all the details about the container. You can use tools like I who to analyze and extract specific information of interest from this output.

Truncated output from docker inspect my_postgres

2. View container logs

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

$ docker logs my_postgres

Docker my_postgres logs output truncated

3. Execute commands inside the container

Sometimes it is useful to enter the container and run a series of diagnostic commands. You can do this with the command docker exec Command that allows you to execute commands inside a running container. This is useful for inspecting the container's file system, checking environment variables, and 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 within the my_postgres container. This way, you can run commands from inside the container.

4. Check the running processes

He docker top The command displays the processes that are running 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 container

He docker attach The command allows you to attach the terminal to the main process of a running container. This can be useful for debugging interactive processes:

$ docker attach my_postgres

Please note that attaching it to a container is different than docker exec as it connects you to the container's main process and transmits its standard output and standard error to your terminal.

6. View resource usage

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

$ docker stats my_postgres

An example of output is shown below:

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 the container configuration, viewing logs, running commands inside the container, and monitoring resource usage. Using these techniques, you can effectively troubleshoot and resolve issues with your containerized applications. Happy debugging!

Additional Resources

If you would like to explore further, check out the following resources:

twitter.com/balawc27″ rel=”noopener”>Bala Priya C. Bala is a technical developer and writer from India. She enjoys working at the intersection of mathematics, programming, data science, and content creation. Her areas of interest and expertise include DevOps, data science, and natural language processing. She enjoys reading, writing, programming, and drinking coffee! Currently, she is working on learning and sharing her knowledge with the developer community by creating tutorials, how-to guides, opinion pieces, and more. Bala also creates interesting resource overviews and programming tutorials.