Prometheus + Grafana + Loki: Stack de Observabilidad Completo para tu Homelab 2025

¿Cuántas veces Uptime Kuma te ha avisado de que un servicio está caído, pero no sabes por qué ni qué pasó antes? Si quieres ir más allá del monitoreo básico y entender qué está pasando dentro de tus servicios, necesitas un stack de observabilidad completo. El problema es que soluciones como Datadog cuestan $31/host/mes, y ELK Stack requiere 4-8 GB RAM solo para empezar.

Prometheus + Grafana + Loki es el stack open-source que necesitas: self-hosted, gratis, con métricas profundas, logs centralizados y dashboards profesionales. En esta guía completa aprenderás a montar el stack completo desde cero con Docker Compose, configurar dashboards pre-hechos y recibir alertas cuando algo va mal antes de que se caiga.

📋 TL;DR (Resumen Ejecutivo)

En este tutorial aprenderás a montar un stack de observabilidad profesional en tu homelab usando Prometheus (métricas), Grafana (visualización) y Loki (logs). Cubrimos desde instalación básica con Docker Compose hasta casos de uso avanzados con dashboards pre-configurados y alertas automáticas.

Lo que conseguirás:

• ✅ Stack completo funcionando en 10 minutos con Docker Compose
• ✅ Métricas del sistema (CPU, RAM, disco, red) y contenedores Docker
• ✅ Logs centralizados de todos tus servicios
• ✅ Dashboards profesionales listos para usar (Node Exporter, Docker, Loki)
• ✅ Sistema de alertas configurado (CPU alto, memoria baja, disco lleno)

Tiempo de lectura: ~25 minutos | Nivel: Intermedio

¿Qué es la Observabilidad y Por Qué Necesitas Este Stack?

Observabilidad vs Monitoring: La Diferencia Clave

Monitoring (Monitoreo básico) es como Uptime Kuma: te dice que algo está caído, pero no el contexto completo. Es reactivo: «el servicio está offline».

Observabilidad es entender por qué está caído y qué pasó antes. Es proactivo: «el CPU subió al 95% hace 10 minutos, luego empezaron los errores de conexión en los logs, y finalmente el servicio se cayó».

Los 3 pilares de observabilidad:

1. Métricas: Datos numéricos medidos en intervalos regulares (CPU 85%, RAM 4.2GB)
2. Logs: Eventos con timestamp y contexto («ERROR: Database connection timeout»)
3. Trazas: Seguimiento de requests a través de servicios (no cubierto en este artículo, pero puedes añadir Tempo después)

¿Por Qué Este Stack y No Otros?

vs ELK Stack (Elasticsearch, Logstash, Kibana):

• ELK es más complejo (6-8 horas setup vs 1-2 horas)
• ELK requiere más recursos (4-8 GB RAM vs 2-4 GB)
• Este stack es más simple y suficiente para homelabs

vs Datadog/CloudWatch:

• Este stack es gratis (self-hosted) vs $31+/host/mes
• Control total de tus datos (todo local)
• Sin vendor lock-in

vs Uptime Kuma solo:

• Uptime Kuma: «está caído» ✅
• Este stack: «por qué está caído» + métricas históricas + logs ✅✅✅

Ideal si:

• Ya tienes Uptime Kuma y quieres métricas profundas
• Gestionas muchos servicios Docker y quieres entender su comportamiento
• Necesitas investigar problemas complejos (no solo «está caído»)
• Quieres gráficos profesionales y dashboards personalizables

Conceptos Fundamentales: Entendiendo el Stack

Prometheus: El Recolector de Métricas

Qué es:

Prometheus es un sistema de monitoreo y alerta open-source diseñado para la confiabilidad y escalabilidad. Fue creado en SoundCloud y ahora es un proyecto de la CNCF (Cloud Native Computing Foundation).

Cómo funciona:

• Pull Model: Prometheus «scrapea» (tira) métricas de los targets cada 15 segundos
• Time-Series Database: Almacena métricas como series temporales (valor + timestamp)
• PromQL: Lenguaje de consulta poderoso para analizar métricas
• Multi-dimensional: Las métricas tienen labels (etiquetas) para filtrar y agrupar

Componentes:

1. Prometheus Server: Recolecta y almacena métricas
2. Exporters: Aplicaciones que exponen métricas en formato Prometheus

– Node Exporter: Métricas del sistema (CPU, RAM, disco, red)

– cAdvisor: Métricas de contenedores Docker

1. Alertmanager: Gestiona alertas (opcional, no incluido en este tutorial básico)

Flujo típico:

