Mastering Docker Container Visibility: Beyond the Basic docker ps Command

Working with Docker in production environments demands more than simply running docker ps and skimming through container names. Knowing exactly which containers are running, how long they’ve been up, why they stopped, and which volumes or networks they touch — these are operational details that matter.

The Default: docker ps

docker ps

This returns active containers, their image, command, age, status, ports, and name. For example:

CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS                    NAMES
a11e19cfb922   nginx:1.25     "nginx -g 'daemon of…"   12 hours ago    Up 12 hours    0.0.0.0:80->80/tcp       prod-nginx
df8327eef6d0   redis:7.2      "redis-server"           2 days ago      Up 2 days      6379/tcp                 cache01

But this view is incomplete. Exited containers—critical for postmortem analysis—don’t appear here.

Full Historical Context: Listing All Containers

docker ps -a

Now, both stopped and running containers appear:

CONTAINER ID   IMAGE        COMMAND              CREATED        STATUS                       PORTS      NAMES
df8327eef6d0   redis:7.2    "redis-server"        2 days ago    Exited (0) 4 hours ago                 cache01
a11e19cfb922   nginx:1.25   "nginx -g 'daemon…"  12 hours ago   Up 12 hours                 80/tcp     prod-nginx

Note: On busy CI/CD hosts, this list can become unwieldy — use filtering to manage output.

Filter by Status, Pattern, Ancestry

Filtering is essential in multi-container fleets. Some practical filters:

• Only show exited containers:

  docker ps -a --filter "status=exited"
  

• Only show paused containers (rare, but encountered in orchestrated environments):

  docker ps --filter "status=paused"
  

• Search for containers by partial name:

  docker ps -a --filter "name=app"
  

• List only containers running from a specific image (e.g., for blue/green upgrades):

  docker ps --filter "ancestor=nginx:1.25"
  

Partial output when a container’s failed (real log):

CONTAINER ID   IMAGE         STATUS                       NAMES
beefdeadbeef   myapi:0.3.1   Exited (137) 23 minutes ago  api-v2-staging

Exit code 137 hints at out-of-memory kill—OS intervention, not a graceful exit.

Disk Usage Insight: docker ps -s

Disk constraints are a frequent issue, especially with ephemeral build runners. To audit per-container disk usage:

docker ps -s

Look for unused containers with large writable layers—culprits for filling /var/lib/docker.

Custom Output for Automation

Automation scripts, CI summaries, or health checks rarely need full tabular output. Instead, tailor the output:

docker ps -a --format "table {{.Names}}\t{{.ID}}\t{{.Status}}"

Sample:

NAMES           ID             STATUS
prod-nginx      a11e19cfb922   Up 12 hours
cache01         df8327eef6d0   Exited (0) 4 hours ago

Other available fields: .Ports, .RunningFor, .Image, .Command. See docs for the full set, or run:

docker ps --format '{{json .}}' | jq .

(Note: JQ required for prettified JSON.)

Compound Queries: Filtering + Formatting

For monitoring or scheduled reports, mix-and-match:

• Find all exited containers from a broken build and summarize:

  docker ps -a --filter "status=exited" --filter "name=build" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"
  

• Return just IDs for later clean-up:

  docker ps -a --filter "status=exited" --format "{{.ID}}"
  

Always review before mass deletion — container metadata loss is permanent.

Resource Utilization: docker stats

Memory/cpu bottlenecks? docker stats shows live metrics:

docker stats $(docker ps -q --filter "ancestor=my-heavy-image")

Gotcha: For short-lived containers, stats may vanish before you can inspect. Use external monitoring (cadvisor, Prometheus) for historical trends.

Practical Table: Command Summary

Field Note

Containers may retain port allocations, mounts, and logs even after exit. Prune old containers (docker container prune) only after checking they're not needed for audit or troubleshooting.

Pro tip: On Docker Engine v20.x+, combining multiple --filter flags is supported, allowing precise queries on complex nodes.

Known issue: The docker ps output order is latest container first—not always intuitive. Consider scripting with sort if order matters.

Closing

The default docker ps output is only a snapshot. With advanced flags and filters, a more nuanced view appears: disk usage trends, postmortem history, resource saturation, and deployment fidelity. Mastery here is less about memorizing options, more about tailoring queries to real problems.

For teams managing stateful workloads or debugging elusive failures, robust visibility isn't optional. It’s operational hygiene.

End of field notes.