The blackbox exporter allows blackbox probing of endpoints over HTTP, HTTPS, DNS, TCP and ICMP.
Download the most suitable binary from the releases tab
Then:
./blackbox_exporter <flags>
Note: You may want to enable ipv6 in your docker configuration
docker run --rm -d -p 9115:9115 --name blackbox_exporter -v `pwd`:/config prom/blackbox-exporter:master --config.file=/config/blackbox.yml
Visiting http://localhost:9115/probe?target=google.com&module=http_2xx
will return metrics for a HTTP probe against google.com. The probe_success
metric indicates if the probe succeeded. Adding a debug=true
parameter
will return debug information for that probe.
make
After a successful local build:
docker build -t blackbox_exporter .
Blackbox exporter is configured via a configuration file and command-line flags (such as what configuration file to load, what port to listen on, and the logging format and level).
Blackbox exporter can reload its configuration file at runtime. If the new configuration is not well-formed, the changes will not be applied.
A configuration reload is triggered by sending a SIGHUP
to the Blackbox exporter process or by sending a HTTP POST request to the /-/reload
endpoint.
To view all available command-line flags, run ./blackbox_exporter -h
.
To specify which configuration file to load, use the --config.file
flag.
Additionally, an example configuration is also available.
HTTP, HTTPS (via the http
prober), DNS, TCP socket and ICMP (see permissions section) are currently supported.
Additional modules can be defined to meet your needs.
The timeout of each probe is automatically determined from the scrape_timeout
in the Prometheus config, slightly reduced to allow for network delays.
This can be further limited by the timeout
in the Blackbox exporter config file. If neither is specified, it defaults to 120 seconds.
The blackbox exporter needs to be passed the target as a parameter, this can be done with relabelling.
Example config:
scrape_configs:
- job_name: 'blackbox'
metrics_path: /probe
params:
module: [http_2xx] # Look for a HTTP 200 response.
static_configs:
- targets:
- http://prometheus.io # Target to probe with http.
- https://prometheus.io # Target to probe with https.
- http://example.com:8080 # Target to probe with http on port 8080.
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 # The blackbox exporter's real hostname:port.
The ICMP probe requires elevated privileges to function:
- Windows: Administrator privileges are required.
- Linux: either a user with a group within
net.ipv4.ping_group_range
, theCAP_NET_RAW
capability or the root user is required.- Your distribution may configure
net.ipv4.ping_group_range
by default in/etc/sysctl.conf
or similar. If not you can setnet.ipv4.ping_group_range = 0 2147483647
to allow any user the ability to use ping. - Alternatively the capability can be set by executing
setcap cap_net_raw ep blackbox_exporter
- Your distribution may configure
- BSD: root user is required.
- OS X: No additional privileges are needed.