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.
