Cómo monitorizar endpoints con Prometheus Blackbox Exporter

Blackbox Exporter es el exportador oficial de Prometheus para monitorización desde fuera: en lugar de medir un servicio desde dentro, lo sondea como lo haría un cliente (una petición HTTP, una conexión TCP, un ping o una consulta DNS) y publica si la sonda ha funcionado y cuánto ha tardado. En este tutorial instalarás Blackbox Exporter en Ubuntu 24.04 como servicio de systemd, definirás módulos para HTTP, TCP, ICMP y DNS, los conectarás con Prometheus y crearás alertas para endpoints caídos, respuestas lentas y certificados TLS a punto de caducar.

Requisitos previos

Para seguir esta guía necesitas:

Un servidor con Ubuntu 24.04 LTS de 64 bits (x86_64), por ejemplo un VPS de CubePath.
Un usuario no root con privilegios sudo.
Prometheus instalado en el mismo servidor, con su configuración en /etc/prometheus/prometheus.yml (es la ruta del paquete prometheus de Ubuntu). Si Prometheus está en otra máquina, cambia 127.0.0.1:9115 por la IP de este servidor en el paso 5 y abre el puerto 9115 solo a esa IP.
Uno o varios endpoints que quieras vigilar. En los ejemplos se usa your_domain como marcador: sustitúyelo por tu dominio.

Nota

sondea desde un servidor distinto al que alojas el servicio. Si ambos están en la misma máquina y esta se cae, nadie avisará.

Paso 1: Instalar Blackbox Exporter

Crea un usuario de sistema sin shell ni directorio personal para ejecutar el exportador:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin blackbox_exporter

Consulta la última versión en la página de releases (en el momento de escribir esta guía es la 0.28.0), descarga el binario y la lista de sumas de comprobación:

BLACKBOX_VERSION=0.28.0
cd /tmp
curl -fsSLO "https://github.com/prometheus/blackbox_exporter/releases/download/v${BLACKBOX_VERSION}/blackbox_exporter-${BLACKBOX_VERSION}.linux-amd64.tar.gz"
curl -fsSLO "https://github.com/prometheus/blackbox_exporter/releases/download/v${BLACKBOX_VERSION}/sha256sums.txt"

Comprueba la integridad del archivo:

sha256sum -c --ignore-missing sha256sums.txt

blackbox_exporter-0.28.0.linux-amd64.tar.gz: OK

Descomprímelo e instala el binario en /usr/local/bin:

tar -xzf "blackbox_exporter-${BLACKBOX_VERSION}.linux-amd64.tar.gz"
sudo install -m 0755 "blackbox_exporter-${BLACKBOX_VERSION}.linux-amd64/blackbox_exporter" /usr/local/bin/

Verifica la instalación:

blackbox_exporter --version

blackbox_exporter, version 0.28.0 (branch: HEAD, revision: 5a059bee8d8ffa4e75947c5055fb0abeefc582e6)

Paso 2: Definir los módulos de sonda

Un módulo describe cómo se realiza una sonda: el tipo (prober), el tiempo máximo y lo que se considera un éxito. El destino no va en el módulo, sino que lo indica Prometheus en cada petición. Así un mismo módulo sirve para cualquier número de URL.

Crea el directorio de configuración y el archivo:

sudo mkdir -p /etc/blackbox_exporter
sudo nano /etc/blackbox_exporter/blackbox.yml

Pega los siguientes módulos:

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      preferred_ip_protocol: ip4
      follow_redirects: true

  http_2xx_tls:
    prober: http
    timeout: 5s
    http:
      preferred_ip_protocol: ip4
      valid_status_codes: [200]
      fail_if_not_ssl: true

  tcp_connect:
    prober: tcp
    timeout: 5s
    tcp:
      preferred_ip_protocol: ip4

  ssh_banner:
    prober: tcp
    timeout: 5s
    tcp:
      preferred_ip_protocol: ip4
      query_response:
        - expect: "^SSH-2.0-"

  icmp:
    prober: icmp
    timeout: 5s
    icmp:
      preferred_ip_protocol: ip4

  dns_a:
    prober: dns
    timeout: 5s
    dns:
      preferred_ip_protocol: ip4
      transport_protocol: udp
      query_name: "your_domain"
      query_type: "A"
      valid_rcodes: [NOERROR]

Qué comprueba cada módulo:

Módulo	Éxito cuando
`http_2xx`	La URL responde con un código 2xx, siguiendo redirecciones
`http_2xx_tls`	Responde exactamente 200 y por HTTPS; falla si la respuesta llega por HTTP
`tcp_connect`	Se establece la conexión TCP con `host:puerto`
`ssh_banner`	El puerto devuelve un banner SSH válido, no solo una conexión abierta
`icmp`	El host responde al ping
`dns_a`	El servidor DNS de destino responde a la consulta A de `your_domain` con `NOERROR`

