Prometheus y Grafana

Instalar Prometheus, Node Exporter y Grafana para monitorear tu stake pool. Incluye el dashboard TOPO⚡ listo para importar.

Vamos a levantar un stack de monitoreo completo que te da visibilidad en tiempo real sobre el estado de tus nodos: métricas de cardano-node, sistema (CPU, RAM, disco, red) y métricas de pool (stake, delegadores, bloques, ROA).

---

Arquitectura del setup

cardano-node ──── puerto 12798 ─────┐
                                    ├──► Prometheus ──► Grafana ──► Dashboard TOPO⚡
node_exporter ─── puerto 9100 ──────┘
pool-exporter ─── (opcional) ───────┘

El servidor de monitoreo puede ser el mismo relay o una VM separada. Si lo ponés en el mismo relay, Prometheus scrapea localhost; si es una VM aparte, abrís los puertos de métricas solo hacia esa IP.

En esta guía asumimos que el servidor de monitoreo corre en la misma máquina que el relay, o que tenés acceso a la IP privada del relay desde el servidor de monitoreo.

---

1. Verificar la configuración de cardano-node

El nodo ya expone métricas si el config.json tiene configurados estos campos:

"hasPrometheus": ["127.0.0.1", 12798],
"hasEKG": 12789

Verificamos qué endpoint tiene las métricas:

# Puerto Prometheus (legacy tracing — lo más común)
curl -s http://127.0.0.1:12798 | head -5

# Puerto EKG (JSON — nuevo tracing backend o fallback)
curl -s http://127.0.0.1:12789 | jq '.cardano.node.metrics' 2>/dev/null | head -10

Si el puerto 12798 responde con líneas tipo cardano_node_metrics_epoch_int 523, usá ese como scrape target en Prometheus (es lo que hacemos en esta guía).

Si 12798 está vacío y todo está en 12789, el nodo usa el nuevo tracing backend (cardano-tracer). En ese caso el scrape target en prometheus.yml debe apuntar al puerto que cardano-tracer exponga para Prometheus — típicamente también 12798 pero servido por el tracer, no por el nodo directamente. El resultado en Grafana es el mismo.

El bind de hasPrometheus está en 127.0.0.1 — solo accesible localmente. Si el servidor de monitoreo es una VM separada, cambia a 0.0.0.0 y agrega la IP del servidor de monitoreo al firewall.

---

2. Instalar Node Exporter

Node Exporter expone métricas del sistema operativo: CPU, RAM, disco, red y tiempo de sincronización NTP.

# Descargar la última versión
NODE_EXPORTER_VERSION="1.8.2"
wget https://github.com/prometheus/node_exporter/releases/download/v${NODE_EXPORTER_VERSION}/node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz
tar xzf node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz
sudo cp node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64/node_exporter /usr/local/bin/

Crear el servicio systemd:

sudo tee /etc/systemd/system/node_exporter.service > /dev/null << 'EOF'
[Unit]
Description=Node Exporter
After=network.target

[Service]
Type=simple
User=TU_USUARIO
ExecStart=/usr/local/bin/node_exporter \
  --collector.systemd \
  --collector.processes \
  --web.listen-address=127.0.0.1:9100
StandardOutput=journal
StandardError=journal
SyslogIdentifier=node_exporter
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable node_exporter
sudo systemctl start node_exporter

Verificar:

curl -s http://127.0.0.1:9100/metrics | grep node_cpu | head -5

---

3. Instalar Prometheus

PROMETHEUS_VERSION="2.53.0"
wget https://github.com/prometheus/prometheus/releases/download/v${PROMETHEUS_VERSION}/prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz
tar xzf prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz
sudo cp prometheus-${PROMETHEUS_VERSION}.linux-amd64/{prometheus,promtool} /usr/local/bin/
sudo mkdir -p /etc/prometheus /var/lib/prometheus

Configuración de Prometheus

sudo tee /etc/prometheus/prometheus.yml > /dev/null << 'EOF'
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'cardano'
    static_configs:
      - targets:
          - 'localhost:12798'
        labels:
          alias: 'RELAY'
      # Si tienes BP accesible:
      # - targets: ['IP-BP:12798']
      #   labels:
      #     alias: 'CORE'

  - job_name: 'node'
    static_configs:
      - targets:
          - 'localhost:9100'
        labels:
          alias: 'RELAY'
      # - targets: ['IP-BP:9100']
      #   labels:
      #     alias: 'CORE'
EOF

