Admin-Sistemas ·

Implementación paso a paso de dashboards unificados en Grafana con Prometheus, Loki y Alertmanager

Introducción

En entornos de producción modernos es habitual contar con varios sistemas de observabilidad: Prometheus para métricas, Loki para logs y Alertmanager para gestionar notificaciones. Grafana se ha convertido en la capa visual que permite unificar toda esa información en dashboards coherentes y, además, definir alertas basadas en complejos patrones de log. En este artículo veremos, paso a paso, cómo instalar y configurar cada componente, crear un dashboard que muestre métricas y logs en la misma vista y, finalmente, generar alertas que se disparen cuando se detecten eventos críticos en los logs.

1. Preparación del entorno

1.1. Requisitos de hardware y software

  • Servidor Linux (Ubuntu 22.04 o CentOS 9) con al menos 2 CPU y 4 GB RAM.
  • Docker & Docker‑Compose (versión ≥ 2.20).
  • Acceso a internet para descargar imágenes oficiales.
  • Puertos abiertos: 3000 (Grafana), 9090 (Prometheus), 3100 (Loki), 9093 (Alertmanager).

1.2. Instalación de Docker y Docker‑Compose

# Ubuntu
sudo apt update
sudo apt install -y docker.io docker-compose

Añadir usuario al grupo docker (opcional)

sudo usermod -aG docker $USER newgrp docker

1.3. Estructura del proyecto

Crearemos un directorio monitoring-stack con la siguiente jerarquía:

monitoring-stack/
├─ docker-compose.yml
├─ prometheus/
│   └─ prometheus.yml
├─ loki/
│   └─ loki-config.yml
├─ alertmanager/
│   └─ alertmanager.yml
└─ grafana/
    └─ provisioning/
        ├─ dashboards/
        └─ datasources/

2. Despliegue de la stack con Docker‑Compose

2.1. Archivo docker-compose.yml


services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
    restart: unless-stopped

loki: image: grafana/loki:2.9.1 command: -config.file=/etc/loki/loki-config.yml volumes: - ./loki/loki-config.yml:/etc/loki/loki-config.yml ports: - “3100:3100” restart: unless-stopped

promtail: image: grafana/promtail:2.9.1 volumes: - /var/log:/var/log - ./promtail/config.yml:/etc/promtail/config.yml command: -config.file=/etc/promtail/config.yml restart: unless-stopped

alertmanager: image: prom/alertmanager:latest volumes: - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml ports: - “9093:9093” restart: unless-stopped

grafana: image: grafana/grafana:10.2.0 ports: - “3000:3000” volumes: - ./grafana/provisioning:/etc/grafana/provisioning environment: - GF_SECURITY_ADMIN_PASSWORD=admin restart: unless-stopped

2.2. Configuración de Prometheus (prometheus/prometheus.yml)

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:

  • job_name: ‘prometheus’ static_configs:

    • targets: [‘localhost:9090’]
  • job_name: ‘node_exporter’ static_configs:

    • targets: [‘host.docker.internal:9100’]

2.3. Configuración de Loki (loki/loki-config.yml)

auth_enabled: false

server: http_listen_port: 3100

ingester: lifecycler: address: 127.0.0.1 ring: kvstore: store: inmemory replication_factor: 1 chunk_idle_period: 5m chunk_retain_period: 30s max_transfer_retries: 0

schema_config: configs: - from: 2020-10-24 store: boltdb-shipper object_store: filesystem schema: v11 index: prefix: index_ period: 24h

storage_config: boltdb_shipper: active_index_directory: /tmp/loki/index cache_location: /tmp/loki/cache shared_store: filesystem filesystem: directory: /tmp/loki/chunks

limits_config: enforce_metric_name: false reject_old_samples: true reject_old_samples_max_age: 168h

2.4. Configuración de Alertmanager (alertmanager/alertmanager.yml)

global:
  resolve_timeout: 5m

route: group_by: [‘alertname’] group_wait: 30s group_interval: 5m repeat_interval: 3h receiver: ‘slack-notifications’

receivers:

2.5. Lanzar la stack

cd monitoring-stack
docker-compose up -d

Verifique que todos los contenedores estén “healthy” con docker ps. Acceda a Grafana en http://IP:3000 (usuario admin, password admin).

3. Configuración de fuentes de datos en Grafana

3.1. Provisionamiento automático

Grafana permite definir datasources mediante archivos YAML bajo /etc/grafana/provisioning/datasources/. Creamos dos archivos:

Prometheus datasource (datasources/prometheus.yml)

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    access: proxy
    isDefault: true
    editable: false

Loki datasource (datasources/loki.yml)

apiVersion: 1
datasources:
  - name: Loki
    type: loki
    url: http://loki:3100
    access: proxy
    editable: false

Reinicie Grafana para que los cambios tomen efecto:

docker restart monitoring-stack_grafana_1

3.2. Verificación

En la UI de Grafana, diríjase a Configuration → Data Sources y compruebe que ambos aparecen sin errores. Realice una consulta rápida:

  • Prometheus: up
  • Loki: {job="varlogs"} |~ "error"

4. Creación del dashboard unificado

4.1. Diseño del panel

El objetivo es visualizar, en una sola vista, la métrica cpu_usage_seconds_total y los logs de aplicación que contengan la palabra ERROR. Usaremos dos tipos de paneles:

  • Graph (Prometheus)
  • Logs (Loki)

