Cuando una aplicación corre dentro de un contenedor Docker, saber qué procesos están activos en su interior es una tarea habitual de diagnóstico. La opción obvia sería entrar al contenedor con docker exec y ejecutar ps, pero hay una forma más directa: docker top.
docker top muestra los procesos en ejecución dentro de un contenedor desde el host, sin necesidad de entrar al contenedor. Es el equivalente al comando ps de Linux, aplicado al interior del contenedor.
Para entender el contexto de monitorización y gestión de contenedores Docker donde encaja este comando, el artículo sobre qué es Docker explica la arquitectura completa.
Qué es docker top y cómo funciona
docker top es un subcomando de docker container que ejecuta el equivalente a ps dentro de un contenedor en ejecución y devuelve el resultado en el terminal del host. El contenedor no necesita tener ps instalado: es el host quien ejecuta la inspección del espacio de nombres de procesos del contenedor.
Esto lo hace especialmente útil en dos escenarios concretos:
- Contenedores sin shell. Las imágenes distroless o construidas desde
scratchno tienen shell ni utilidades del sistema. No se puede usardocker exec bashporque no existe. Condocker topse pueden ver los procesos igualmente. - Diagnóstico rápido. Sin tener que abrir una sesión interactiva dentro del contenedor, se obtiene la lista de procesos en una sola línea de comando.
La sintaxis del comando es:
docker top nombre-o-id-contenedor [opciones-ps]Sintaxis y uso básico
🔴 ¿Quieres entrar de lleno al mundo DevOps & Cloud Computing? 🔴
Descubre el DevOps & Cloud Computing Full Stack Bootcamp de KeepCoding. La formación más completa del mercado y con empleabilidad garantizada
👉 Prueba gratis el Bootcamp en DevOps & Cloud Computing por una semanaEl uso más simple es pasar el nombre o el ID del contenedor:
# Por nombre del contenedor
docker top mi-app
# Por ID del contenedor (sirve el ID completo o los primeros caracteres)
docker top a3f5c8e9d2b1La salida por defecto en sistemas Linux tiene este formato:
UID PID PPID C STIME TTY TIME CMD
root 1234 1230 0 10:25 ? 00:00:00 node server.js
root 1256 1234 0 10:25 ? 00:00:00 node --inspectLas columnas por defecto son:
| Columna | Qué muestra |
|---|---|
| UID | Usuario propietario del proceso |
| PID | ID del proceso dentro del contenedor |
| PPID | ID del proceso padre |
| C | Porcentaje de uso de CPU |
| STIME | Hora de inicio del proceso |
| TTY | Terminal asociado al proceso |
| TIME | Tiempo de CPU acumulado |
| CMD | Comando que ejecuta el proceso |
Opciones de ps para personalizar la salida
Se pueden pasar opciones de ps directamente a docker top para obtener más información o en un formato diferente:
# Todos los procesos con uso de CPU y memoria
docker top mi-app aux
# Formato completo con más columnas
docker top mi-app -ef
# Solo PID y comando
docker top mi-app -eo pid,cmd
# Con uso de memoria
docker top mi-app -eo pid,user,%cpu,%mem,cmdLa opción aux es la más usada en diagnóstico porque muestra todos los procesos con sus porcentajes de CPU y memoria, equivalente a ps aux en un sistema Linux:
$ docker top mi-app aux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.1 0.5 712348 18456 ? Ssl 10:25 0:02 node server.js
root 28 0.0 0.2 654212 8192 ? S 10:25 0:00 node worker.jsdocker top vs docker stats vs docker exec: cuándo usar cada uno
Las tres herramientas sirven para inspeccionar lo que ocurre dentro de un contenedor, pero con enfoques distintos.
| Comando | Qué muestra | Cuándo usarlo |
|---|---|---|
docker top |
Procesos activos dentro del contenedor | Ver qué procesos corren, verificar PID 1, detectar procesos inesperados |
docker stats |
Uso de CPU, memoria, red y disco en tiempo real | Monitorizar consumo de recursos, detectar memory leaks o CPU spikes |
docker exec |
Terminal interactiva o comando específico dentro del contenedor | Diagnóstico profundo, editar archivos, ejecutar comandos complejos |
docker logs |
Salida estándar y de error del proceso principal | Ver logs de la aplicación, diagnosticar errores de arranque |
docker inspect |
Configuración completa del contenedor en JSON | Ver toda la configuración: redes, volúmenes, variables de entorno, estado |
# docker stats: uso de recursos en tiempo real de todos los contenedores
docker stats
# docker stats de un contenedor específico sin actualización continua
docker stats mi-app --no-stream
# Salida típica:
# CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
# a3f5c8e9d2b1 mi-app 0.15% 48.5MiB / 2GiB 2.37% 1.2MB 0B 3Casos de uso reales de docker top
Verificar que solo corre el proceso principal
En contenedores bien construidos, debería haber un único proceso principal (PID 1) y ningún proceso hijo inesperado. docker top permite verificarlo rápidamente:
docker top mi-app
# Salida esperada en un contenedor bien construido:
# UID PID PPID C STIME TTY TIME CMD
# root 1 0 0 10:25 ? 00:00:02 node server.js
# Si aparecen procesos inesperados, hay que investigarDiagnosticar un contenedor que consume demasiados recursos
Si docker stats muestra que un contenedor consume más CPU o memoria de lo esperado, docker top aux permite ver qué proceso específico está causando el consumo:
# Ver qué proceso consume más CPU dentro del contenedor
docker top mi-app -eo pid,user,%cpu,%mem,cmd --sort=-%cpuInspeccionar contenedores sin shell
Las imágenes construidas desde scratch o con base distroless no tienen sh ni bash. No se puede usar docker exec -it mi-app sh. docker top es la única forma directa de ver los procesos activos en esos contenedores sin herramientas externas.
Verificar el usuario que ejecuta el proceso
Una buena práctica de seguridad es no ejecutar el proceso principal del contenedor como root. docker top muestra en la columna UID qué usuario ejecuta cada proceso. Si el Dockerfile usa la instrucción USER para definir un usuario no-root, docker top permite verificar que se aplica correctamente.
Para entender cómo configurar el usuario en el Dockerfile, el artículo sobre qué es un Dockerfile cubre la instrucción USER y las buenas prácticas de seguridad en la construcción de imágenes.
docker container top: el alias completo
docker top es el alias abreviado de docker container top. Los dos comandos son equivalentes y aceptan las mismas opciones:
# Los dos son equivalentes
docker top mi-app
docker container top mi-appLa versión con docker container top es más explícita y algunos equipos la prefieren en scripts y documentación para dejar claro que se está operando sobre un contenedor.
docker compose top: procesos de todos los servicios
En entornos con Docker Compose, el comando equivalente muestra los procesos de todos los servicios definidos en el archivo Compose:
# Procesos de todos los servicios del Compose
docker compose top
# Procesos de un servicio específico
docker compose top web
# Salida típica:
# web
# UID PID PPID C STIME TTY TIME CMD
# root 1234 1230 0 10:25 ? 00:00:02 node server.js
#
# db
# UID PID PPID C STIME TTY TIME CMD
# 999 5678 5674 0 10:25 ? 00:00:05 postgresEs una forma rápida de obtener una visión general de todos los procesos activos en una aplicación multi-contenedor sin tener que ejecutar docker top sobre cada servicio por separado.
Limitaciones de docker top
docker top tiene algunas limitaciones que conviene conocer:
- Solo funciona con contenedores en ejecución. Si el contenedor está detenido, el comando devuelve un error.
- No se actualiza en tiempo real. A diferencia de
docker stats, es una fotografía puntual del estado de los procesos en el momento de la ejecución. Para monitorización continua hay que ejecutarlo repetidamente o usarwatch docker top mi-app. - Los PIDs mostrados son los del host. Docker muestra los PIDs del espacio de nombres del host, no los PIDs del interior del contenedor. El PID 1 del contenedor puede aparecer como un PID diferente desde la perspectiva del host.
- Disponibilidad de opciones de ps según la imagen base. Las opciones de ps disponibles pueden variar según la imagen base del contenedor y la versión del kernel del host.
Rubén trabajaba como ingeniero de aplicaciones cuando decidió dar el salto a DevOps. Hizo el Bootcamp DevOps de KeepCoding para entender el ecosistema completo: Docker, Kubernetes, Terraform y los procesos reales de gestión de infraestructura.
Hoy trabaja como SRE en Red Hat, donde herramientas como docker top, docker stats y docker exec forman parte del diagnóstico cotidiano de contenedores en producción. Lo que más valoró fue aprender a razonar sobre la infraestructura, no solo a ejecutar comandos.
Cómo aprender Docker a nivel profesional
Comandos como docker top son los que separan a quien usa Docker de quien sabe diagnosticar y operar contenedores en producción. En entornos reales, la capacidad de inspeccionar rápidamente los procesos de un contenedor sin interrumpir su ejecución es parte del trabajo cotidiano de cualquier SRE o DevOps Engineer.
Ese conocimiento operativo se construye trabajando con contenedores en proyectos reales donde los problemas de diagnóstico tienen consecuencias directas.
Para aprender a operar Docker a nivel profesional, el DevOps y Cloud Computing Full Stack Bootcamp de KeepCoding cubre el recorrido completo en 6 meses.
Conclusión
docker top es una herramienta de diagnóstico simple pero muy útil: permite ver los procesos activos dentro de un contenedor desde el host, sin entrar al contenedor y sin necesidad de que tenga shell instalado. DevOps y Cloud Computing Full Stack Bootcamp de KeepCoding.
En el conjunto de herramientas de diagnóstico de Docker, docker top responde a la pregunta «¿qué procesos están corriendo?». docker stats responde «¿cuántos recursos consumen?». Y docker exec permite entrar al contenedor para un diagnóstico más profundo.
Los tres juntos cubren la mayor parte de los escenarios de inspección de contenedores en producción.
La referencia oficial de docker top con todas sus opciones está en docs.docker.com/reference/cli/docker/container/top/.
