Docker commands Guide – docker top with examples

Here’s a complete tutorial on docker top, covering what it does, examples, and use cases.

What is docker top?

docker top is a Docker command used to display the running processes inside a container. It shows information similar to the ps command in Linux, helping you monitor and troubleshoot the container’s processes in real time.

Key Features:

• Lists all running processes inside a container.
• Helps in debugging and monitoring process-level activity.
• Supports custom process options like ps flags (-ef or aux).

Basic Syntax

docker top CONTAINER [ps OPTIONS]
Code language: CSS (css)

Arguments:

• CONTAINER: The name or ID of the container.
• [ps OPTIONS]: Optional Linux ps options to customize the output (e.g., -ef, aux).

Examples of docker top

1. List Running Processes in a Container

docker top my_container

Example Output:

UID     PID   PPID  C  STIME  TTY   TIME   CMD
root    123   1     0  10:00  ?     00:00 /bin/bash
root    456   123   0  10:01  ?     00:00 sleep 300

This shows all running processes in my_container.

2. Use ps -ef to Get Detailed Process Information

docker top my_container -ef

This displays detailed process information with extended fields, including UID, PID, CPU, and start time.

3. Display Process Information Similar to ps aux

docker top my_container aux

This provides process information in a format similar to the ps aux command.

4. Check the Main Process of a Container

docker top my_web_container

This helps you verify that the main web server process (e.g., nginx or httpd) is running as expected.

5. Monitor Resource Usage for a Specific Process

docker top my_app_container -eo pid,cmd,%cpu,%mem

This shows the PID, command, CPU usage, and memory usage for processes in my_app_container.

6. Use docker top in a Script

#!/bin/bash
docker top my_app_container > process_list.txt
echo "Process list saved to process_list.txt"
Code language: PHP (php)

This script saves the process list from my_app_container to a file.

7. Check for Zombie Processes

docker top my_container | grep defunct

This checks for zombie processes (<defunct>) inside the container.

8. Combine with watch for Real-Time Monitoring

watch docker top my_container

This updates the process list every 2 seconds, giving you a real-time view of running processes.

9. Check Processes Across Multiple Containers

docker ps -q | xargs -n 1 docker top

This lists processes for all running containers.

Use Cases for docker top

1. Monitoring Running Processes

• Verify that the main application process is running inside the container.
• Example: Ensure the web server (NGINX or Apache) is active.

2. Debugging and Troubleshooting

• Identify stuck or zombie processes.
• Debug performance issues by checking which processes consume high CPU or memory.

3. Security Auditing

• Monitor processes to detect unauthorized or malicious processes inside containers.
• Example: Ensure only the intended processes are running in production containers.

4. Incident Response and Forensics

• Use docker top during incident response to capture the state of processes in a compromised container.

5. Performance Analysis

• Identify bottlenecks by monitoring the CPU and memory usage of container processes.
• Example: Check if a background task is consuming too many resources.

6. Process-Based Monitoring and Health Checks

• Integrate docker top in monitoring scripts to detect missing or stuck processes.
• Example: Automatically restart a container if a key process is missing.

List of Common docker top Commands

Best Practices for Using docker top:

1. Use docker top for regular monitoring to verify critical processes.
2. Combine with grep or watch for real-time process filtering and monitoring.
3. Automate health checks based on process availability and resource consumption.
4. Filter columns (-eo) for relevant metrics like CPU, memory, and PID.
5. Capture process lists during debugging or incident response for later analysis.

Common Errors and Solutions

1. “No such container”
   → Ensure the container exists and is running. Use docker ps to verify.
2. Processes not shown
   → The container may have stopped or exited. Use docker ps -a to check its status.
3. Zombie processes detected (<defunct>)
   → Investigate the main process or entrypoint script for mismanagement of child processes.

Combining docker top with Other Commands

1. Check Resource Usage with docker stats: docker stats my_container docker top my_container
2. Restart Container if a Process is Missing: if ! docker top my_app | grep "nginx"; then docker restart my_app fi

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.