Admin-Sistemas ·

Monitorizar Docker con cAdvisor, Prometheus y Grafana: guía paso a paso

Introducción: por qué monitorizar tus contenedores

Los contenedores Docker cambian el juego del despliegue, pero también el de la monitorización: son efímeros, comparten el kernel del host y aparecen y desaparecen en segundos. Los enfoques clásicos de monitorización de máquinas virtuales no funcionan bien aquí. Necesitas métricas de recursos por contenedor, en tiempo casi real, con histórico y alertas.

La combinación ganadora sigue siendo la misma en 2026: cAdvisor recoge las métricas de cada contenedor, Prometheus las almacena y las evalúa con PromQL, y Grafana las convierte en dashboards visuales. En esta guía actualizada los desplegaremos los tres con un único docker-compose.yml, añadiremos reglas de alerta y consultas PromQL probadas.

Nota importante: la imagen google/cadvisor de Docker Hub está obsoleta y lleva años sin actualizarse. La imagen oficial y mantenida es gcr.io/cadvisor/cadvisor:latest, y es la que usaremos en todo el artículo.

cAdvisor: recogiendo métricas de los contenedores

¿Qué es cAdvisor?

cAdvisor (Container Advisor) es un agente de código abierto mantenido por el proyecto Google Cloud que se ejecuta en el host Docker y expone métricas de cada contenedor en ejecución: uso de CPU, memoria, disco, red, además de información sobre el sistema de ficheros y los procesos. Expone todo en formato compatible con Prometheus, listo para el scraping.

Arranque rápido con Docker

Si solo quieres probar cAdvisor de forma aislada, este es el comando correcto en 2026 (observa la imagen oficial de Google Container Registry y los volúmenes de solo lectura):

docker run -d --name=cadvisor --restart=unless-stopped \
  -p 8080:8080 \
  -v /:/rootfs:ro \
  -v /var/run:/var/run:ro \
  -v /sys:/sys:ro \
  -v /var/lib/docker:/var/lib/docker:ro \
  -v /dev/disk:/dev/disk:ro \
  gcr.io/cadvisor/cadvisor:latest

Con esto, la interfaz web de cAdvisor queda disponible en http://<IP_del_host>:8080, y el endpoint de métricas para Prometheus en http://<IP_del_host>:8080/metrics. El flag --restart=unless-stopped garantiza que sobrevive a reinicios del host.

Stack completo: docker-compose.yml con cAdvisor + Prometheus + Grafana

En lugar de levantar cada pieza a mano, desplegaremos el stack entero con Docker Compose. Crea un directorio de trabajo y estos tres ficheros.

Fichero 1: docker-compose.yml

services:
  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker:/var/lib/docker:ro
      - /dev/disk:/dev/disk:ro
    privileged: true

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./alerts.yml:/etc/prometheus/alerts.yml:ro
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=30d'

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:-cambia-esta-password}

volumes:
  prometheus-data:
  grafana-data:

Fichero 2: prometheus.yml

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - /etc/prometheus/alerts.yml

alerting:
  alertmanagers:
    - static_configs:
        - targets: []   # añade aquí tu Alertmanager cuando lo tengas

scrape_configs:
  - job_name: 'cadvisor'
    static_configs:
      - targets: ['cadvisor:8080']

  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

Como todos los servicios comparten la red interna de Compose, Prometheus alcanza a cAdvisor por el nombre del servicio (cadvisor:8080), sin necesidad de IPs.

Fichero 3: alerts.yml — reglas de alerta

Las reglas de alerta convierten métricas en avisos proactivos. Estas tres cubren los casos más habituales: un contenedor que desaparece y consumos anómalos de CPU o memoria.

groups:
  - name: docker-containers
    rules:
      - alert: ContainerDown
        expr: absent(container_last_seen{name=~".+"} offset 5m)
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Posible contenedor caído"
          description: "No se reciben métricas de un contenedor esperado desde hace más de 5 minutos."

      - alert: ContainerHighCpu
        expr: |
          sum by (name) (rate(container_cpu_usage_seconds_total{name!=""}[5m])) * 100 > 80
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "CPU alta en el contenedor {{ $labels.name }}"
          description: "El contenedor lleva más de 10 minutos por encima del 80 % de CPU."

      - alert: ContainerHighMemory
        expr: |
          sum by (name) (container_memory_usage_bytes{name!=""})
            / sum by (name) (container_spec_memory_limit_bytes{name!=""}) > 0.9
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Memoria alta en el contenedor {{ $labels.name }}"
          description: "El contenedor supera el 90 % de su límite de memoria durante más de 10 minutos."