El campo alias en los labels es el que usa el dashboard TOPO⚡ para distinguir entre nodos. Usa RELAY para el relay y CORE para el block producer.

Crear el servicio systemd:

sudo tee /etc/systemd/system/prometheus.service > /dev/null << 'EOF'
[Unit]
Description=Prometheus
After=network.target

[Service]
Type=simple
User=TU_USUARIO
ExecStart=/usr/local/bin/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus \
  --storage.tsdb.retention.time=90d \
  --web.listen-address=127.0.0.1:9090
StandardOutput=journal
StandardError=journal
SyslogIdentifier=prometheus
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo chown -R TU_USUARIO:TU_USUARIO /var/lib/prometheus
sudo systemctl daemon-reload
sudo systemctl enable prometheus
sudo systemctl start prometheus

Verificar que Prometheus levantó y puede scrape los targets:

curl -s http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, state: .health}'

---

4. Instalar Grafana

sudo apt-get install -y apt-transport-https software-properties-common
wget -q -O - https://apt.grafana.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/grafana.key
echo "deb [signed-by=/usr/share/keyrings/grafana.key] https://apt.grafana.com stable main" \
  | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install -y grafana

sudo systemctl daemon-reload
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

Grafana queda en el puerto 3000. Para acceder desde tu máquina local, abrí un túnel SSH:

ssh -L 3000:localhost:3000 tu_usuario@IP-DEL-SERVIDOR

Luego abrí http://localhost:3000 en el browser. Login por defecto: admin / admin.

No expongas el puerto 3000 a internet. Usá siempre el túnel SSH o un proxy inverso con autenticación.

---

5. Configurar Prometheus como datasource en Grafana

1. En Grafana: Configuration → Data sources → Add data source

2. Selecciona Prometheus

3. URL: http://localhost:9090

4. Clic en Save & test — debe aparecer "Data source is working"

---

6. Importar el dashboard TOPO⚡

El dashboard incluye:

Panel	Qué muestra
Epoch / Block Height / Tip	Estado actual de la cadena
KES Expiration	Tiempo restante hasta vencimiento de KES
Pool Performance	% de bloques forjados vs asignados
Saturation	% de saturación del pool
CPU / RAM / Disk / Network	Recursos del sistema por nodo
Mempool	Transacciones y bytes en mempool
Block delay / Late blocks	Salud de la red P2P
P2P Connections	Conexiones por tipo (duplex, unidirectional, incoming)
Stake Metrics / ROA	Stake activo, delegadores, retorno
Time Sync	Sincronización NTP — crítico para la forja de bloques

Cómo importar

1. En Grafana: Dashboards → Import

2. Clic en Upload JSON file

3. Selecciona el archivo topo-dashboard.json (disponible en este repositorio en kb/monitoreo/)

4. En prometheus, selecciona el datasource que acabás de crear

5. Clic en Import

---

7. Métricas custom del pool

Los paneles de Stake Metrics, Delegators, Blocks Minted, Saturation, Rank y ROA usan métricas que no vienen del nodo directamente — vienen de un script que consulta la API de Koios y expone los datos vía un exporter personalizado.

Las métricas son:

saturation        delegators        blocks_lifetime
blocks_epoch      blocks_est_epoch  roa / roa_short
stake             stake_active      pledged
position          tx_submit_count   tx_submit_fail_count

Si estos paneles aparecen vacíos, instalá el pool-exporter: un script bash que consulta Koios y escribe las métricas en un archivo .prom que node_exporter ya sirve en :9100. Sin puerto extra ni cambios en prometheus.yml. Ver guía completa: Pool Exporter (Koios → Prometheus).

---

8. Alertas básicas recomendadas

El dashboard ya tiene condiciones de alerta pre-configuradas para:

• CPU > 75% sostenido por 5 minutos

• RAM > 16 GB

• Chain density < 4% (nodo fuera de sync)

• Time sync > 5 segundos (problema NTP grave)

Para recibir las alertas por email o Telegram, configurá un Contact point en Grafana: Alerting → Contact points → Add contact point.

---

Checklist final

✅ cardano-node expone métricas en :12798
✅ node_exporter corriendo en :9100
✅ Prometheus scrapeando ambos (ver /targets)
✅ Grafana instalado y accesible via túnel SSH
✅ Datasource Prometheus configurado y funcionando
✅ Dashboard TOPO⚡ importado
✅ Verificar que KES Expiration muestra tiempo correcto
✅ Verificar que CPU/RAM/Disk muestran datos del relay