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-sensorsysmartmontools.
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:
- Uso de CPU (porcentaje).
- Temperatura de la CPU (usando
sensors). - Estado y temperatura de discos (usando
smartctl).
#!/usr/bin/env python3 import subprocess import re import sysdef 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
- Accede a Grafana (
http://grafana-host:3000) y crea un nuevo Dashboard. - Añade un panel Graph para la CPU:
- Query:
custom_cpu_usage_percent - Tipo: Gauge
- Umbral: 80% (warning), 95% (critical).
- Query:
- Panel de temperatura de CPU:
- Query:
custom_cpu_temperature_celsius - Display: Stat
- Alertas: >70°C warning, >85°C critical.
- Query:
- 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).
- Query:
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 > 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:
name: ‘mail’ email_configs:to: ‘admin@example.com’ from: ‘alertmanager@example.com’ smarthost: ‘smtp.example.com:587’ auth_username: ‘alertmanager@example.com’ auth_password: ’********’
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"} valueserá descartada. Revisa/var/log/custom_exporter_error.logy el contenido del archivo temporal. - Permisos: El directorio
/var/lib/node_exporter/textfile_collectordebe ser propiedad denode_exporter. Usachowncomo se mostró. - Cache de Node Exporter: Si modificas el script, fuerza una recarga borrando el archivo
.promy 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_exporteral grupodisky establecersetuiden el binario (cuidado con seguridad). - Ejecutar el script como root dentro del service (como se muestra). Si prefieres menor exposición, crea un
sudoerslimitado:
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.