Con preferred_ip_protocol: ip4 las sondas usan IPv4 cuando el nombre tiene registros A y AAAA. Si quieres vigilar también IPv6, duplica el módulo con ip6.

Ajusta los permisos y valida la sintaxis con la opción --config.check, que carga el archivo y termina:

sudo chown -R root:blackbox_exporter /etc/blackbox_exporter
sudo chmod 640 /etc/blackbox_exporter/blackbox.yml
sudo -u blackbox_exporter blackbox_exporter --config.file=/etc/blackbox_exporter/blackbox.yml --config.check

... level=INFO source=main.go:107 msg="Config file is ok exiting..."

Paso 3: Crear el servicio de systemd

La sonda ICMP necesita abrir sockets raw, algo que un usuario sin privilegios no puede hacer. En lugar de ejecutar el exportador como root, el servicio le concede solo la capacidad CAP_NET_RAW.

Crea la unidad:

sudo nano /etc/systemd/system/blackbox_exporter.service

[Unit]
Description=Prometheus Blackbox Exporter
Wants=network-online.target
After=network-online.target

[Service]
User=blackbox_exporter
Group=blackbox_exporter
ExecStart=/usr/local/bin/blackbox_exporter \
  --config.file=/etc/blackbox_exporter/blackbox.yml \
  --web.listen-address=127.0.0.1:9115
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW
NoNewPrivileges=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target

El exportador escucha solo en 127.0.0.1 porque Prometheus está en el mismo servidor. ExecReload permite recargar los módulos con systemctl reload sin reiniciar el proceso.

Recarga systemd, habilita el servicio y arráncalo:

sudo systemctl daemon-reload
sudo systemctl enable --now blackbox_exporter

Comprueba que está activo:

systemctl status blackbox_exporter --no-pager

● blackbox_exporter.service - Prometheus Blackbox Exporter
     Loaded: loaded (/etc/systemd/system/blackbox_exporter.service; enabled; preset: enabled)
     Active: active (running) since ...

Paso 4: Probar las sondas manualmente

El exportador ejecuta una sonda cada vez que recibe una petición en /probe con los parámetros target y module. Pruébalo contra tu web:

curl -s "http://127.0.0.1:9115/probe?target=https://your_domain&module=http_2xx_tls" | grep -E '^probe_(success|http_status_code|duration_seconds|ssl_earliest_cert_expiry)'

probe_duration_seconds 0.214
probe_http_status_code 200
probe_ssl_earliest_cert_expiry 1.793139441e+09
probe_success 1

probe_success 1 indica que la sonda ha superado todas las condiciones del módulo. probe_ssl_earliest_cert_expiry es la fecha de caducidad del certificado en tiempo Unix, que usarás en las alertas.

Prueba también las sondas TCP, ICMP y DNS (en DNS, el destino es el servidor al que se pregunta):

curl -s "http://127.0.0.1:9115/probe?target=your_domain:22&module=ssh_banner" | grep '^probe_success'
curl -s "http://127.0.0.1:9115/probe?target=1.1.1.1&module=icmp" | grep '^probe_success'
curl -s "http://127.0.0.1:9115/probe?target=1.1.1.1&module=dns_a" | grep '^probe_success'

probe_success 1
probe_success 1
probe_success 1

Si alguna devuelve probe_success 0, añade &debug=true a la URL. El exportador mostrará el registro completo de la sonda: resolución DNS, conexión, código de respuesta y el motivo exacto del fallo.

Paso 5: Configurar Prometheus para lanzar las sondas

Prometheus normalmente pide /metrics a cada destino. Con Blackbox Exporter el destino real es la URL a sondear, pero la petición debe ir al exportador. Las reglas de relabel_configs hacen ese cambio: copian el destino al parámetro target, lo conservan como etiqueta instance y redirigen la petición a 127.0.0.1:9115.

Abre la configuración de Prometheus:

sudo nano /etc/prometheus/prometheus.yml

Añade estos trabajos dentro de scrape_configs:

  - job_name: "blackbox_http"
    metrics_path: /probe
    params:
      module: [http_2xx_tls]
    static_configs:
      - targets:
          - https://your_domain
          - https://your_domain/api/health
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

  - job_name: "blackbox_icmp"
    metrics_path: /probe
    params:
      module: [icmp]
    static_configs:
      - targets:
          - your_server_ip
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

  - job_name: "blackbox_ssh"
    metrics_path: /probe
    params:
      module: [ssh_banner]
    static_configs:
      - targets:
          - your_server_ip:22
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

  - job_name: "blackbox_exporter"
    static_configs:
      - targets: ["127.0.0.1:9115"]

El último trabajo recoge las métricas internas del exportador, útil para detectar si el propio exportador deja de funcionar. Para vigilar más URL basta con añadirlas a la lista targets del trabajo correspondiente.

Valida la configuración y reinicia Prometheus:

promtool check config /etc/prometheus/prometheus.yml
sudo systemctl restart prometheus

