--- title: "Cómo monitorizar endpoints con Prometheus Blackbox Exporter" description: "Instala Blackbox Exporter en Ubuntu 24.04 y configura sondas HTTP, TCP, ICMP y DNS en Prometheus, con alertas de caída, lentitud y caducidad de certificados." category: "Stack de Observabilidad" language: es source: https://cubepath.com/es/docs/stack-de-observabilidad/exportador-blackbox-para-monitoreo-de-endpoints updated: 2026-09-25 --- # 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: ```bash sudo useradd --system --no-create-home --shell /usr/sbin/nologin blackbox_exporter ``` Consulta la última versión en la [página de releases](https://github.com/prometheus/blackbox_exporter/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: ```bash 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: ```bash sha256sum -c --ignore-missing sha256sums.txt ``` ```output blackbox_exporter-0.28.0.linux-amd64.tar.gz: OK ``` Descomprímelo e instala el binario en `/usr/local/bin`: ```bash 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: ```bash blackbox_exporter --version ``` ```output 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: ```bash sudo mkdir -p /etc/blackbox_exporter sudo nano /etc/blackbox_exporter/blackbox.yml ``` Pega los siguientes módulos: ```yaml 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: ```bash 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 ``` ```output ... 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: ```bash sudo nano /etc/systemd/system/blackbox_exporter.service ``` ```ini [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: ```bash sudo systemctl daemon-reload sudo systemctl enable --now blackbox_exporter ``` Comprueba que está activo: ```bash systemctl status blackbox_exporter --no-pager ``` ```output ● 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: ```bash 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)' ``` ```output 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): ```bash 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' ``` ```output 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: ```bash sudo nano /etc/prometheus/prometheus.yml ``` Añade estos trabajos dentro de `scrape_configs`: ```yaml - 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: ```bash promtool check config /etc/prometheus/prometheus.yml sudo systemctl restart prometheus ``` ```output 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**: ```text probe_success ``` Cada destino debe devolver `1`. ## Paso 6: Crear alertas Crea un archivo de reglas junto a la configuración de Prometheus: ```bash sudo nano /etc/prometheus/blackbox_alerts.yml ``` ```yaml 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): ```yaml rule_files: - "blackbox_alerts.yml" ``` Valida las reglas y la configuración, y reinicia: ```bash promtool check rules /etc/prometheus/blackbox_alerts.yml promtool check config /etc/prometheus/prometheus.yml sudo systemctl restart prometheus ``` ```output 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: ```text 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): ```text probe_http_duration_seconds{job="blackbox_http"} ``` Días que faltan para que caduque cada certificado: ```text (probe_ssl_earliest_cert_expiry - time()) / 86400 ``` Latencia del ping: ```text 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.