Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Blackbox prober exporter

License

NotificationsYou must be signed in to change notification settings

prometheus/blackbox_exporter

CircleCIDocker Repository on QuayDocker Pulls

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

Running this software

From binaries

Download the most suitable binary fromthe releases tab

Then:

./blackbox_exporter <flags>

Using the docker image

Note: You may want toenable ipv6 in your docker configuration

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

Checking the results

Visitinghttp://localhost:9115/probe?target=google.com&module=http_2xxwill return metrics for a HTTP probe against google.com. Theprobe_successmetric indicates if the probe succeeded. Adding adebug=true parameterwill return debug information for that probe.

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

TLS and basic authentication

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

To use TLS and/or basic authentication, you need to pass a configuration fileusing the--web.config.file parameter. The format of the file is describedin 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

The blackbox_exporter has a primary structured logger that is used for logs related to the application itself. Application logs can be controlled by--log.level, which sets the log level for messages to output, valid levels aredebug,info,warn, anderror.

The blackbox_exporter also maintains a second, fully independent structured logger that is used specifically for logging related to the probers (http,tcp,icmp,dns,grpc) and their output.The scrape probe logger defaults toinfo level filtering, similar to the primary logger. Prober logs can be controlled with--log.prober

Note

All log samples below used the following basicblackbox.yml configuration file and contain the probe logs of a single scrape generated bycurl

