项目作者: prometheus

项目描述 :
Blackbox prober exporter
高级语言: Go
项目地址: git://github.com/prometheus/blackbox_exporter.git
创建时间: 2015-09-05T14:45:00Z
项目社区:https://github.com/prometheus/blackbox_exporter

开源协议:Apache License 2.0

下载


Blackbox exporter

CircleCI
Docker Repository on Quay
Docker Pulls

The blackbox exporter allows blackbox probing of endpoints over
HTTP, HTTPS, DNS, TCP, ICMP and gRPC.

Running this software

From binaries

Download the most suitable binary from the releases tab

Then:

  1. ./blackbox_exporter <flags>

Using the docker image

Note: You may want to enable ipv6 in your docker configuration

  1. docker run --rm \
  2. -p 9115/tcp \
  3. --name blackbox_exporter \
  4. -v $(pwd):/config \
  5. quay.io/prometheus/blackbox-exporter:latest --config.file=/config/blackbox.yml

Checking the results

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.

Metrics concerning the operation of the exporter itself are available at the
endpoint http://localhost:9115/metrics.

TLS and basic authentication

The Blackbox Exporter supports TLS and basic authentication. This enables better
control of the various HTTP endpoints.

To use TLS and/or basic authentication, you need to pass a configuration file
using the --web.config.file parameter. The format of the file is described
in the exporter-toolkit repository.

Note that the TLS and basic authentication settings affect all HTTP endpoints:
/metrics for scraping, /probe for probing, and the web UI.

Controlling log level for probe logs

It is possible to control the level at which probe logs related to a scrape are output as.

Probe logs default to debug level, and can be controlled by the --log.prober flag.
This means that probe scrape logs will not be output unless the level configured for the probe logger via --log.prober is >= the level configured for the blackbox_exporter via --log.level.

Sample output demonstrating the use and effect of these flags can be seen below.

Note

All log samples below used the following basic blackbox.yml configuration file and contain the probe logs of a single scrape generated by curl

  1. # blackbox.yml
  2. modules:
  3. http_2xx:
  4. prober: http
  5. # generate probe
  6. curl "http://localhost:9115/probe?target=prometheus.io&module=http_2xx"

Example output with --log.level=info and --log.prober=debug (default)

bash ./blackbox_exporter --config.file ./blackbox.yml --log.level=info --log.prober=debug time=2025-05-21T04:10:54.131Z level=INFO source=main.go:88 msg="Starting blackbox_exporter" version="(version=0.26.0, branch=fix/scrape-logger-spam, revision=7df3031feecba82f1a534336979b4e5920f79b72)" time=2025-05-21T04:10:54.131Z level=INFO source=main.go:89 msg="(go=go1.24.1, platform=linux/amd64, user=tjhop@contraband, date=20250521-04:00:25, tags=unknown)" time=2025-05-21T04:10:54.132Z level=INFO source=main.go:101 msg="Loaded config file" time=2025-05-21T04:10:54.133Z level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115 time=2025-05-21T04:10:54.133Z level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115 ^Ctime=2025-05-21T04:11:03.619Z level=INFO source=main.go:283 msg="Received SIGTERM, exiting gracefully..."

Example output with --log.level=info and --log.prober=info

