Admin-Sistemas ·

Implementación paso a paso de un Exporter personalizado de métricas de hardware

En entornos de producción es fundamental disponer de métricas de hardware precisas para anticipar fallos y optimizar recursos. Node Exporter es el agente oficial de Prometheus para exponer métricas del sistema, pero a veces necesitamos datos que no están incluidos por defecto, como la temperatura de la CPU o lecturas específicas de discos SSD. En este artículo describiremos, paso a paso, cómo crear un exporter personalizado usando scripts Bash y Python, integrarlo con Node Exporter mediante un collector externo, visualizarlas en Grafana y generar alertas con Alertmanager.

1. Preparación del entorno

1.1. Requisitos previos

  • Servidor Linux (Ubuntu 22.04 LTS recomendado).
  • Prometheus 2.x instalado y configurado.
  • Node Exporter 1.6+ en ejecución.
  • Grafana 9.x y Alertmanager 0.27+.
  • Paquetes python3, pip, lm-sensors y smartmontools.

1.2. Instalación de dependencias

sudo apt update
sudo apt install -y prometheus-node-exporter python3-pip lm-sensors smartmontools
# Habilitar sensores
sudo sensors-detect --auto
sudo systemctl restart prometheus-node-exporter

1.3. Verificar que Node Exporter funciona

curl -s http://localhost:9100/metrics | grep node_cpu_seconds_total | head

Deberías ver líneas similares a node_cpu_seconds_total{cpu="0",mode="user"} 12345.67.

2. Creación del script de recolección personalizado

2.1. Estructura del proyecto

mkdir -p /opt/custom_exporter
cd /opt/custom_exporter
# Archivo principal
touch hardware_exporter.py
# Wrapper para Node Exporter
touch collector.sh
chmod +x collector.sh hardware_exporter.py

2.2. Script Python: hardware_exporter.py

Este script recopila tres tipos de datos:

  1. Uso de CPU (porcentaje).
  2. Temperatura de la CPU (usando sensors).
  3. Estado y temperatura de discos (usando smartctl).
#!/usr/bin/env python3
import subprocess
import re
import sys

def run_cmd(cmd): result = subprocess.run(cmd, shell=True, capture_output=True, text=True) if result.returncode != 0: sys.stderr.write(f”Error ejecutando {cmd}: {result.stderr}\n”) return "" return result.stdout.strip()

def cpu_usage(): # Promedio de uso de CPU en los últimos 1 minuto (load average) load = run_cmd(“cat /proc/loadavg”).split()[0] # Convertir a porcentaje respecto al número de CPUs cpu_count = int(run_cmd(“nproc”)) usage = (float(load) / cpu_count) * 100 return f”custom_cpu_usage_percent {usage:.2f}”

def cpu_temp(): out = run_cmd(“sensors”) # Buscar líneas tipo “Package id 0: +45.0°C (high = +100.0°C)” m = re.search(r’Package id 0:\s++([0-9.]+)°C’, out) if m: return f”custom_cpu_temperature_celsius {m.group(1)}” return ”# No se encontró temperatura de CPU”

def disk_stats(): # Enumerar discos con /dev/sd* y /dev/nvme* disks = run_cmd(“lsblk -dn -o NAME,TYPE | awk ‘$2==“disk” {print $1}’”) lines = [] for d in disks.splitlines(): dev = f”/dev/{d}” # Temperatura con smartctl (requiere privilegios) temp_out = run_cmd(f”smartctl -A {dev} | grep -i temperature”) temp_match = re.search(r’Temperature_Celsius\s+\d+\s+(\d+)’, temp_out) if temp_match: temp = temp_match.group(1) lines.append(f’custom_disk_temperature_celsius{{device=“{dev}”}} {temp}’) # Estado SMART health = run_cmd(f”smartctl -H {dev} | grep -i result”) health = “0” if “PASSED” in health.upper() else “1” lines.append(f’custom_disk_health{{device=“{dev}”}} {health}’) return “\n”.join(lines) if lines else ”# No se encontraron discos”

if name == “main”: metrics = [ cpu_usage(), cpu_temp(), disk_stats() ] print(“\n”.join(metrics))

2.3. Wrapper Bash: collector.sh

Node Exporter permite ejecutar colecciones externas mediante la opción --collector.textfile.directory. El wrapper escribe la salida del script Python en un archivo .prom dentro de ese directorio.

#!/usr/bin/env bash
# Directorio de textfiles que Node Exporter escanea
TEXTFILE_DIR="/var/lib/node_exporter/textfile_collector"
EXPORT_FILE="${TEXTFILE_DIR}/custom_hardware.prom"

Asegurarse de que el directorio exista y tenga permisos correctos

mkdir -p “$TEXTFILE_DIR” chown node_exporter:node_exporter “$TEXTFILE_DIR”

Ejecutar el script Python y capturar salida

/usr/bin/python3 /opt/custom_exporter/hardware_exporter.py > “$EXPORT_FILE.tmp”

Verificar si el script devolvió algún error

if [ $? -ne 0 ]; then echo “Error al generar métricas personalizadas” > /var/log/custom_exporter_error.log exit 1 fi

Reemplazar atomícamente el archivo anterior

mv “$EXPORT_FILE.tmp” “$EXPORT_FILE” chmod 644 “$EXPORT_FILE” chown node_exporter:node_exporter “$EXPORT_FILE”

2.4. Programar la ejecución periódica

Usaremos systemd para ejecutar el wrapper cada minuto.

cat > /etc/systemd/system/custom_exporter.service <<EOF
[Unit]
Description=Custom hardware exporter for Node Exporter
After=network.target

[Service] Type=oneshot ExecStart=/opt/custom_exporter/collector.sh User=root Group=root

[Install] WantedBy=multi-user.target EOF