Levanta todo con:

docker compose up -d
docker compose ps

Verifica que Prometheus está haciendo scraping en http://<IP_del_host>:9090/targets: el job cadvisor debe aparecer en estado UP.

PromQL: consultas útiles para tus contenedores

Con las métricas ya en Prometheus, estas consultas cubren el día a día del sysadmin. Pégalas en la consola de Prometheus (:9090) o úsalas como paneles en Grafana.

Uso de memoria por contenedor

sum by (name) (container_memory_usage_bytes{name!=""})

Para verlo como porcentaje del límite asignado:

sum by (name) (container_memory_usage_bytes{name!=""})
  / sum by (name) (container_spec_memory_limit_bytes{name!=""}) * 100

Uso de CPU por contenedor (últimos 5 minutos)

sum by (name) (rate(container_cpu_usage_seconds_total{name!=""}[5m])) * 100

Tráfico de red: bytes recibidos y enviados por contenedor

sum by (name) (rate(container_network_receive_bytes_total{name!=""}[5m]))
sum by (name) (rate(container_network_transmit_bytes_total{name!=""}[5m]))

Reinicios de contenedores

Un contador de reinicios que crece es la primera señal de un contenedor inestable (OOMKilled, crashes en bucle):

sum by (name) (increases(container_start_time_seconds{name!=""}[1h]))

O, más directo, los segundos desde el último arranque (valores bajos = reinicio reciente):

time() - max by (name) (container_start_time_seconds{name!=""})

Los 5 contenedores que más CPU consumen ahora mismo

topk(5, sum by (name) (rate(container_cpu_usage_seconds_total{name!=""}[5m])))

Grafana: dashboards listos para importar

Entra en Grafana (http://<IP_del_host>:3000, usuario admin y la contraseña que definiste) y añade Prometheus como fuente de datos apuntando a http://prometheus:9090. En lugar de construir los dashboards desde cero, importa estos dos de la comunidad, pensados para métricas de cAdvisor:

  • Dashboard 14282 — "Docker and system monitoring" (CPU, memoria, red y disco por contenedor, muy completo).
  • Dashboard 11600 — "Docker monitoring with cAdvisor/Prometheus" (vista compacta, ideal para empezar).

Para importarlos: Dashboards → New → Import, pega el ID numérico y selecciona tu fuente de datos Prometheus. En un par de minutos tendrás visibilidad total del host y de cada contenedor.

Troubleshooting: errores comunes

cAdvisor no recoge métricas del host

Revisa que los volúmenes /, /var/run, /sys y /var/lib/docker están montados como :ro. Sin ellos, cAdvisor no ve ni el sistema de ficheros ni el socket de Docker. Comprueba también que no estás usando la imagen obsoleta google/cadvisor.

Prometheus muestra el target cadvisor como DOWN

Desde dentro del contenedor de Prometheus debe resolverse el nombre cadvisor. Compruébalo con:

docker compose exec prometheus wget -qO- http://cadvisor:8080/metrics | head

Si falla, revisa que ambos servicios están en la misma red de Compose y que el puerto 8080 no lo está ocupando otro proceso del host.

Las alertas no se disparan

Verifica que alerts.yml está referenciado en rule_files y que Prometheus lo cargó sin errores: http://<IP_del_host>:9090/rules. Recuerda que cada regla necesita cumplirse durante el tiempo indicado en for antes de pasar a estado firing.

Grafana no muestra datos

El error más típico es apuntar la fuente de datos a localhost:9090 desde el contenedor de Grafana, donde localhost es el propio Grafana. Usa http://prometheus:9090 (el nombre del servicio en la red de Compose).

Conclusión

Con un solo docker-compose.yml tienes hoy un sistema de monitorización completo: cAdvisor (con su imagen oficial gcr.io/cadvisor/cadvisor:latest) recoge las métricas, Prometheus las almacena y evalúa reglas de alerta, y Grafana las visualiza con dashboards probados por la comunidad (14282 y 11600).

El siguiente paso natural es conectar Prometheus a Alertmanager para recibir los avisos por correo, Slack o webhook, y ajustar los umbrales de alerts.yml a la realidad de tu carga. La monitorización es un proceso continuo: revisa tus reglas cada vez que cambie tu parque de contenedores.