bash ./blackbox_exporter --config.file ./blackbox.yml --log.level=info --log.prober=info time=2025-05-21T04:12:09.884Z level=INFO source=main.go:88 msg="Starting blackbox_exporter" version="(version=0.26.0, branch=fix/scrape-logger-spam, revision=7df3031feecba82f1a534336979b4e5920f79b72)" time=2025-05-21T04:12:09.884Z level=INFO source=main.go:89 msg="(go=go1.24.1, platform=linux/amd64, user=tjhop@contraband, date=20250521-04:00:25, tags=unknown)" time=2025-05-21T04:12:09.884Z level=INFO source=main.go:101 msg="Loaded config file" time=2025-05-21T04:12:09.885Z level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115 time=2025-05-21T04:12:09.885Z level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115 time=2025-05-21T04:12:13.827Z level=INFO source=handler.go:194 msg="Beginning probe" module=http_2xx target=prometheus.io probe=http timeout_seconds=119.5 time=2025-05-21T04:12:13.827Z level=INFO source=handler.go:194 msg="Resolving target address" module=http_2xx target=prometheus.io target=prometheus.io ip_protocol=ip4 time=2025-05-21T04:12:13.829Z level=INFO source=handler.go:194 msg="Resolved target address" module=http_2xx target=prometheus.io target=prometheus.io ip=172.67.201.240 time=2025-05-21T04:12:13.829Z level=INFO source=handler.go:194 msg="Making HTTP request" module=http_2xx target=prometheus.io url=http://172.67.201.240 host=prometheus.io time=2025-05-21T04:12:13.860Z level=INFO source=handler.go:194 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/ time=2025-05-21T04:12:13.860Z level=INFO source=handler.go:194 msg="Making HTTP request" module=http_2xx target=prometheus.io url=https://prometheus.io/ host="" time=2025-05-21T04:12:13.860Z level=INFO source=handler.go:194 msg="Address does not match first address, not sending TLS ServerName" module=http_2xx target=prometheus.io first=172.67.201.240 address=prometheus.io time=2025-05-21T04:12:13.974Z level=INFO source=handler.go:194 msg="Received HTTP response" module=http_2xx target=prometheus.io status_code=200 time=2025-05-21T04:12:13.974Z level=INFO source=handler.go:194 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=0 start=2025-05-21T00:12:13.829-04:00 dnsDone=2025-05-21T00:12:13.829-04:00 connectDone=2025-05-21T00:12:13.839-04:00 gotConn=2025-05-21T00:12:13.839-04:00 responseStart=2025-05-21T00:12:13.860-04:00 tlsStart=0001-01-01T00:00:00.000Z tlsDone=0001-01-01T00:00:00.000Z end=0001-01-01T00:00:00.000Z time=2025-05-21T04:12:13.974Z level=INFO source=handler.go:194 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=1 start=2025-05-21T00:12:13.860-04:00 dnsDone=2025-05-21T00:12:13.861-04:00 connectDone=2025-05-21T00:12:13.869-04:00 gotConn=2025-05-21T00:12:13.925-04:00 responseStart=2025-05-21T00:12:13.974-04:00 tlsStart=2025-05-21T00:12:13.869-04:00 tlsDone=2025-05-21T00:12:13.925-04:00 end=2025-05-21T00:12:13.974-04:00 time=2025-05-21T04:12:13.974Z level=INFO source=handler.go:194 msg="Probe succeeded" module=http_2xx target=prometheus.io duration_seconds=0.14708839 ^Ctime=2025-05-21T04:12:17.818Z level=INFO source=main.go:283 msg="Received SIGTERM, exiting gracefully..."

Example output with --log.level=debug and --log.prober=info

bash ./blackbox_exporter --config.file ./blackbox.yml --log.level=debug --log.prober=info time=2025-05-21T04:13:18.497Z level=INFO source=main.go:88 msg="Starting blackbox_exporter" version="(version=0.26.0, branch=fix/scrape-logger-spam, revision=7df3031feecba82f1a534336979b4e5920f79b72)" time=2025-05-21T04:13:18.497Z level=INFO source=main.go:89 msg="(go=go1.24.1, platform=linux/amd64, user=tjhop@contraband, date=20250521-04:00:25, tags=unknown)" time=2025-05-21T04:13:18.497Z level=INFO source=main.go:101 msg="Loaded config file" time=2025-05-21T04:13:18.498Z level=DEBUG source=main.go:116 msg=http://contraband:9115 time=2025-05-21T04:13:18.498Z level=DEBUG source=main.go:130 msg=/ time=2025-05-21T04:13:18.498Z level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115 time=2025-05-21T04:13:18.498Z level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115 time=2025-05-21T04:13:23.169Z level=INFO source=handler.go:194 msg="Beginning probe" module=http_2xx target=prometheus.io probe=http timeout_seconds=119.5 time=2025-05-21T04:13:23.169Z level=INFO source=handler.go:194 msg="Resolving target address" module=http_2xx target=prometheus.io target=prometheus.io ip_protocol=ip4 time=2025-05-21T04:13:23.170Z level=INFO source=handler.go:194 msg="Resolved target address" module=http_2xx target=prometheus.io target=prometheus.io ip=104.21.60.220 time=2025-05-21T04:13:23.170Z level=INFO source=handler.go:194 msg="Making HTTP request" module=http_2xx target=prometheus.io url=http://104.21.60.220 host=prometheus.io time=2025-05-21T04:13:23.202Z level=INFO source=handler.go:194 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/ time=2025-05-21T04:13:23.202Z level=INFO source=handler.go:194 msg="Making HTTP request" module=http_2xx target=prometheus.io url=https://prometheus.io/ host="" time=2025-05-21T04:13:23.202Z level=INFO source=handler.go:194 msg="Address does not match first address, not sending TLS ServerName" module=http_2xx target=prometheus.io first=104.21.60.220 address=prometheus.io time=2025-05-21T04:13:23.316Z level=INFO source=handler.go:194 msg="Received HTTP response" module=http_2xx target=prometheus.io status_code=200 time=2025-05-21T04:13:23.319Z level=INFO source=handler.go:194 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=0 start=2025-05-21T00:13:23.171-04:00 dnsDone=2025-05-21T00:13:23.171-04:00 connectDone=2025-05-21T00:13:23.181-04:00 gotConn=2025-05-21T00:13:23.181-04:00 responseStart=2025-05-21T00:13:23.201-04:00 tlsStart=0001-01-01T00:00:00.000Z tlsDone=0001-01-01T00:00:00.000Z end=0001-01-01T00:00:00.000Z time=2025-05-21T04:13:23.319Z level=INFO source=handler.go:194 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=1 start=2025-05-21T00:13:23.202-04:00 dnsDone=2025-05-21T00:13:23.203-04:00 connectDone=2025-05-21T00:13:23.212-04:00 gotConn=2025-05-21T00:13:23.268-04:00 responseStart=2025-05-21T00:13:23.316-04:00 tlsStart=2025-05-21T00:13:23.212-04:00 tlsDone=2025-05-21T00:13:23.268-04:00 end=2025-05-21T00:13:23.319-04:00 time=2025-05-21T04:13:23.319Z level=INFO source=handler.go:194 msg="Probe succeeded" module=http_2xx target=prometheus.io duration_seconds=0.150580389 ^Ctime=2025-05-21T04:13:27.945Z level=INFO source=main.go:283 msg="Received SIGTERM, exiting gracefully..."

Example output with --log.level=debug and --log.prober=debug

bash ./blackbox_exporter --config.file ./blackbox.yml --log.level=debug --log.prober=debug time=2025-05-21T04:14:55.621Z level=INFO source=main.go:88 msg="Starting blackbox_exporter" version="(version=0.26.0, branch=fix/scrape-logger-spam, revision=7df3031feecba82f1a534336979b4e5920f79b72)" time=2025-05-21T04:14:55.621Z level=INFO source=main.go:89 msg="(go=go1.24.1, platform=linux/amd64, user=tjhop@contraband, date=20250521-04:00:25, tags=unknown)" time=2025-05-21T04:14:55.622Z level=INFO source=main.go:101 msg="Loaded config file" time=2025-05-21T04:14:55.622Z level=DEBUG source=main.go:116 msg=http://contraband:9115 time=2025-05-21T04:14:55.622Z level=DEBUG source=main.go:130 msg=/ time=2025-05-21T04:14:55.623Z level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115 time=2025-05-21T04:14:55.623Z level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115 time=2025-05-21T04:15:03.048Z level=DEBUG source=handler.go:194 msg="Beginning probe" module=http_2xx target=prometheus.io probe=http timeout_seconds=119.5 time=2025-05-21T04:15:03.049Z level=DEBUG source=handler.go:194 msg="Resolving target address" module=http_2xx target=prometheus.io target=prometheus.io ip_protocol=ip4 time=2025-05-21T04:15:03.050Z level=DEBUG source=handler.go:194 msg="Resolved target address" module=http_2xx target=prometheus.io target=prometheus.io ip=172.67.201.240 time=2025-05-21T04:15:03.050Z level=DEBUG source=handler.go:194 msg="Making HTTP request" module=http_2xx target=prometheus.io url=http://172.67.201.240 host=prometheus.io time=2025-05-21T04:15:03.089Z level=DEBUG source=handler.go:194 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/ time=2025-05-21T04:15:03.089Z level=DEBUG source=handler.go:194 msg="Making HTTP request" module=http_2xx target=prometheus.io url=https://prometheus.io/ host="" time=2025-05-21T04:15:03.089Z level=DEBUG source=handler.go:194 msg="Address does not match first address, not sending TLS ServerName" module=http_2xx target=prometheus.io first=172.67.201.240 address=prometheus.io time=2025-05-21T04:15:03.211Z level=DEBUG source=handler.go:194 msg="Received HTTP response" module=http_2xx target=prometheus.io status_code=200 time=2025-05-21T04:15:03.212Z level=DEBUG source=handler.go:194 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=0 start=2025-05-21T00:15:03.050-04:00 dnsDone=2025-05-21T00:15:03.050-04:00 connectDone=2025-05-21T00:15:03.061-04:00 gotConn=2025-05-21T00:15:03.061-04:00 responseStart=2025-05-21T00:15:03.089-04:00 tlsStart=0001-01-01T00:00:00.000Z tlsDone=0001-01-01T00:00:00.000Z end=0001-01-01T00:00:00.000Z time=2025-05-21T04:15:03.212Z level=DEBUG source=handler.go:194 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=1 start=2025-05-21T00:15:03.089-04:00 dnsDone=2025-05-21T00:15:03.090-04:00 connectDone=2025-05-21T00:15:03.102-04:00 gotConn=2025-05-21T00:15:03.163-04:00 responseStart=2025-05-21T00:15:03.211-04:00 tlsStart=2025-05-21T00:15:03.102-04:00 tlsDone=2025-05-21T00:15:03.163-04:00 end=2025-05-21T00:15:03.212-04:00 time=2025-05-21T04:15:03.212Z level=DEBUG source=handler.go:194 msg="Probe succeeded" module=http_2xx target=prometheus.io duration_seconds=0.163695815 ^Ctime=2025-05-21T04:15:07.862Z level=INFO source=main.go:283 msg="Received SIGTERM, exiting gracefully..."