cat > /etc/systemd/system/custom_exporter.timer <<EOF [Unit] Description=Run custom_exporter.service every minute

[Timer] OnBootSec=30sec OnUnitActiveSec=60sec Unit=custom_exporter.service

[Install] WantedBy=timers.target EOF

systemctl daemon-reload systemctl enable —now custom_exporter.timer

Con esto, cada minuto se actualizará /var/lib/node_exporter/textfile_collector/custom_hardware.prom y Node Exporter lo expondrá automáticamente.

3. Configuración de Prometheus y Grafana

3.1. Añadir el target en prometheus.yml

scrape_configs:
  - job_name: 'node_exporter'
    static_configs:
      - targets: ['localhost:9100']
    metrics_path: /metrics
    # No es necesario cambiar nada, el collector de textfile ya está habilitado por defecto

Reinicia Prometheus:

systemctl restart prometheus

3.2. Verificar que Prometheus recibe las nuevas métricas

curl -s http://localhost:9090/api/v1/label/__name__/values | grep custom_

Deberías ver:

custom_cpu_usage_percent
custom_cpu_temperature_celsius
custom_disk_temperature_celsius
custom_disk_health

3.3. Crear paneles en Grafana

  1. Accede a Grafana (http://grafana-host:3000) y crea un nuevo Dashboard.
  2. Añade un panel Graph para la CPU:
    • Query: custom_cpu_usage_percent
    • Tipo: Gauge
    • Umbral: 80% (warning), 95% (critical).
  3. Panel de temperatura de CPU:
    • Query: custom_cpu_temperature_celsius
    • Display: Stat
    • Alertas: >70°C warning, >85°C critical.
  4. Panel de discos:
    • Query: custom_disk_temperature_celsius{device="/dev/sda"}
    • Grafica como Bar gauge por dispositivo.
    • Alertas de salud: custom_disk_health == 1 (SMART failed).

4. Configuración de Alertas con Alertmanager

4.1. Regla de alerta en Prometheus

groups:
  - name: hardware_alerts
    rules:
      - alert: HighCPUUsage
        expr: custom_cpu_usage_percent > 85
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Uso de CPU alto en {{ $labels.instance }}"
          description: "CPU al {{ $value }}% durante más de 2 minutos."
  - alert: CpuOverheat
    expr: custom_cpu_temperature_celsius &gt; 80
    for: 1m
    labels:
      severity: warning
    annotations:
      summary: "Temperatura de CPU elevada"
      description: "Temperatura actual {{ $value }}°C."

  - alert: DiskSmartFailed
    expr: custom_disk_health == 1
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "SMART falló en {{ $labels.device }}"
      description: "El disco {{ $labels.device }} reportó fallo en SMART."

4.2. Envío de alertas a Alertmanager

Asegúrate de que en prometheus.yml exista la sección:

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['localhost:9093']

4.3. Configuración básica de Alertmanager

global:
  resolve_timeout: 5m

route: receiver: ‘mail’ group_wait: 30s group_interval: 5m repeat_interval: 12h

receivers:

Reinicia ambos servicios:

systemctl restart prometheus
systemctl restart alertmanager

5. Troubleshooting y errores comunes

5.1. Métrica no aparece en Prometheus

  • Síntaxis del archivo .prom: cualquier línea que no cumpla el formato name{label="value"} value será descartada. Revisa /var/log/custom_exporter_error.log y el contenido del archivo temporal.
  • Permisos: El directorio /var/lib/node_exporter/textfile_collector debe ser propiedad de node_exporter. Usa chown como se mostró.
  • Cache de Node Exporter: Si modificas el script, fuerza una recarga borrando el archivo .prom y esperando el próximo ciclo del timer.

5.2. Smartctl devuelve errores de permiso

Smartctl necesita privilegios de root para acceder a algunos discos. Puedes:

  • Añadir node_exporter al grupo disk y establecer setuid en el binario (cuidado con seguridad).
  • Ejecutar el script como root dentro del service (como se muestra). Si prefieres menor exposición, crea un sudoers limitado:
node_exporter ALL=(root) NOPASSWD: /usr/sbin/smartctl

5.3. Temperatura no se detecta en algunos hardware

Algunos servidores usan ipmi-sensors en lugar de lm-sensors. En ese caso, sustituye la función cpu_temp por:

def cpu_temp():
    out = run_cmd("ipmitool sensor get \"CPU Temp\" | grep \"Reading\"")
    m = re.search(r'Reading\\s*:\\s*([0-9.]+)', out)
    if m:
        return f"custom_cpu_temperature_celsius {m.group(1)}"
    return "# Temperatura no encontrada"

5.4. Alertas no se envían

  • Verifica la conectividad al puerto 9093 desde Prometheus.
  • En Alertmanager, comprueba el estado con curl http://localhost:9093/api/v2/alerts.
  • Revisa los logs de Prometheus (/var/log/prometheus/prometheus.log) por errores de regla.

6. Conclusión

Crear un exporter personalizado combina la simplicidad de los scripts Bash/Python con la potencia de Node Exporter y el ecosistema de Prometheus‑Grafana‑Alertmanager. Con los pasos descritos, obtendrás métricas de CPU, temperatura y salud de discos en tiempo real, visualizables en paneles claros y con alertas que te permitirán actuar antes de que un problema cause una caída del servicio. Además, la arquitectura basada en el textfile collector asegura que el proceso sea liviano y fácil de mantener; basta con actualizar el script o añadir nuevas lecturas sin tocar la configuración de Node Exporter.

Recuerda siempre validar los permisos y probar los scripts en un entorno de pruebas antes de desplegarlos en producción. Con una monitorización completa, tu infraestructura ganará en resiliencia y te liberarás de sorpresas inesperadas.