Checking /etc/prometheus/prometheus.yml
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

En la interfaz web de Prometheus (http://your_server_ip:9090), ve a Status > Targets: los nuevos trabajos deben aparecer con estado UP. Ese estado solo indica que el exportador ha respondido; si el endpoint está caído lo verás en probe_success. Ejecuta esta consulta en la pestaña Graph:

probe_success

Cada destino debe devolver 1.

Paso 6: Crear alertas

Crea un archivo de reglas junto a la configuración de Prometheus:

sudo nano /etc/prometheus/blackbox_alerts.yml

groups:
  - name: blackbox
    rules:
      - alert: EndpointDown
        expr: probe_success == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "{{ $labels.instance }} no responde"
          description: "La sonda {{ $labels.job }} contra {{ $labels.instance }} falla desde hace más de 2 minutos."

      - alert: EndpointSlow
        expr: avg_over_time(probe_duration_seconds[5m]) > 2
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "{{ $labels.instance }} responde lento"
          description: "La sonda tarda de media {{ $value | humanizeDuration }} en los últimos 5 minutos."

      - alert: SSLCertExpiringSoon
        expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 14
        for: 1h
        labels:
          severity: warning
        annotations:
          summary: "El certificado de {{ $labels.instance }} caduca pronto"
          description: "Quedan {{ $value | humanize }} días para que caduque el certificado TLS."

EndpointDown usa for: 2m para no avisar por un único fallo puntual de red.
EndpointSlow promedia la duración de 5 minutos, de modo que un pico aislado no dispara la alerta.
SSLCertExpiringSoon avisa cuando quedan menos de 14 días. Con Let's Encrypt, que renueva a los 30 días de la caducidad, esta alerta indica que la renovación automática ha fallado.

Registra el archivo en /etc/prometheus/prometheus.yml, en la sección rule_files (créala al nivel de scrape_configs si no existe):

rule_files:
  - "blackbox_alerts.yml"

Valida las reglas y la configuración, y reinicia:

promtool check rules /etc/prometheus/blackbox_alerts.yml
promtool check config /etc/prometheus/prometheus.yml
sudo systemctl restart prometheus

Checking /etc/prometheus/blackbox_alerts.yml
  SUCCESS: 3 rules found

Las reglas aparecen en la pestaña Alerts de Prometheus. Para recibir las notificaciones por correo, Slack u otro canal necesitas Alertmanager o Grafana Alerting conectados a Prometheus.

Para comprobar que la alerta funciona, añade temporalmente al trabajo blackbox_http un destino que no exista, como https://noexiste.your_domain. Tras unos segundos verás EndpointDown en estado Pending y, pasados 2 minutos, en Firing. Después elimina ese destino.

Paso 7: Consultas útiles para paneles

Estas consultas PromQL sirven tanto en Prometheus como en paneles de Grafana:

Disponibilidad de cada endpoint en porcentaje durante las últimas 24 horas:

avg_over_time(probe_success[24h]) * 100

Tiempo de cada fase de la petición HTTP (resolución DNS, conexión, TLS, procesamiento y transferencia):

probe_http_duration_seconds{job="blackbox_http"}

Días que faltan para que caduque cada certificado:

(probe_ssl_earliest_cert_expiry - time()) / 86400

Latencia del ping:

probe_duration_seconds{job="blackbox_icmp"}

Solución de problemas

La sonda ICMP falla con un error operation not permitted. El servicio no tiene la capacidad CAP_NET_RAW. Revisa que las líneas AmbientCapabilities y CapabilityBoundingSet están en la unidad y ejecuta sudo systemctl daemon-reload && sudo systemctl restart blackbox_exporter.

probe_success 0 con HTTPS y el navegador funciona. Consulta la sonda con &debug=true. Las causas más habituales son un certificado incompleto (falta la cadena intermedia), un código distinto de 200 con el módulo http_2xx_tls o un bloqueo del cortafuegos del destino a la IP del servidor que sondea.

Todas las sondas fallan por timeout. El exportador usa el menor valor entre el timeout del módulo y el scrape_timeout de Prometheus (10 s por defecto). Si el destino es lento, sube ambos valores, manteniendo el timeout del módulo por debajo del scrape_timeout.

Los cambios en blackbox.yml no se aplican. Recarga la configuración con sudo systemctl reload blackbox_exporter y revisa sudo journalctl -u blackbox_exporter -n 20 por si hay errores de sintaxis.

Conclusión

Tienes Blackbox Exporter funcionando como servicio en Ubuntu 24.04, con módulos para HTTP, TCP, ICMP y DNS, Prometheus sondeando tus endpoints y alertas para caídas, lentitud y certificados a punto de caducar. Como siguientes pasos, puedes instalar Alertmanager para enviar las alertas a correo o Slack, desplegar el exportador en varias ubicaciones para distinguir una caída real de un problema de red local, o importar un panel de Blackbox Exporter en Grafana usando las consultas del paso 7.

On this page