Building the software

Local Build

  1. make

Building with Docker

After a successful local build:

  1. docker build -t blackbox_exporter .

Configuration

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, ICMP and gRPC (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.

Prometheus Configuration

Blackbox exporter implements the multi-target exporter pattern, so we advice
to read the guide Understanding and using the multi-target exporter pattern to get the general
idea about the configuration.

The blackbox exporter needs to be passed the target as a parameter, this can be
done with relabelling.

Example config:

  1. scrape_configs:
  2. - job_name: 'blackbox'
  3. metrics_path: /probe
  4. params:
  5. module: [http_2xx] # Look for a HTTP 200 response.
  6. static_configs:
  7. - targets:
  8. - http://prometheus.io # Target to probe with http.
  9. - https://prometheus.io # Target to probe with https.
  10. - http://example.com:8080 # Target to probe with http on port 8080.
  11. relabel_configs:
  12. - source_labels: [__address__]
  13. target_label: __param_target
  14. - source_labels: [__param_target]
  15. target_label: instance
  16. - target_label: __address__
  17. replacement: 127.0.0.1:9115 # The blackbox exporter's real hostname:port.
  18. - job_name: 'blackbox_exporter' # collect blackbox exporter's operational metrics.
  19. static_configs:
  20. - targets: ['127.0.0.1:9115']

HTTP probes can accept an additional hostname parameter that will set Host header and TLS SNI. This can be especially useful with dns_sd_config:

  1. scrape_configs:
  2. - job_name: blackbox_all
  3. metrics_path: /probe
  4. params:
  5. module: [ http_2xx ] # Look for a HTTP 200 response.
  6. dns_sd_configs:
  7. - names:
  8. - example.com
  9. - prometheus.io
  10. type: A
  11. port: 443
  12. relabel_configs:
  13. - source_labels: [__address__]
  14. target_label: __param_target
  15. replacement: https://$1/ # Make probe URL be like https://1.2.3.4:443/
  16. - source_labels: [__param_target]
  17. target_label: instance
  18. - target_label: __address__
  19. replacement: 127.0.0.1:9115 # The blackbox exporter's real hostname:port.
  20. - source_labels: [__meta_dns_name]
  21. target_label: __param_hostname # Make domain name become 'Host' header for probe requests
  22. - source_labels: [__meta_dns_name]
  23. target_label: vhost # and store it in 'vhost' label

Permissions

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, the
    CAP_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 set
      net.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
  • BSD: root user is required.
  • OS X: No additional privileges are needed.