4.2. JSON de provisión (opcional)

Para reproducir el dashboard en cualquier entorno, guardaremos su definición en grafana/provisioning/dashboards/unified.json y lo referenciamos en dashboards.yml.

{
  "dashboard": {
    "id": null,
    "title": "Unified Metrics & Logs",
    "panels": [
      {
        "type": "graph",
        "title": "CPU usage (seconds)",
        "datasource": "Prometheus",
        "targets": [
          {
            "expr": "rate(cpu_usage_seconds_total[5m])",
            "legendFormat": "{{instance}}"
          }
        ],
        "gridPos": { "x": 0, "y": 0, "w": 12, "h": 8 }
      },
      {
        "type": "logs",
        "title": "Application errors",
        "datasource": "Loki",
        "targets": [
          {
            "expr": "{job=\"app\"} |= \"ERROR\"",
            "refId": "A"
          }
        ],
        "gridPos": { "x": 12, "y": 0, "w": 12, "h": 8 }
      }
    ],
    "schemaVersion": 38,
    "version": 1
  },
  "overwrite": true
}

4.3. Creación manual (paso a paso)

  1. En Grafana, haga clic en + → Dashboard → Add new panel.
  2. Seleccione Prometheus como datasource y pegue la consulta rate(cpu_usage_seconds_total[5m]). Ajuste el rango de tiempo a 1 h.
  3. Guarde el panel con el nombre “CPU usage”.
  4. Repita el proceso, pero elija Loki como datasource y use la consulta {job="app"} |= "ERROR". Active la opción “Show timestamp” para facilitar la correlación.
  5. Organice los paneles lado a lado y guarde el dashboard como “Unified Metrics & Logs”.

5. Configuración de alertas basadas en patrones de log

5.1. Regla de alerta en Grafana

Grafana 10 permite crear alertas directamente sobre consultas Loki.

  1. En el panel de logs, haga clic en la pestaña Alert.
  2. Pulse Create Alert Rule.
  3. Defina la expresión:
count_over_time({job="app"} |= "ERROR" [5m]) > 10

Esto disparará la alerta si en los últimos 5 minutos aparecen más de 10 líneas con ERROR.

5.2. Envío de la alerta a Alertmanager

En el formulario de la regla, seleccione Contact point → Alertmanager y configure la URL del servicio:

http://alertmanager:9093/api/v2/alerts

Marque la opción “Send resolved notifications” para que también se informe cuando la condición desaparezca.

5.3. Verificación de la cadena de alertas

Genere un log de prueba en el contenedor app (supongamos que existe):

docker exec -i app sh -c 'for i in $(seq 1 15); do echo "$(date) - ERROR - test $i"; sleep 1; done' >> /var/log/app.log

Observe que la alerta aparece en la UI de Grafana y, tras unos segundos, llega a Slack según la configuración del Alertmanager.

6. Troubleshooting y errores comunes

6.1. Prometheus no scrapea targets

  • Síntoma: En la UI de Prometheus, Targets muestra “down”.
  • Causa típica: El nombre del host en static_configs es incorrecto o el puerto no está expuesto.
  • Solución: Verifique la IP accesible desde el contenedor de Prometheus:
    docker exec monitoring-stack_prometheus_1 curl -s http://host.docker.internal:9100/metrics | head
    Corrija targets en prometheus.yml y recargue:
    docker kill -s HUP monitoring-stack_prometheus_1

6.2. Loki no recibe logs de Promtail

  • Síntoma: Consulta en Loki devuelve “no entries found”.
  • Causa: Ruta de volumen mal montada o rotación de logs sin permisos.
  • Solución: Asegúrese de que /var/log está montado en Promtail y que el usuario dentro del contenedor tiene permisos de lectura:
    docker exec monitoring-stack_promtail_1 ls -l /var/log

6.3. Alertas no llegan a Slack

  • Síntoma: Alertmanager muestra “silenced” o “pending”.
  • Causa: URL del webhook incorrecta o falta de permiso en el canal.
  • Solución: Pruebe el webhook con curl:
    curl -X POST -H 'Content-type: application/json' --data '{"text":"test"}' https://hooks.slack.com/services/...
    Si falla, regenere el webhook en Slack y actualice alertmanager.yml. Reinicie Alertmanager.

6.4. Panel de logs muestra “No data”

  • Síntoma: El panel de Loki está vacío aunque los logs existen.
  • Causa: Timezone o rango de tiempo mal alineado.
  • Solución: Ajuste el selector de tiempo del dashboard a “Last 24 h” y verifique que la zona horaria de Grafana coincide con la del servidor (Settings → Preferences → Timezone).

Conclusión

Unificar métricas de Prometheus y logs de Loki en Grafana permite a los administradores de sistemas obtener una visión completa del comportamiento de sus aplicaciones. La combinación con Alertmanager brinda la capacidad de crear alertas sofisticadas basadas en patrones de log, reduciendo el tiempo de detección y respuesta ante incidentes. Siguiendo los pasos descritos —instalación de la stack, provisionamiento de datasources, diseño de dashboards y configuración de alertas— se obtiene una solución robusta, reproducible y fácil de mantener. Recuerde revisar periódicamente los límites de retención de Loki y la carga de consultas de Prometheus para garantizar un rendimiento óptimo a medida que crece el entorno.