blackbox-exporter

prom/blackbox-exporter Docker Image

prom查看中文加速指南
自动构建

Blackbox Exporter是Prometheus生态的黑盒探测工具，支持通过HTTP、HTTPS、DNS、TCP、ICMP和gRPC协议对目标端点进行探测，提供探测成功率等指标，用于监控端点可用性和性能。

110 次收藏下载次数: 0状态：自动构建维护者：prom仓库类型：镜像最近更新：
下载命令
点击查看

Blackbox exporter

https://quay.io/repository/prometheus/blackbox-exporter https://hub.docker.com/r/prom/blackbox-exporter/

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 https://github.com/prometheus/blackbox_exporter/releases

Then:

./blackbox_exporter <flags>

Using the docker image

Images are published to https://quay.io/repository/prometheus/blackbox-exporter (quay.io/prometheus/blackbox-exporter), https://hub.docker.com/r/prom/blackbox-exporter/ (prom/blackbox-exporter) and the https://github.com/orgs/prometheus/packages?repo_name=blackbox_exporter (ghcr.io/prometheus/blackbox-exporter).

Note: You may want to https://docs.docker.com/v17.09/engine/userguide/networking/default_network/ipv6/

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

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.

The probe will also return timing metrics for measuring how long it takes to probe the target.

For example, you can find out how much of the probe timeout is used. This is useful because Prometheus timeouts can never be longer than the scrape interval.

probe_duration_seconds / probe_timeout_seconds

This query will return the ratio of remaining time.

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 https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md.

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 are debug, info, warn, and error.

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 to info level filtering, similar to the primary logger. Prober logs can be controlled with --log.prober

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

bash
# blackbox.yml
modules:
  http_2xx:
    prober: http

# generate probe
curl -sL "http://localhost:9115/probe?target=prometheus.io&module=http_2xx&debug=true"
Example stderr and debug module output with `--log.prober=info` (default) 
shell
~ $ ./blackbox_exporter --config.file ./blackbox.yml
time=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=[::]:9115
time=2025-09-09T00:58:02.558-04:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115
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/
^Ctime=2025-09-09T00:58:12.257-04:00 level=INFO source=main.go:290 msg="Received SIGTERM, exiting gracefully..."

shell
~ $ curl -sL "http://localhost:9115/probe?target=prometheus.io&module=http_2xx&debug=true" | sed '/Metrics that would have been returned/q'
Logs for 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` 
shell
~ $ ./blackbox_exporter --config.file ./blackbox.yml --log.prober=debug
time=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=[::]:9115
time=2025-09-09T00:58:21.484-04:00 level=INFO source=tls_config.go:350 msg="TLS is disabled." http2=false address=[::]:9115
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.5
time=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=ip4
time=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.220
time=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.io
time=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.io
time=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=200
time=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.000Z
time=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:00
time=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..."

shell
~ $ curl -sL "http://localhost:9115/probe?target=prometheus.io&module=http_2xx&debug=true" | sed '/Metrics that would have been returned/q'
Logs for 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.5
time=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=ip4
time=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.220
time=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.io
time=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.io
time=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=200
time=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.000Z
time=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:00
time=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



Metrics that would have been returned:

Building the software

Local Build

make

Building with Docker

After a successful local build:

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.

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 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 https://prometheus.io/docs/operating/configuration/#configuration-file, 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 https://prometheus.io/docs/guides/multi-target-exporter/ 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:

yml
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.
  - job_name: 'blackbox_exporter'  # collect blackbox exporter's operational metrics.
    static_configs:
      - 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:

yaml
scrape_configs:
  - job_name: blackbox_all
    metrics_path: /probe
    params:
      module: [ http_2xx ]  # Look for a HTTP 200 response.
    dns_sd_configs:
      - names:
          - example.com
          - prometheus.io
        type: A
        port: 443
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
        replacement: 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

DNS resolution of targets

The blackbox exporter resolves the target hostname on every probe and does not cache the result. This applies to all probers except unix.

IP address targets are used as-is and never cause a DNS query. For the dns prober the lookup is for the DNS server given as the target, not for query_name.

With the default ip_protocol_fallback: true, each lookup asks for both A and AAAA records, so one probe can send two queries. Setting preferred_ip_protocol and ip_protocol_fallback: false limits it to one record type.

If you probe many hostnames at a short interval and want fewer DNS queries, run a caching DNS resolver next to the exporter, such as systemd-resolved, unbound or dnsmasq, and point the exporter's /etc/resolv.conf at it. The systemd-resolved stub (127.0.0.53) or NodeLocal DNSCache on Kubernetes work the same way.

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.

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.

Security

Report vulnerabilities privately as described in the https://prometheus.io/docs/operating/security/. Do not open public issues or PRs for them.

The project acts on https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck results only. Reports from other scanners must include govulncheck output showing the exporter is affected by the CVE.

The exporter makes requests to any target it is given. Secure its endpoints with TLS and basic authentication and do not expose it to the internet.

Also see SECURITY.md

prom 命名空间的其他可用镜像：

prom/prometheus logo

prom/prometheus

Prometheus 监控系统，Prom 官方版本，适合指标收集和告警
prom/alertmanager logo

prom/alertmanager

Prometheus Alertmanager，告警管理服务
prom/mysqld-exporter logo

prom/mysqld-exporter

MySQLd Exporter，Prometheus 监控指标导出器
prom/pushgateway logo

prom/pushgateway

Prometheus Pushgateway，支持短生命周期任务的指标推送
prom/node-exporter logo

prom/node-exporter

Node Exporter，Prometheus 官方版本，系统监控指标导出器
prom/snmp-exporter logo

prom/snmp-exporter

Prometheus SNMP Exporter，适合网络设备 SNMP 指标采集

镜像拉取方式

您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本，请访问 标签列表页面。

轩辕镜像加速拉取命令点我查看更多 blackbox-exporter 镜像标签

docker pull docker.xuanyuan.run/prom/blackbox-exporter:<标签>

使用方法：

DockerHub 原生拉取命令

docker pull prom/blackbox-exporter:<标签>

用户好评

来自真实用户的反馈，见证轩辕镜像的优质服务

查看流量套餐与价格
用户头像

oldzhang

运维工程师

Linux服务器

5

"Docker访问体验非常流畅，大镜像也能快速完成下载。"

专业版 · 高速稳定拉取镜像
50GB 仅 ¥8/年
高速镜像下载在线技术支持专业版保障服务可用付费会员免广告