Guiame para levantar Prometheus + Grafana con Docker Compose en 5 minutos

Introducción

Si querés empezar a monitorizar tus servicios de forma rápida y sin complicados scripts de instalación, Docker Compose es la solución perfecta. Con solo un archivo YAML podés lanzar tanto Prometheus (el recolector de métricas) como Grafana (el panel visual) en cuestión de minutos. Este artículo te guía paso a paso para tener ambos servicios corriendo en tu máquina local, con ejemplos prácticos y la salida esperada en cada etapa. Al final, sabrás cómo verificar que todo funciona, agregar una fuente de datos y montar un dashboard de ejemplo, además de aprender algunos trucos y mejores prácticas para evitar los errores más comunes.

Este tutorial está orientado a desarrolladores, ingenieros DevOps y a cualquier persona que quiera un setup de monitorización rápido para proyectos pequeños o pruebas. No se requieren conocimientos previos de Docker más allá de lo básico; solo necesitas Docker Engine y Docker Compose instalados.

Qué son Prometheus y Grafana

• Prometheus: Un servidor de métricas de código abierto que recolecta datos de tiempo serie de targets habilitados (servicios, contenedores, nodos, etc.). Expone una API HTTP y un potente lenguaje de consulta (PromQL). Es ideal para entornos cloud nativos y funciona muy bien con el ecosistema Kubernetes.
• Grafana: Una plataforma de visualización que permite crear paneles interactivos a partir de una variedad de fuentes de datos. Con un conector nativo, Grafana puede leer los datos expuestos por Prometheus y mostrarlos como gráficos, tablas o alarmas.

Cuando se ejecutan juntos, forman un stack de monitorización completo y autosuficiente.

Por qué usar Docker Compose

Docker Compose simplifica el despliegue de múltiples contenedores que interactúan entre sí. Con un solo comando (docker compose up -d) podés iniciar, detener y gestionar todo el stack. Además, el enfoque de código declarativo (el archivo docker‑compose.yml) facilita compartir la configuración con teammates o versionarla junto con el código de la aplicación.

Requisitos previos

• Docker Engine versión ≥ 20.10
• Docker Compose versión ≥ 2.0 (docker compose, no docker-compose)
• Recursos disponibles: 2 GB de RAM y 2 CPU son suficientes para empezar
• Acceso a localhost desde el navegador web para Grafana

Si cumplís con estos requisitos, estás listo para empezar.

Paso 1 – Crear el archivo docker‑compose.yml

Creamos un archivo en tu proyecto (o en una carpeta dedicada monitoring/) llamado docker‑compose.yml.

# docker-compose.yml
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus:/etc/prometheus
      - prometheus_data:/prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_SECURITY_ADMIN_USER=admin
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning
      - grafana_data:/var/lib/grafana
    restart: unless-stopped

volumes:
  prometheus_data:
  grafana_data:

Explicación

• Ambos contenedores usan las imágenes oficiales más recientes (prom/prometheus y grafana/grafana).
• Los puertos 9090 (Prometheus) y 3000 (Grafana) se exponen en localhost.
• Se montan volúmenes locales para la configuración (./prometheus y ./grafana/provisioning) y para que los datos persistan (prometheus_data, grafana_data).
• Grafana se configura con un usuario/admin predeterminado (admin/admin) – recordá cambiarlo en producción.

Paso 2 – Agregar archivos de configuración

2.1 Archivo de configuración de Prometheus (prometheus.yml)

Crea una carpeta prometheus e inside escribe prometheus.yml:

# prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'docker'
    docker_sd_configs:
      - host: unix:///var/run/docker.sock
    relabel_configs:
      - source_labels: [__meta_docker_container_label_com_docker_compose_project]
        action: keep
        regex: your-project-name   # reemplaza con el nombre de tu compose project

Este ejemplo recolecta métricas de contenedores administrados por Docker Compose. Ajustá regex al docker‑compose project que uses.

2.2 Dataset de ejemplo de Grafana

Crea una carpeta grafana/provisioning/datasources y dentro prometheus.yml:

# grafana/provisioning/datasources/prometheus.yml
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    access: proxy
    isDefault: true

Luego, crea grafana/provisioning/dashboards y dentro example-dashboard.json (un dashboard simple):

{
  "dashboard": {
    "id": null,
    "title": "Example – Up metric",
    "panels": [
      {
        "id": 1,
        "title": "Container Up",
        "type": "graph",
        "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0},
        "targets": [
          {
            "expr": "up{job=\"docker\"}",
            "legendFormat": "{{instance}}",
            "refId": "A"
          }
        ]
      }
    ],
    "refresh": "5m"
  },
  "overwrite": true
}

Estos archivos aseguran que Grafana conozca Prometheus y traiga un dashboard de ejemplo automáticamente.

Paso 3 – Levantar los servicios

Asegúrate de estar en la carpeta donde resides docker-compose.yml y ejecuta:

docker compose up -d

El comando anterior descarga las imágenes, crea las redes, inicia los contenedores y los mantiene corriendo en background (-d).

Salida esperada (simulada)

