Docker Stats

Docker stats y métricas

El comando docker stats proporciona una vista en tiempo real del uso de recursos de los contenedores en ejecución. Esta funcionalidad resulta fundamental para monitorear el rendimiento y diagnosticar problemas de recursos en entornos de desarrollo y producción.

Docker stats muestra métricas actualizadas dinámicamente, permitiendo observar cómo los contenedores consumen recursos del sistema host. Por defecto, el comando se ejecuta en modo streaming, actualizando las estadísticas continuamente hasta que se interrumpe con Ctrl+C.

Métricas básicas disponibles

Docker stats presenta varias métricas clave organizadas en columnas:

• CONTAINER ID/NAME: Identificador único del contenedor y su nombre asignado
• CPU %: Porcentaje de uso de CPU respecto a la capacidad total del sistema
• MEM USAGE / LIMIT: Memoria RAM utilizada y límite asignado (si existe)
• MEM %: Porcentaje de memoria utilizada respecto al total disponible
• NET I/O: Datos transmitidos y recibidos por la interfaz de red
• BLOCK I/O: Datos leídos y escritos en el disco
• PIDs: Número de procesos e hilos ejecutándose dentro del contenedor

Veamos un ejemplo práctico ejecutando algunos contenedores:

# Ejecutar contenedores para observar métricas
docker run -d --name web-server nginx:latest
docker run -d --name database mysql:8.0 -e MYSQL_ROOT_PASSWORD=password
docker run -d --name cache redis:alpine

Al ejecutar docker stats, obtendremos una salida similar a esta:

docker stats

CONTAINER ID   NAME         CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O         PIDS
a1b2c3d4e5f6   web-server   0.05%     3.2MiB / 7.775GiB    0.04%     1.38kB / 0B       4.1MB / 0B        2
f6e5d4c3b2a1   database     0.23%     372MiB / 7.775GiB    4.68%     648B / 0B         45.2MB / 8.19kB   37
9h8g7f6e5d4c   cache        0.12%     7.8MiB / 7.775GiB    0.10%     906B / 0B         1.2MB / 0B        4

Interpretación de métricas por sistema operativo

Las métricas de docker stats se comportan de manera diferente según el sistema operativo y la arquitectura de Docker:

En Linux nativo:

• Las métricas reflejan directamente el uso de recursos del kernel host
• Los valores de CPU % corresponden al uso real de cores físicos
• La memoria mostrada es la RAM física del sistema

En Docker Desktop (Windows/macOS):

• Las métricas se obtienen desde la máquina virtual que ejecuta Docker Engine
• Los límites de memoria corresponden a la VM asignada a Docker Desktop
• El CPU % se calcula respecto a los recursos asignados a la VM

En Windows con contenedores Windows:

• Los contenedores Windows muestran métricas específicas del kernel de Windows
• Las métricas de red pueden incluir overhead del stack de red de Windows

Opciones de visualización y formato

El comando docker stats incluye varias opciones para personalizar la salida:

Mostrar estadísticas puntuales:

docker stats --no-stream

Este flag obtiene una captura instantánea de las métricas sin mantenerse ejecutando, útil para scripts o comprobaciones rápidas.

Incluir contenedores detenidos:

docker stats --all

Por defecto, docker stats solo muestra contenedores en ejecución. Con --all se incluyen también los contenedores detenidos, aunque mostrarán valores en cero.

Estadísticas de contenedores específicos:

docker stats web-server database
docker stats $(docker ps -q)  # Todos los contenedores ejecutándose

Métricas de red y disco

Las métricas de NET I/O muestran el tráfico de red acumulado:

NET I/O: 2.45MB / 1.67MB

El primer valor representa datos recibidos (RX) y el segundo datos transmitidos (TX) desde el inicio del contenedor.

Las métricas de BLOCK I/O indican la actividad del sistema de archivos:

BLOCK I/O: 125MB / 45.2MB  

El primer valor muestra datos leídos del disco y el segundo datos escritos al disco, incluyendo logs, archivos temporales y datos persistentes.

Limitaciones y consideraciones

Docker stats presenta algunas limitaciones importantes:

• Las métricas se actualizan cada segundo aproximadamente, no en tiempo real absoluto
• En sistemas con muchos contenedores, el overhead de recolección puede ser significativo
• Los contenedores con volúmenes montados pueden mostrar I/O disk que no corresponde al contenedor sino al host
• En arquitecturas ARM, algunos valores pueden tener precisión reducida

Para contenedores de bases de datos como MySQL o PostgreSQL, presta especial atención a las métricas de memoria y BLOCK I/O, ya que estos servicios suelen ser intensivos en ambos recursos.

Las métricas de PIDs son especialmente útiles para identificar contenedores que pueden estar experimentando fork bombs o creando demasiados procesos, lo que puede afectar la estabilidad del sistema.

Formato y opciones

Docker stats ofrece múltiples opciones de formateo que permiten personalizar la salida según las necesidades específicas de monitorización o integración con scripts y herramientas externas.

Formateo personalizado con --format

La opción --format utiliza la sintaxis de templates de Go para crear salidas estructuradas y personalizadas:

docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Esta sintaxis permite seleccionar únicamente las métricas relevantes y organizarlas de manera específica. Los campos disponibles incluyen:

• .Name: Nombre del contenedor
• .ID: ID completo del contenedor
• .CPUPerc: Porcentaje de uso de CPU
• .MemUsage: Uso actual de memoria
• .MemPerc: Porcentaje de memoria utilizada
• .NetIO: Input/Output de red
• .BlockIO: Input/Output de disco
• .PIDs: Número de procesos

Formatos de salida estructurados

Para integración con herramientas de procesamiento de datos, docker stats soporta formatos estructurados:

Formato JSON:

docker stats --format "{{json .}}" --no-stream

Esto produce una salida JSON por cada contenedor, ideal para scripts de monitorización:

{"BlockIO":"45.2MB / 8.19kB","CPUPerc":"0.23%","Container":"database","ID":"f6e5d4c3b2a1","MemPerc":"4.68%","MemUsage":"372MiB / 7.775GiB","Name":"database","NetIO":"648B / 0B","PIDs":"37"}

Formato de tabla personalizada:

docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemPerc}}\t{{.PIDs}}"

NAME         CPU %     MEM %     PIDS
web-server   0.05%     0.04%     2
database     0.23%     4.68%     37
cache        0.12%     0.10%     4

Opciones avanzadas de filtrado

Docker stats incluye opciones adicionales para casos de uso específicos:

Mostrar solo IDs de contenedor:

docker stats --format "{{.ID}}" --no-stream $(docker ps -q)

Filtrar contenedores por patrón:

docker stats $(docker ps --filter "name=web*" -q)

Combinar con watch para intervalos personalizados:

watch -n 5 'docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"'

Plantillas útiles para monitorización

Algunas plantillas predefinidas resultan especialmente útiles en entornos de producción:

Vista compacta para dashboards:

docker stats --format "{{.Name}}: CPU={{.CPUPerc}} MEM={{.MemPerc}} PIDs={{.PIDs}}"

Salida compatible con sistemas de logging:

docker stats --no-stream --format "timestamp=$(date -Iseconds) container={{.Name}} cpu={{.CPUPerc}} memory={{.MemUsage}} network={{.NetIO}} disk={{.BlockIO}}"

Detección de contenedores con alto consumo:

docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemPerc}}" | grep -E "[0-9]{2,}\.[0-9]+%"

Opciones de intervalo y precisión

Aunque docker stats no incluye opciones nativas para modificar el intervalo de actualización, se puede combinar con herramientas del sistema:

Capturas periódicas con cron:

# En crontab: capturar métricas cada 5 minutos
*/5 * * * * docker stats --no-stream --format "{{json .}}" >> /var/log/docker-stats.log

Monitorización continua con timeout:

timeout 60s docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Integración con scripts de automatización

Las opciones de formato facilitan la integración con scripts de monitorización y alertas:

#!/bin/bash
# Script de ejemplo para alertas de uso de memoria
HIGH_MEM_THRESHOLD=80

docker stats --no-stream --format "{{.Name}} {{.MemPerc}}" | while read name mem_perc; do
    mem_value=$(echo $mem_perc | sed 's/%//')
    if (( $(echo "$mem_value > $HIGH_MEM_THRESHOLD" | bc -l) )); then
        echo "ALERTA: $name usando $mem_perc de memoria"
    fi
done

Exportación a CSV:

echo "Contenedor,CPU,Memoria,Red,Disco,PIDs" > docker-stats.csv
docker stats --no-stream --format "{{.Name}},{{.CPUPerc}},{{.MemPerc}},{{.NetIO}},{{.BlockIO}},{{.PIDs}}" >> docker-stats.csv

Consideraciones para formatos personalizados

Al utilizar formatos personalizados, ten en cuenta estas recomendaciones:

• Los templates deben usar sintaxis exacta de Go template, incluyendo las llaves dobles
• Los nombres de campos son sensibles a mayúsculas y minúsculas
• Para salidas que se procesarán automáticamente, siempre usa --no-stream
• En entornos con muchos contenedores, considera filtrar antes de aplicar formatos complejos

La flexibilidad del sistema de templates permite crear salidas adaptadas a cualquier herramienta de monitorización externa, desde sistemas de logging hasta dashboards de métricas especializados.