1. Prometheus configura "scrape jobs" en prometheus.yml
2. Prometheus consulta /metrics de cada target cada 15s
3. Métricas se almacenan como time-series
4. Grafana consulta Prometheus con PromQL para visualizar
5. Si una alerta se dispara → Alertmanager → Notificación

Grafana: La Plataforma de Visualización

Qué es:

Grafana es una plataforma open-source de análisis y visualización de datos. Permite crear dashboards interactivos para múltiples fuentes de datos.

Características clave:

• Multi-datasource: Conecta a Prometheus, Loki, InfluxDB, MySQL, etc.
• Dashboards interactivos: Paneles configurables con gráficos, tablas, estadísticas
• Alertas: Alertas basadas en paneles o métricas
• Variables y templating: Dashboards dinámicos con dropdowns
• Provisioning: Configuración automática vía archivos YAML (sin tocar UI)

En este stack:

• Consulta métricas de Prometheus usando PromQL
• Visualiza logs de Loki usando LogQL
• Dashboards pre-configurados (Node Exporter, Docker, Loki logs)

Loki: El Agregador de Logs

Qué es:

Loki es un sistema de agregación de logs diseñado para ser altamente escalable y fácil de operar. Inspirado en Prometheus, usa labels para indexar logs en lugar de indexar el contenido completo.

Diferencia clave con ELK:

• ELK: Indexa el contenido completo de los logs → Más costoso en almacenamiento
• Loki: Solo indexa labels (metadata) → Logs comprimidos, almacenamiento eficiente

Promtail: El Agente de Logs

• Promtail es el agente que envía logs a Loki
• Similar a Logstash/Filebeat en ELK
• Lee logs de:

– Docker containers (stdout/stderr)

– Archivos de logs del sistema

– Journald (systemd logs)

Labels en Loki:

Los logs se organizan por labels (similar a Prometheus):

• Ejemplo: {job="docker", container="nginx", level="error"}
• Queries LogQL filtran por labels: {container="nginx"} |= "error"

Arquitectura del Stack: Cómo Fluye la Información

┌─────────────────────────────────────────────────────────────┐
│                     TUS SERVICIOS DOCKER                     │
│  (nginx, n8n, homeassistant, etc.)                          │
└──────────────┬──────────────────────────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
       ▼                ▼
┌─────────────┐  ┌──────────────┐
│ Node        │  │ cAdvisor     │
│ Exporter    │  │ (Docker      │
│ (Sistema)   │  │  containers) │
└──────┬──────┘  └──────┬───────┘
       │                │
       │                │
       └────────┬───────┘
                │
                ▼
        ┌───────────────┐
        │  Prometheus   │  ◄─── Scrapea métricas cada 15s
        │  (Métricas)   │
        └───────┬───────┘
                │
                │ PromQL queries
                ▼
        ┌───────────────┐
        │   Grafana     │  ◄─── Visualiza todo
        │(Dashboards)   │
        └───────┬───────┘
                │
                ▲
                │ LogQL queries
                │
        ┌───────┴───────┐
        │     Loki      │  ◄─── Almacena logs
        │    (Logs)     │
        └───────┬───────┘
                │
                ▲
                │ Push logs
                │
        ┌───────┴───────┐
        │   Promtail    │  ◄─── Lee logs de Docker
        │  (Agente)     │
        └───────────────┘

Recursos Necesarios

Mínimo (homelab pequeño):

• RAM: 2 GB
• CPU: 2 cores
• Disco: 20 GB (90 días métricas + 30 días logs)

Recomendado (homelab medio):

• RAM: 4 GB
• CPU: 4 cores
• Disco: 50 GB

Para homelab grande (50+ servicios):

• RAM: 8 GB
• CPU: 4+ cores
• Disco: 100+ GB

Instalación con Docker Compose: Stack Completo en 10 Minutos

Requisitos Previos

Antes de empezar, asegúrate de tener:

• Docker instalado: docker --version (v20.10+)
• Docker Compose instalado: docker compose version (v2.0+)
• 2-4 GB RAM libre
• 20 GB de espacio en disco

Verificar instalación:

docker --version
docker compose version

Si no tienes Docker, sigue nuestra guía de Docker para novatos.

Paso 1: Descargar y Preparar Archivos

Opción A: Desde GitHub (Recomendado)

Descarga el stack completo desde nuestro repositorio:

cd /home/z/learningaiagents/homelab/prometheus-grafana-loki

Opción B: Crear estructura manual

Si prefieres crear todo desde cero, sigue esta estructura:

mkdir -p observability-stack/{prometheus/alerts,grafana/{provisioning/{datasources,dashboards},dashboards},loki,promtail}
cd observability-stack

Paso 2: Crear docker-compose.yml

Crea docker-compose.yml en la raíz del proyecto:

version: '3.8'

services:
  # Prometheus: Recolección de métricas
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./prometheus/alerts:/etc/prometheus/alerts:ro
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--storage.tsdb.retention.time=90d'
      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
      - '--web.console.templates=/usr/share/prometheus/consoles'
    ports:
      - "9090:9090"
    networks:
      - observability

  # Grafana: Visualización
  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/provisioning/datasources:/etc/grafana/provisioning/datasources:ro
      - ./grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
      - ./grafana/dashboards:/var/lib/grafana/dashboards:ro
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
      - GF_USERS_ALLOW_SIGN_UP=false
    ports:
      - "3000:3000"
    networks:
      - observability
    depends_on:
      - prometheus
      - loki

  # Loki: Agregación de logs
  loki:
    image: grafana/loki:latest
    container_name: loki
    restart: unless-stopped
    volumes:
      - ./loki/loki-config.yml:/etc/loki/local-config.yaml:ro
      - loki_data:/loki
    command: -config.file=/etc/loki/local-config.yaml
    ports:
      - "3100:3100"
    networks:
      - observability

  # Promtail: Agente de logs
  promtail:
    image: grafana/promtail:latest
    container_name: promtail
    restart: unless-stopped
    volumes:
      - ./promtail/promtail-config.yml:/etc/promtail/config.yml:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    command: -config.file=/etc/promtail/config.yml
    networks:
      - observability
    depends_on:
      - loki

  # Node Exporter: Métricas del sistema
  node-exporter:
    image: prom/node-exporter:latest
    container_name: node-exporter
    restart: unless-stopped
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'
      - '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)'
    ports:
      - "9100:9100"
    networks:
      - observability

  # cAdvisor: Métricas de contenedores Docker
  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    restart: unless-stopped
    privileged: true
    devices:
      - /dev/kmsg
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    ports:
      - "8080:8080"
    networks:
      - observability

volumes:
  prometheus_data:
  grafana_data:
  loki_data:

networks:
  observability:
    driver: bridge

Explicación de componentes:

• Prometheus: Recolecta y almacena métricas (retención: 90 días)
• Grafana: Visualiza métricas y logs (puerto 3000)
• Loki: Almacena logs (puerto 3100)
• Promtail: Lee logs de Docker y los envía a Loki
• Node Exporter: Expone métricas del sistema operativo (CPU, RAM, disco, red)
• cAdvisor: Expone métricas de contenedores Docker (CPU, RAM, I/O por container)

Paso 3: Configurar Prometheus

Crea prometheus/prometheus.yml:

global:
  scrape_interval: 15s      # Frecuencia de scrape por defecto
  evaluation_interval: 15s  # Frecuencia de evaluación de alertas
  external_labels:
    cluster: 'homelab'
    environment: 'production'

# Configuración de Alertmanager (comentado por ahora)
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - alertmanager:9093  # Descomentar si añades Alertmanager

# Archivos de reglas de alertas
rule_files:
  - "/etc/prometheus/alerts/*.yml"

# Configuración de jobs para scrapear métricas
scrape_configs:
  # Prometheus self-monitoring
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
        labels:
          job: 'prometheus'

  # Node Exporter: Métricas del sistema
  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']
        labels:
          job: 'node-exporter'

  # cAdvisor: Métricas de contenedores Docker
  - job_name: 'cadvisor'
    static_configs:
      - targets: ['cadvisor:8080']
        labels:
          job: 'cadvisor'

Qué hace este archivo:

• Define cada 15 segundos scrapear métricas de los targets
• Configura 3 jobs: Prometheus (self-monitoring), Node Exporter (sistema), cAdvisor (Docker containers)
• Carga reglas de alertas desde prometheus/alerts/*.yml

Paso 4: Configurar Loki

Crea loki/loki-config.yml:

auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9096

common:
  instance_addr: 127.0.0.1
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

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

ruler:
  alertmanager_url: http://localhost:9093

# Retención de logs: 30 días
limits_config:
  retention_period: 720h
  enforce_metric_name: false
  reject_old_samples: true
  reject_old_samples_max_age: 168h

chunk_store_config:
  max_look_back_period: 720h

table_manager:
  retention_deletes_enabled: true
  retention_period: 720h

Configuración clave:

• Retención: 30 días (720 horas)
• Storage: Filesystem (simple para homelab)
• Sin autenticación (si expones externamente, añade autenticación)

Paso 5: Configurar Promtail

Crea promtail/promtail-config.yml:

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  # Scrape logs de contenedores Docker
  - job_name: docker
    docker_sd_configs:
      - host: unix:///var/run/docker.sock
        refresh_interval: 5s
    relabel_configs:
      - source_labels: ['__meta_docker_container_name']
        regex: '/(.*)'
        target_label: 'container'
      - source_labels: ['__meta_docker_container_log_stream']
        target_label: 'stream'
      - source_labels: ['__meta_docker_container_label_com_docker_compose_service']
        target_label: 'compose_service'

Qué hace:

• Se conecta al Docker socket para descubrir contenedores automáticamente
• Añade labels a los logs: container (nombre), stream (stdout/stderr), compose_service (si usa docker-compose)
• Envía logs a Loki cada vez que hay logs nuevos

Paso 6: Configurar Grafana Datasources (Provisioning Automático)

Crea grafana/provisioning/datasources/prometheus.yml:

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false
    jsonData:
      timeInterval: "15s"
      queryTimeout: "60s"
      httpMethod: POST

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100
    editable: false
    jsonData:
      maxLines: 1000

Qué hace:

• Configura automáticamente Prometheus y Loki como datasources en Grafana
• No necesitas configurarlos manualmente desde la UI
• isDefault: true hace que Prometheus sea el datasource por defecto

Crea grafana/provisioning/dashboards/default.yml:

apiVersion: 1

providers:
  - name: 'Default'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    updateIntervalSeconds: 10
    allowUiUpdates: true
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

Qué hace:

• Configura Grafana para cargar dashboards automáticamente desde /var/lib/grafana/dashboards
• Si añades dashboards JSON a esa carpeta, se importan automáticamente

Paso 7: Crear Archivos de Alertas (Opcional)

Crea prometheus/alerts/system.yml:

groups:
  - name: system_alerts
    interval: 30s
    rules:
      # Alerta: CPU alto
      - alert: HighCPUUsage
        expr: 100 - (avg by(instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "CPU usage is above 80%"
          description: "CPU usage on {{ $labels.instance }} is above 80% for more than 5 minutes"

      # Alerta: Memoria baja
      - alert: LowMemory
        expr: (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100 < 10
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Memory is running low"
          description: "Available memory on {{ $labels.instance }} is below 10%"

      # Alerta: Disco lleno
      - alert: DiskSpaceLow
        expr: (node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"}) * 100 < 15
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Disk space is running low"
          description: "Disk space on {{ $labels.instance }} is below 15%"

Qué hace:

• Define 3 alertas básicas: CPU alto, memoria baja, disco lleno
• Se evalúan cada 30 segundos
• Si se disparan, aparecen en Prometheus UI (Alertmanager opcional para notificaciones)

Paso 8: Iniciar el Stack

Una vez que todos los archivos están creados:

# Iniciar todos los servicios
docker compose up -d

# Verificar que todos están corriendo
docker compose ps

# Ver logs (si algo falla)
docker compose logs -f

Verificar que funciona:

1. Prometheus: Abre http://localhost:9090 → Deberías ver la UI de Prometheus
2. Grafana: Abre http://localhost:3000 → Login: admin / admin (o tu GRAFANA_PASSWORD)
3. Loki: Abre http://localhost:3100/ready → Debería responder «ready»

Si Grafana no muestra datasources:

• Espera 10-15 segundos (provisioning puede tardar)
• Verifica logs: docker logs grafana
• Verifica que los archivos YAML están en las rutas correctas

Configuración Inicial en Grafana: Primeros Pasos

Paso 1: Cambiar Password de Admin

Cuando accedas por primera vez a http://localhost:3000:

1. Grafana te pedirá cambiar el password
2. Introduce un password seguro
3. Guarda (puedes saltarte el email por ahora)

Paso 2: Verificar Datasources

1. Ve a Configuration → Data Sources
2. Deberías ver Prometheus y Loki ya configurados (gracias al provisioning)
3. Haz clic en «Prometheus» → «Save & Test» → Debería decir «Data source is working»
4. Repite con «Loki»

Si no aparecen:

• Verifica que los archivos YAML están en las rutas correctas
• Revisa logs: docker logs grafana | grep -i error
• Reinicia Grafana: docker restart grafana

Paso 3: Importar Dashboards Pre-configurados

Dashboard 1: Node Exporter Full

1. Ve a Dashboards → Import
2. Introduce ID: 1860
3. Selecciona datasource: Prometheus
4. Click «Import»

Este dashboard muestra:

• CPU usage (por core y total)
• Memory usage (RAM, swap)
• Disk I/O (read/write rates)
• Network I/O (bytes in/out)
• Filesystem usage (espacio por mountpoint)
• System load average

Dashboard 2: Docker Container & Host Metrics

1. Ve a Dashboards → Import
2. Introduce ID: 179
3. Selecciona datasource: Prometheus
4. Click «Import»

Este dashboard muestra:

• CPU usage por container
• Memory usage por container
• Network I/O por container
• Restart count de contenedores
• Uptime de contenedores

Dashboard 3: Loki Logs Dashboard

1. Ve a Dashboards → Import
2. Introduce ID: 15141
3. Selecciona datasource: Loki
4. Click «Import»

Este dashboard te permite:

• Explorar logs de todos tus contenedores
• Filtrar por container name
• Buscar por texto en logs
• Ver logs en tiempo real

Casos de Uso Prácticos: Monitorear tu Homelab Real

Caso 1: Monitorear Stack Docker Completo

Objetivo: Ver métricas y logs de todos tus contenedores Docker en un solo lugar.

Lo que ya tienes configurado:

• ✅ cAdvisor scrapeando métricas de todos los containers
• ✅ Promtail capturando logs de todos los containers

En Grafana:

1. Dashboard de Docker Containers (ID 179):

– Muestra CPU/Memory por container

– Identifica containers que consumen más recursos

– Ve restart counts (si un container se reinicia frecuentemente)

1. Loki Logs Dashboard:

– Selecciona un container del dropdown

– Ve logs en tiempo real

– Filtra por nivel (ERROR, WARN, INFO)

Ejemplo práctico:

• Ves que nginx tiene CPU alto en el dashboard
• Cambias a Loki logs dashboard
• Filtas por {container="nginx"} y buscas «error»
• Encuentras: «upstream timeout» → Problema identificado

Caso 2: Detección Proactiva de Problemas

Escenario: Detectar problemas antes de que los servicios se caigan.

Alertas configuradas:

• CPU > 80% por 5 minutos → Warning
• RAM disponible < 10% → Critical
• Disk space < 15% → Warning

Flujo:

1. Prometheus evalúa alertas cada 15 segundos
2. Si CPU sube > 80%, se dispara alerta «HighCPUUsage»
3. Ve a Prometheus UI → Alerts → Ver alertas activas
4. Cambia a Grafana → Dashboards → Ver gráficos de CPU
5. Cambia a Loki → Ver logs del periodo de alto CPU
6. Identificas el problema antes de que se caiga el servicio

Ejemplo:

14:00 - CPU normal (30%)
14:15 - CPU empieza a subir (60%)
14:20 - Alerta disparada: CPU > 80%
14:20 - Revisas logs: "ERROR: Database connection pool exhausted"
14:25 - Problema identificado: conexiones DB no se cierran
14:30 - Aplicas fix: aumentar pool size
14:35 - CPU vuelve a normal (40%)

Caso 3: Monitorear Servicio Específico (ej: n8n)

Si tienes n8n u otro servicio que expone métricas en /metrics:

Añadir scrape config en Prometheus:

Edita prometheus/prometheus.yml y añade:

# n8n metrics (si expone /metrics endpoint)
  - job_name: 'n8n'
    static_configs:
      - targets: ['n8n:5678']  # Ajusta puerto si es diferente
        labels:
          job: 'n8n'

Reiniciar Prometheus:

docker restart prometheus

Configurar Promtail para logs específicos de n8n:

Ya está configurado automáticamente si n8n corre en Docker. Los logs aparecerán en Loki con label {container="n8n"}.

Crear dashboard personalizado en Grafana:

1. Dashboards → New Dashboard
2. Añade paneles con queries PromQL:

– CPU: rate(container_cpu_usage_seconds_total{name="n8n"}[5m])

– Memory: container_memory_usage_bytes{name="n8n"}

1. Añade panel de logs:

– Data source: Loki

– Query: {container="n8n"}

– Visualización: Logs

Comparativas: ¿Es Este Stack el Mejor para Ti?

Prometheus + Grafana + Loki vs ELK Stack

Elige este stack si: Quieres métricas y logs juntos, simplicidad, eficiencia en recursos.

Elige ELK si: Necesitas análisis de texto avanzado, full-text search en logs, análisis de logs muy complejos.

Prometheus + Grafana + Loki vs Datadog

Elige este stack si: Homelab, control total, sin coste, datos locales.

Elige Datadog si: Empresa con presupuesto, no quieres mantener infraestructura, necesitas soporte enterprise.

Prometheus + Grafana + Loki vs CloudWatch

Elige este stack si: No estás en AWS, quieres dashboards potentes, sin vendor lock-in.

Elige CloudWatch si: Todo está en AWS, necesitas integración nativa AWS, presupuesto para logs.

Mejores Prácticas y Optimización

Retención de Datos: Cuánto Tiempo Guardar

Por defecto:

• Prometheus: 90 días de métricas
• Loki: 30 días de logs

Para homelab pequeño (<10 servicios):

• Prometheus: 30 días es suficiente
• Loki: 14 días de logs

Para homelab medio (10-30 servicios):

• Prometheus: 60 días
• Loki: 30 días

Para homelab grande (30+ servicios):

• Prometheus: 90 días
• Loki: 30-60 días

Modificar retención:

Prometheus:

Edita docker-compose.yml:

command:
  - '--storage.tsdb.retention.time=30d'  # Cambiar de 90d a 30d

Loki:

Edita loki/loki-config.yml:

limits_config:
  retention_period: 336h  # 14 días en lugar de 720h (30 días)

Optimización de Recursos

Si consumes mucha RAM:

1. Reducir scrape_interval:

global:
     scrape_interval: 30s  # En lugar de 15s

1. Limitar métricas scrapeadas:

Usa metric_relabel_configs para filtrar métricas innecesarias en prometheus.yml

1. Reducir retención de datos (ver arriba)

Si consumes mucho disco:

1. Reducir retención (ver arriba)
2. Comprimir datos (Loki ya comprime automáticamente)
3. Usar storage externo (S3, etc.) si tienes mucho espacio

Seguridad Básica

Si expones Grafana externamente:

1. Cambiar password de admin (obligatorio)
2. Añadir autenticación reverse proxy (Nginx Proxy Manager, Traefik)
3. Usar HTTPS (certificados Let’s Encrypt)
4. Firewall: Solo permitir acceso desde IPs conocidas

Recomendación: No expongas Prometheus/Loki directamente. Accede vía Grafana solo.

Backups de Configuraciones

Qué hacer backup:

• Todo el directorio del proyecto (docker-compose.yml, configs)
• Dashboards de Grafana (exportar JSON)

Script de backup básico:

#!/bin/bash
# backup-observability.sh

BACKUP_DIR="/backups/observability"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Backup configuraciones
tar -czf "$BACKUP_DIR/observability-configs-$DATE.tar.gz" \
  docker-compose.yml \
  prometheus/ \
  grafana/provisioning/ \
  loki/ \
  promtail/

# Backup dashboards de Grafana (si exportaste JSONs)
if [ -d "grafana/dashboards" ]; then
  tar -czf "$BACKUP_DIR/grafana-dashboards-$DATE.tar.gz" \
    grafana/dashboards/
fi

# Limpiar backups antiguos (>30 días)
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

echo "✅ Backup completado: $BACKUP_DIR/observability-configs-$DATE.tar.gz"

Ejecutar automáticamente:

Añade a crontab (crontab -e):

0 2 * * * /ruta/a/backup-observability.sh

Troubleshooting Común: Soluciones Rápidas

Problema 1: Prometheus no scrapea métricas

Síntomas:

• No aparecen métricas en Grafana
• Targets aparecen como «DOWN» en Prometheus UI (http://localhost:9090/targets)

Diagnóstico:

# Verificar que Prometheus puede alcanzar los targets
docker exec prometheus wget -qO- http://node-exporter:9100/metrics | head -5

# Verificar logs de Prometheus
docker logs prometheus | grep -i error

# Verificar configuración de red
docker network inspect observability | grep -A 5 "Containers"

Soluciones:

1. Verificar que todos los servicios están en la misma network:

docker network inspect observability

Todos deben aparecer en la misma network observability.

1. Verificar targets en Prometheus UI:

– Ve a http://localhost:9090/targets

– Si un target está DOWN, haz clic para ver el error

1. Verificar URLs en prometheus.yml:

– Los targets deben usar nombres de servicios Docker: node-exporter:9100

– NO usar localhost (Prometheus está en un container)

Problema 2: Grafana no muestra datos

Síntomas:

• Dashboard vacío
• Error «Data source not found» o «Query timeout»

Diagnóstico:

# Verificar que Grafana puede alcanzar Prometheus
docker exec grafana wget -qO- http://prometheus:9090/api/v1/query?query=up

# Verificar logs de Grafana
docker logs grafana | grep -i error

# Verificar datasources
# En Grafana UI: Configuration → Data Sources

Soluciones:

1. Verificar provisioning de datasources:

– Archivo debe estar en: grafana/provisioning/datasources/prometheus.yml

– URL debe usar nombre de servicio: http://prometheus:9090 (NO localhost)

1. Reiniciar Grafana:

docker restart grafana

Espera 10-15 segundos para que el provisioning se ejecute.

1. Probar query manualmente:

– En Grafana: Explore → Prometheus

– Query: up

– Debería devolver resultados si Prometheus funciona

Problema 3: Loki no recibe logs

Síntomas:

• No aparecen logs en Grafana cuando consultas Loki
• Promtail no envía logs a Loki

Diagnóstico:

# Verificar que Promtail está corriendo
docker ps | grep promtail

# Verificar logs de Promtail
docker logs promtail | grep -i error

# Verificar que Promtail puede acceder a Docker socket
docker exec promtail ls -la /var/run/docker.sock

# Verificar que Loki está accesible
docker exec promtail wget -qO- http://loki:3100/ready

Soluciones:

1. Verificar acceso a Docker socket:

# En docker-compose.yml, promtail debe tener:
   volumes:
     - /var/run/docker.sock:/var/run/docker.sock:ro

1. Verificar URL de Loki en promtail-config.yml:

clients:
     - url: http://loki:3100/loki/api/v1/push

Debe usar nombre de servicio loki, NO localhost.

1. Verificar que hay contenedores Docker:

docker ps

Si no hay contenedores, Promtail no tiene logs que capturar.

1. Reiniciar Promtail:

docker restart promtail

Problema 4: Alta utilización de recursos

Síntomas:

• Stack consume mucha RAM (>4GB)
• CPU usage alto constante
• Disco llenándose rápidamente

Diagnóstico:

# Ver uso de recursos por container
docker stats

# Ver tamaño de volúmenes
docker system df -v

Soluciones:

1. Reducir retención de datos (ver sección Mejores Prácticas)

1. Aumentar scrape_interval:

# En prometheus.yml:
   global:
     scrape_interval: 30s  # En lugar de 15s

1. Limitar cantidad de métricas:

– Usa metric_relabel_configs para filtrar métricas innecesarias

– Desactiva collectors de Node Exporter que no necesites

1. Optimizar Loki:

– Reduce retention_period

– Usa compresión (ya está activada por defecto)

Problema 5: Dashboards no se importan

Síntomas:

• Al importar dashboard por ID, aparece error
• Datasource no se asigna correctamente

Soluciones:

1. Verificar que datasources están configurados:

– Configuration → Data Sources

– Prometheus y Loki deben aparecer

1. Asignar datasource manualmente al importar:

– Al importar dashboard, selecciona datasource en el dropdown

– Si no aparece, verifica que el provisioning funcionó

1. Importar dashboard por JSON en lugar de ID:

– Descarga JSON del dashboard desde grafana.com

– Dashboards → Import → Upload JSON file

Preguntas Frecuentes

¿Puedo usar esto junto con Uptime Kuma?

Sí, absolutamente. Uptime Kuma y este stack se complementan:

• Uptime Kuma: «¿Está caído?» (uptime monitoring)
• Este stack: «¿Por qué está caído?» (métricas profundas + logs)

Puedes tener ambos corriendo sin conflicto. Uptime Kuma monitorea endpoints, este stack monitorea métricas y logs.

¿Cuánta RAM/CPU necesito?

Mínimo:

• RAM: 2 GB
• CPU: 2 cores

Recomendado:

• RAM: 4 GB
• CPU: 4 cores

Para homelab grande (50+ servicios):

• RAM: 8 GB
• CPU: 4+ cores

Si tienes menos recursos, reduce retención de datos y aumenta scrape_interval.

¿Cómo hago backup de mis datos?

Configuraciones:

• Backup todo el directorio del proyecto (docker-compose.yml, configs)
• Usa Git para versionar configuraciones

Datos históricos:

• Los volúmenes Docker contienen los datos
• Backup de volúmenes: docker run --rm -v prometheus_data:/data -v $(pwd):/backup alpine tar czf /backup/prometheus-backup.tar.gz /data
• Restaurar: docker run --rm -v prometheus_data:/data -v $(pwd):/backup alpine tar xzf /backup/prometheus-backup.tar.gz -C /

Dashboards:

• Exporta dashboards como JSON desde Grafana UI
• Guarda en Git o en carpeta de backups

¿Puedo monitorear servicios fuera de Docker?

Sí:

1. Para servicios con endpoint /metrics:

– Añade job en prometheus/prometheus.yml:

- job_name: 'mi-servicio'
     static_configs:
       - targets: ['IP-DEL-SERVIDOR:PUERTO']

1. Para logs de servicios no-Docker:

– Configura Promtail para leer archivos de logs:

- job_name: archivos
     static_configs:
       - targets:
           - localhost
         labels:
           job: archivos
           __path__: /var/log/mi-servicio/*.log

¿Loki reemplaza a ELK?

No completamente. Depende de tus necesidades:

• Loki es mejor si: Quieres simplicidad, eficiencia, integración con Prometheus/Grafana
• ELK es mejor si: Necesitas análisis de texto avanzado, full-text search complejo, análisis de logs muy profundo

Para la mayoría de homelabs, Loki es suficiente y más simple.

¿Qué diferencia hay entre Prometheus y Grafana?

Prometheus:

• Recolecta y almacena métricas
• Time-series database
• Lenguaje de consulta: PromQL

Grafana:

• Visualiza datos (métricas y logs)
• Crea dashboards interactivos
• Conecta a múltiples datasources (Prometheus, Loki, MySQL, etc.)

Analogía: Prometheus es la base de datos, Grafana es Excel/Tableau.

¿Cuánto tiempo de retención necesito?

Para homelab:

• Métricas: 30-90 días (depende de espacio)
• Logs: 14-30 días

Para debugging:

• Métricas: 7-14 días suele ser suficiente
• Logs: 7 días es suficiente para troubleshooting

Recomendación: Empieza con 30 días de métricas y 14 días de logs. Ajusta según necesites.

¿Cómo escalo si tengo muchos servicios?

Opciones:

1. Aumentar recursos del servidor (RAM, CPU, disco)
2. Reducir retención (menos datos = menos recursos)
3. Aumentar scrape_interval (menos frecuencia = menos carga)
4. Filtrar métricas innecesarias (metric_relabel_configs)
5. Usar Prometheus federation (múltiples instancias de Prometheus)

Para homelabs típicos (<100 servicios), un solo servidor es suficiente.

¿Puedo usar esto en producción?

Sí, pero:

Ventajas:

• Stack usado en producción por muchas empresas
• Escalable y confiable
• Open-source y mantenido activamente

Consideraciones:

• Necesitas mantenerlo (updates, backups)
• Alta disponibilidad requiere setup adicional (múltiples instancias)
• Seguridad: añade autenticación, HTTPS, firewall

Para producción pequeña/media: Este stack básico es suficiente.

Para producción crítica: Considera alta disponibilidad, Alertmanager para notificaciones, backup automatizado.

Conclusión: Tu Stack de Observabilidad Está Listo

Has montado un stack de observabilidad completo y profesional en tu homelab. Ahora tienes:

✅ Métricas profundas del sistema y contenedores Docker

✅ Logs centralizados de todos tus servicios

✅ Dashboards profesionales listos para usar

✅ Alertas básicas configuradas

✅ Control total de tus datos (self-hosted, gratis)

Próximos pasos sugeridos:

1. Personalizar dashboards según tus necesidades específicas
2. Añadir Alertmanager para notificaciones Discord/Telegram (artículo futuro)
3. Integrar con más servicios (añadir scrape configs para servicios que expongan /metrics)
4. Añadir Tempo para traces (completar el stack de observabilidad)
5. Backup automatizado de configuraciones y datos

📦 Descargar Ejemplos

Todo el código de este artículo está disponible en GitHub:

https://github.com/ziruelen/learningaiagents/tree/main/homelab/prometheus-grafana-loki-observabilidad-homelab

Incluye:

• docker-compose.yml completo
• Todas las configuraciones (Prometheus, Grafana, Loki, Promtail)
• Alertas de ejemplo
• README con instrucciones detalladas

🔗 Artículos Relacionados:

Continúa aprendiendo con estas guías complementarias:

• Uptime Kuma: Monitoreo Self-Hosted para Homelab – Complemento perfecto: monitoreo de uptime junto con métricas profundas
• Docker Compose: De 0 a Homelab Completo – Aprende Docker Compose desde cero si eres nuevo
• Homelab desde Cero: Guía Completa 2025 – Todo lo que necesitas para empezar tu homelab
• Portainer: Gestiona Docker con Interfaz Web – Gestiona tus contenedores Docker fácilmente
• Nginx Proxy Manager: Reverse Proxy con SSL Automático – Expón Grafana y Prometheus de forma segura
• TrueNAS Scale: NAS Potente con Docker y ZFS – Storage para tus volúmenes de datos
• n8n Database Workflows: PostgreSQL, MySQL, MongoDB – Monitorea tus bases de datos con este stack
• GitLab Self-Hosted: CI/CD Completo en tu Homelab – Monitorea tus pipelines CI/CD

¿Tienes preguntas o problemas?

Comenta abajo o pregunta en nuestra comunidad. Si encuentras un problema específico, comparte logs y configuración y te ayudo a resolverlo.

¡Feliz observabilidad! 📊🔍