# blackbox.ymlmodules:  http_2xx:    prober: http# generate probecurl -sL"http://localhost:9115/probe?target=prometheus.io&module=http_2xx&debug=true"
Example stderr and debug module output with `--log.prober=info` (default)
~ $ ./blackbox_exporter --config.file ./blackbox.ymltime=2025-09-09T00:58:02.557-04:00 level=INFO source=main.go:95 msg="Starting blackbox_exporter" version="(version=0.27.0, branch=feat/make-scrape-logger-independent, revision=47e27d09847edf2ade2732b50663c37ed8177485)"time=2025-09-09T00:58:02.557-04:00 level=INFO source=main.go:96 msg="(go=go1.24.4, platform=linux/amd64, user=tjhop@contraband, date=20250909-04:57:55, tags=unknown)"time=2025-09-09T00:58:02.557-04:00 level=INFO source=main.go:108 msg="Loaded config file"time=2025-09-09T00:58:02.558-04:00 level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115time=2025-09-09T00:58:02.558-04:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115time=2025-09-09T00:58:06.756-04:00 level=WARN source=http.go:490 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/^Ctime=2025-09-09T00:58:12.257-04:00 level=INFO source=main.go:290 msg="Received SIGTERM, exiting gracefully..."
~ $ curl -sL"http://localhost:9115/probe?target=prometheus.io&module=http_2xx&debug=true"| sed'/Metrics that would have been returned/q'Logsfor the probe:time=2025-09-09T00:58:06.756-04:00 level=WARN source=http.go:490 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/Metrics that would have been returned:
Example stderr and debug module output with `--log.prober=debug`
~ $ ./blackbox_exporter --config.file ./blackbox.yml --log.prober=debugtime=2025-09-09T00:58:21.483-04:00 level=INFO source=main.go:95 msg="Starting blackbox_exporter" version="(version=0.27.0, branch=feat/make-scrape-logger-independent, revision=47e27d09847edf2ade2732b50663c37ed8177485)"time=2025-09-09T00:58:21.483-04:00 level=INFO source=main.go:96 msg="(go=go1.24.4, platform=linux/amd64, user=tjhop@contraband, date=20250909-04:57:55, tags=unknown)"time=2025-09-09T00:58:21.483-04:00 level=INFO source=main.go:108 msg="Loaded config file"time=2025-09-09T00:58:21.484-04:00 level=INFO source=tls_config.go:347 msg="Listening on" address=[::]:9115time=2025-09-09T00:58:21.484-04:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115time=2025-09-09T00:58:26.604-04:00 level=DEBUG source=handler.go:116 msg="Beginning probe" module=http_2xx target=prometheus.io probe=http timeout_seconds=119.5time=2025-09-09T00:58:26.604-04:00 level=DEBUG source=utils.go:61 msg="Resolving target address" module=http_2xx target=prometheus.io target=prometheus.io ip_protocol=ip4time=2025-09-09T00:58:26.605-04:00 level=DEBUG source=utils.go:96 msg="Resolved target address" module=http_2xx target=prometheus.io target=prometheus.io ip=104.21.60.220time=2025-09-09T00:58:26.605-04:00 level=DEBUG source=http.go:209 msg="Making HTTP request" module=http_2xx target=prometheus.io url=http://104.21.60.220 host=prometheus.iotime=2025-09-09T00:58:26.645-04:00 level=WARN source=http.go:490 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/time=2025-09-09T00:58:26.645-04:00 level=DEBUG source=http.go:209 msg="Making HTTP request" module=http_2xx target=prometheus.io url=https://prometheus.io/ host=""time=2025-09-09T00:58:26.645-04:00 level=DEBUG source=http.go:224 msg="Address does not match first address, not sending TLS ServerName" module=http_2xx target=prometheus.io first=104.21.60.220 address=prometheus.iotime=2025-09-09T00:58:26.765-04:00 level=DEBUG source=http.go:590 msg="Received HTTP response" module=http_2xx target=prometheus.io status_code=200time=2025-09-09T00:58:26.800-04:00 level=DEBUG source=http.go:721 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=0 start=2025-09-09T00:58:26.605-04:00 dnsDone=2025-09-09T00:58:26.605-04:00 connectDone=2025-09-09T00:58:26.619-04:00 gotConn=2025-09-09T00:58:26.619-04:00 responseStart=2025-09-09T00:58:26.645-04:00 tlsStart=0001-01-01T00:00:00.000Z tlsDone=0001-01-01T00:00:00.000Z end=0001-01-01T00:00:00.000Ztime=2025-09-09T00:58:26.800-04:00 level=DEBUG source=http.go:721 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=1 start=2025-09-09T00:58:26.645-04:00 dnsDone=2025-09-09T00:58:26.646-04:00 connectDone=2025-09-09T00:58:26.656-04:00 gotConn=2025-09-09T00:58:26.717-04:00 responseStart=2025-09-09T00:58:26.765-04:00 tlsStart=2025-09-09T00:58:26.657-04:00 tlsDone=2025-09-09T00:58:26.717-04:00 end=2025-09-09T00:58:26.800-04:00time=2025-09-09T00:58:26.801-04:00 level=DEBUG source=handler.go:127 msg="Probe succeeded" module=http_2xx target=prometheus.io duration_seconds=0.196876958^Ctime=2025-09-09T00:58:32.471-04:00 level=INFO source=main.go:290 msg="Received SIGTERM, exiting gracefully..."
~ $ curl -sL"http://localhost:9115/probe?target=prometheus.io&module=http_2xx&debug=true"| sed'/Metrics that would have been returned/q'Logsfor the probe:time=2025-09-09T00:58:26.604-04:00 level=DEBUG source=handler.go:116 msg="Beginning probe" module=http_2xx target=prometheus.io probe=http timeout_seconds=119.5time=2025-09-09T00:58:26.604-04:00 level=DEBUG source=utils.go:61 msg="Resolving target address" module=http_2xx target=prometheus.io target=prometheus.io ip_protocol=ip4time=2025-09-09T00:58:26.605-04:00 level=DEBUG source=utils.go:96 msg="Resolved target address" module=http_2xx target=prometheus.io target=prometheus.io ip=104.21.60.220time=2025-09-09T00:58:26.605-04:00 level=DEBUG source=http.go:209 msg="Making HTTP request" module=http_2xx target=prometheus.io url=http://104.21.60.220 host=prometheus.iotime=2025-09-09T00:58:26.645-04:00 level=WARN source=http.go:490 msg="Received redirect" module=http_2xx target=prometheus.io location=https://prometheus.io/time=2025-09-09T00:58:26.645-04:00 level=DEBUG source=http.go:209 msg="Making HTTP request" module=http_2xx target=prometheus.io url=https://prometheus.io/ host=""time=2025-09-09T00:58:26.645-04:00 level=DEBUG source=http.go:224 msg="Address does not match first address, not sending TLS ServerName" module=http_2xx target=prometheus.io first=104.21.60.220 address=prometheus.iotime=2025-09-09T00:58:26.765-04:00 level=DEBUG source=http.go:590 msg="Received HTTP response" module=http_2xx target=prometheus.io status_code=200time=2025-09-09T00:58:26.800-04:00 level=DEBUG source=http.go:721 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=0 start=2025-09-09T00:58:26.605-04:00 dnsDone=2025-09-09T00:58:26.605-04:00 connectDone=2025-09-09T00:58:26.619-04:00 gotConn=2025-09-09T00:58:26.619-04:00 responseStart=2025-09-09T00:58:26.645-04:00 tlsStart=0001-01-01T00:00:00.000Z tlsDone=0001-01-01T00:00:00.000Z end=0001-01-01T00:00:00.000Ztime=2025-09-09T00:58:26.800-04:00 level=DEBUG source=http.go:721 msg="Response timings for roundtrip" module=http_2xx target=prometheus.io roundtrip=1 start=2025-09-09T00:58:26.645-04:00 dnsDone=2025-09-09T00:58:26.646-04:00 connectDone=2025-09-09T00:58:26.656-04:00 gotConn=2025-09-09T00:58:26.717-04:00 responseStart=2025-09-09T00:58:26.765-04:00 tlsStart=2025-09-09T00:58:26.657-04:00 tlsDone=2025-09-09T00:58:26.717-04:00 end=2025-09-09T00:58:26.800-04:00time=2025-09-09T00:58:26.801-04:00 level=DEBUG source=handler.go:127 msg="Probe succeeded" module=http_2xx target=prometheus.io duration_seconds=0.196876958Metrics that would have been returned:

Building the software

Local Build

make

Building with Docker

After a successful local build:

docker build -t blackbox_exporter .

Blackbox exporter is configured via aconfiguration 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 aSIGHUP to the Blackbox exporter process or by sending a HTTP POST request to the/-/reload endpoint.

Blackbox exporter also supports automatic configuration reloading. You can enable this feature using the--config.enable-auto-reload flag.When enabled, the exporter will automatically check for changes to its configuration file at a specified interval in seconds.The interval can be customized with the--config.auto-reload-interval flag, which is set to 30 (which is 30 seconds) by default.

To view all available command-line flags, run./blackbox_exporter -h.

To specify whichconfiguration file to load, use the--config.file flag.

Additionally, anexample configuration is also available.

HTTP, HTTPS (via thehttp 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 thescrape_timeout in thePrometheus config, slightly reduced to allow for network delays.This can be further limited by thetimeout 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 adviceto read the guideUnderstanding and using the multi-target exporter pattern to get the generalidea about the configuration.

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

Example config:

scrape_configs:  -job_name:'blackbox'metrics_path:/probeparams: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.  -job_name:'blackbox_exporter'# collect blackbox exporter's operational metrics.static_configs:      -targets:['127.0.0.1:9115']

HTTP probes can accept an additionalhostname parameter that will setHost header and TLS SNI. This can be especially useful withdns_sd_config:

scrape_configs:  -job_name:blackbox_allmetrics_path:/probeparams:module:[ http_2xx ]# Look for a HTTP 200 response.dns_sd_configs:      -names:          -example.com          -prometheus.iotype:Aport:443relabel_configs:      -source_labels:[__address__]target_label:__param_targetreplacement:https://$1/# Make probe URL be like https://1.2.3.4:443/      -source_labels:[__param_target]target_label:instance      -target_label:__address__replacement:127.0.0.1:9115# The blackbox exporter's real hostname:port.      -source_labels:[__meta_dns_name]target_label:__param_hostname# Make domain name become 'Host' header for probe requests      -source_labels:[__meta_dns_name]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 withinnet.ipv4.ping_group_range, theCAP_NET_RAW capability or the root user is required.
    • Your distribution may configurenet.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 abilityto use ping.
    • Alternatively the capability can be set by executingsetcap cap_net_raw+ep blackbox_exporter
  • BSD: root user is required.
  • OS X: No additional privileges are needed.

The UNIX probe requires the process owner to have write permissions (w) to the UNIX socket,and access permissions (x) to the directory structure the socket resides in.

[8]ページ先頭
©2009-2025 Movatter.jp