# Simulación de la salida de "docker compose ps"
print("   NAME                COMMAND                  SERVICE             STATUS              PORTS")
print("--------------------------------------------------------------------------------------------")
print("prometheus           /bin/prometheus --config....  prometheus          running             0.0.0.0:9090->9090/tcp")
print("grafana              /docker-entrypoint.sh g...   grafana             running             0.0.0.0:3000->3000/tcp")
print("--------------------------------------------------------------------------------------------")

Si ves ambos contenedores marcados como running, estás en camino.

Paso 4 – Acceder a Grafana

Abre tu navegador y visita http://localhost:3000. La pantalla de login aparece con los credenciales por defecto (admin/admin). Ingresá y te dirigirá a la página de inicio de Grafana.

Es buena idea cambiar la contraseña ahora:

1. Haz click en tu avatar → Configuración → Seguridad → Cambiar contraseña.
2. Establece una contraseña robusta y guárdala en un gestor de contraseñas seguro.

Paso 5 – Agregar Prometheus como fuente de datos

Cuando Grafana arranca con la provisión, debería detectar automáticamente el datasource que definiste. Puedes verificarlo:

1. Haz click en Configuración (icono de engranaje) → Fuentes de datos.
2. Deberías ver Prometheus listado; haz click en Probar para validar la conexión.

El resultado esperado es un mensaje de éxito, por ejemplo:

Datos fuentePrometheusprobados correctamente

Si falla, revisa que el archivo prometheus.yml en grafana/provisioning/datasources/ tenga la sintaxis correcta y que el servicio prometheus esté accesible (usa docker compose logs prometheus para revisar).

Paso 6 – Agregar el dashboard de ejemplo

Ve a Dashboard → Gestionar → Importar → pega el ID del panel de ejemplo (o sube el archivo JSON). Como ya hay un archivo de provisioning, puedes también:

1. Coloca example-dashboard.json dentro de grafana/provisioning/dashboards/.
2. Reinicia Grafana (docker compose restart grafana) – Grafana detectará el nuevo dashboard automáticamente.

El dashboard debería aparecer en Dashboard → Example – Up metric y mostrar una línea con el estado up de tus contenedores.

Paso 7 – Verificar métricas en Prometheus

Abre http://localhost:9090. En la barra de búsqueda, escribe up{job="docker"} y presiona Ejecutar. Deberías ver un listado de métricas con estado 1 (up) o 0 (down). Para servicios reales, necesitarás que Prometheus pueda recolectar de ellos; el ejemplo recolecta automáticamente contenedores que pertenecen al mismo docker‑compose project.

Vista previa esperada

Métrica    Etiquetas                              Valor   Timestamps
up{instance="container_1",...}          1       2025‑12‑20T12:34:56Z
up{instance="container_2",...}          0       2025‑12‑20T12:34:57Z

Si alguna métrica aparece en 0, verifica que el contenedor correspondiente esté corriendo (docker compose ps) y que Docker Sock esté accesible (chmod chmod 666 /var/run/docker.sock si usas el SD de Docker).

Paso 8 – Depuración común

Adicionalmente, ejecuta docker compose logs -f prometheus para ver cualquier error de sintaxis en tu archivo de configuración.

Mejores prácticas

1. Versiona la configuración – Guarda docker-compose.yml, prometheus.yml, grafana/provisioning bajo control de versiones (ej: Git). Así podés reproducir el stack en cualquier ambiente.
2. No uses credenciales hard‑coded – Si Grafana precisa de una base de datos externa (ej: PostgreSQL para usuarios), inyecta variables de ambiente o monta un archivo secreto.
3. Protege el Docker Socket – El service discovery usando unix:///var/run/docker.sock es práctico pero menos seguro. Considera usar docker provider en vez de file para restringir acceso.
4. Rota de alertas – Una vez que tengas métricas en Prometheus, configura alertas a través de Grafana o directamente con la configuración alerting.yml. Esto te ayuda a responder rápido antes de que un servicio caiga.
5. Monitoreá el stack mismo – Prometheus puede auto‑monitorizarse: agrega un job extra que escrapee prometheus y grafana endpoints (/metrics, /api/metrics respectivamente). Esto te da visibilidad de los responsables de las responsabilidades de monitorización.
6. Usa recursos limits – Para evitar que un container hambree recursos, agrega deploy.resources.limits o resources en docker-compose.yml:

resources:
  limits:
    cpus: '0.5'
    memory: 512M

1. Actualizaciones – Usa tags de versión fijas (prom/prometheus:v2.45.0) en producción para evitar actualizaciones inesperadas que puedan romper la configuración.

Conclusión

Siguiendo estos pasos, tendrías Prometheus y Grafana corriendo en menos de cinco minutos con Docker Compose. Tienes un pipeline de métricas funcional, un dashboard de ejemplo y un punto de partida claro para agregar más fuentes de datos y alertas.

Recuerda que la monitorización es un proceso iterativo: a medida que tu aplicación crezca, podrás:

• Agregar más servicios a docker-compose.yml y enriquecer prometheus.yml.
• Implementar dashboards más complejos usando paneles de Grafana.
• Configurar una alerta robusta con Prometheus Alertmanager.
• Persistir datos de series temporales en un storage remoto (ej: Cortex, M3DB) si necesitas historicidad a largo plazo.

Experimenta con los ejemplos, adáptalos a tus necesidades y pronto tendrás un stack de monitorización totalmente operativo.

¡Feliz monitoreo!