Set up Prometheus blackbox_exporter to run HTTP, TCP, and ICMP probes and scrape probe results

domain: github.com/prometheus/blackbox_exporter · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Install and run blackbox_exporter (default listen port 9115), then define probe modules in blackbox.yml, e.g. an HTTP module with prober: http and a timeout, a TCP module with prober: tcp, and an ICMP module with prober: icmp.
  2. For the ICMP module, note it requires elevated privileges: run as root, grant the CAP_NET_RAW capability, or add the running user's group to net.ipv4.ping_group_range on Linux (Administrator privileges on Windows).
  3. In prometheus.yml, add a scrape_configs job with metrics_path: /probe and params: module: [<module_name>] (e.g. http_2xx, tcp_connect, or icmp), with static_configs targets listing the endpoints/hosts to probe (not the exporter address).
  4. Add relabel_configs to rewrite labels: copy __address__ into __param_target, copy __param_target into the instance label, then set __address__ to the blackbox_exporter's own host:port (e.g. 127.0.0.1:9115) so Prometheus actually scrapes the exporter, not the target directly.
  5. Reload/restart Prometheus and verify results via the probe_success, probe_duration_seconds, and protocol-specific metrics returned at the /probe endpoint.
  6. Optionally use file_sd or other service discovery for target lists, and configure separate scrape jobs per module (http, tcp, icmp) since each module requires its own relabeling block.

Known gotchas

Related routes

Configure Grafana Alloy (the successor to the Grafana Agent) to scrape Prometheus metrics and forward them to Grafana Mimir via remote_write
grafana.com · 5 steps · unrated
Run Prometheus in Agent mode for remote-write-only scraping without local querying
prometheus.io · 6 steps · unrated
Configure Prometheus recording rules to pre-aggregate SLO burn rate windows for efficient querying
opentelemetry.io · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans