Blackbox Exporter

The Blackbox Exporter is the Prometheus project's prober. It sends a real request to an endpoint (an HTTPS page, a DNS server, a TCP port, an ICMP echo) and reports whether the request passed and how long each phase took. In-process metrics describe what a service thinks of itself; a probe shows what a client actually gets, including DNS, TLS, the CDN and the ingress in between.

What it is

A small Go server, maintained in the prometheus GitHub organisation, licensed Apache 2.0. It ships as release binaries and as the quay.io/prometheus/blackbox-exporter and prom/blackbox-exporter images. The prometheus-community Helm chart prometheus-blackbox-exporter (11.20.0 at the time of writing) packages it for Kubernetes.

The current release is v0.29.0 (2026-10-07). It is still pre-1.0, and minor releases can change behaviour:

• v0.29.0 added a WebSocket prober, a probe_timeout_seconds metric, tls_cipher_info for TCP and Unix probes, and optional CRL revocation checks (check_revoked). It also made the exporter refuse a config whose prober value is invalid, so a typo that older versions accepted now fails the load.
• v0.28.0 (2025-12) had two breaking log changes: --log.prober now controls an independent probe logger, and many probe messages moved from INFO to DEBUG. The same release added an HTTP/3 (QUIC) prober, Unix-socket probes, gRPC metadata, opt-in config auto-reload (--config.enable-auto-reload), and a default User-Agent of Blackbox-Exporter/<version>.
• v0.27.0 (2025-06) added CEL expressions to match JSON response bodies.

It belongs to the Prometheus exporter family, next to node_exporter and the SNMP exporter. Like the SNMP exporter, it uses the multi-target exporter pattern: one exporter instance probes many targets, and Prometheus says which target to probe on each scrape.

How it works

The exporter keeps no target list and no schedule. Prometheus owns both. For each target, Prometheus scrapes /probe?target=<url>&module=<name>. The exporter looks up the module in its config file, runs that probe once, and returns the result as the scrape body. The probe timeout comes from the Prometheus scrape_timeout (slightly reduced), capped by the module's timeout, with a default of 120 seconds when neither is set.

Every probe resolves the hostname again (no DNS cache) and makes one connection attempt to one address. There is no retry and no "happy eyeballs" fallback, because the goal is to test one path and see it fail when it is broken.

A module is a named probe recipe: the prober type, a timeout and the checks. The http_2xx module in the example config asks for a 2xx answer. A stricter module can require TLS (fail_if_not_ssl), require some body text (fail_if_body_not_matches_regexp), or check a JSON body with a CEL expression. A probe only fails on these checks if the module sets them.

When to use it

Reach for it when:

• A public site or API needs an uptime check that goes through DNS, TLS, the CDN and the ingress, not only a pod readiness check.
• TLS certificates need an expiry alert (probe_ssl_earliest_cert_expiry) that does not depend on the issuer's own reminders.
• An availability SLO needs a simple good/bad signal. probe_success is a 0/1 gauge that SLO tools can use directly.
• Prometheus is already in place, so probes should be ordinary scrapes with ordinary labels, rules and alert routes.

Skip it when:

• The check needs a multi-step browser flow (sign in, click, submit). The exporter makes one request per probe and runs no JavaScript.
• Probes must come from many regions. One exporter tests from one network location; use one exporter per location, or a hosted synthetic service.
• There is no Prometheus. Without a scraper the exporter only answers ad-hoc curl calls.

At a glance

Core concepts

• Prober — the protocol: http, tcp, dns, icmp, grpc, unix, websocket. HTTPS is the http prober with TLS.
• Module — a named config in blackbox.yml that picks a prober and its checks. A scrape names one module.
• Target — the URL, host:port or IP to probe, passed as the target query parameter.
• Multi-target pattern — relabeling copies __address__ into __param_target, keeps it as the instance label, and points __address__ at the exporter.
• probe_success — 1 when every check passed, 0 when any failed. The main signal for uptime and SLOs.
• Debug mode — add debug=true to a /probe request to get the probe log and the metrics it would have returned.

Key facts

Aspect	Detail
Release line	v0.29.0 (2026-10-07), pre-1.0
Licence	Apache 2.0
Default port	9115 (/probe, /metrics, web UI)
Config reload	SIGHUP, POST /-/reload, or --config.enable-auto-reload (30 s check interval by default)
Probe timeout	From Prometheus scrape_timeout, capped by module timeout; 120 s if neither is set
ICMP on Linux	Needs CAP_NET_RAW, root, or a group in net.ipv4.ping_group_range
Endpoint auth	TLS and basic auth through --web.config.file (exporter-toolkit format)

Useful metrics

Metric	What it tells
probe_success	Whether the probe passed (1) or failed (0)
probe_duration_seconds	Total time of the probe
probe_http_duration_seconds{phase}	Time in resolve, connect, tls, processing and transfer
probe_http_status_code	The final HTTP status after redirects
probe_ssl_earliest_cert_expiry	Unix time when the first certificate in the chain expires
probe_dns_lookup_time_seconds	Time spent resolving the target

How to integrate

A minimal module file. preferred_ip_protocol defaults to ip6, so set ip4 on IPv4-only networks:

# blackbox.yml
modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      valid_http_versions: ["HTTP/1.1", "HTTP/2.0"]
      follow_redirects: true
      fail_if_not_ssl: true
      preferred_ip_protocol: ip4

A plain Prometheus scrape job with the multi-target relabeling, from the project README:

scrape_configs:
  - job_name: blackbox
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://example.com/
          - https://api.example.com/healthz
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115
  - job_name: blackbox_exporter      # the exporter's own metrics
    static_configs:
      - targets: [blackbox-exporter:9115]

On Kubernetes with the Prometheus Operator, the Probe custom resource replaces the hand-written relabeling:

apiVersion: monitoring.coreos.com/v1
kind: Probe
metadata:
  name: public-sites
  namespace: monitoring
spec:
  interval: 60s
  module: http_2xx
  prober:
    url: blackbox-exporter.monitoring.svc:9115   # path defaults to /probe
  targets:
    staticConfig:
      static:
        - https://example.com/
        - https://api.example.com/healthz

With kube-prometheus-stack, the default probeSelectorNilUsesHelmValues: true makes Prometheus select only Probes that carry the chart's release label. Set it to false (or add the label) or the Probe is ignored.

An availability SLO with Pyrra, adapted from the Pyrra examples:

apiVersion: pyrra.dev/v1alpha1
kind: ServiceLevelObjective
metadata:
  name: public-sites-availability
  namespace: monitoring
spec:
  target: "99.5"
  window: 28d
  indicator:
    bool_gauge:
      metric: probe_success
      grouping: [instance]

In the GL stack

Blackbox Exporter v0.29.0 runs on the management cluster, next to the Prometheus hub, Alertmanager and Pyrra. It probes the public product sites and their APIs over HTTPS from outside the apps. A probe does not call a pod or a Service inside the cluster. It goes out through the public internet and back in through Cloudflare and the Cloudflare Tunnel, the same way a visitor's request does. So a failed probe covers the faults that in-cluster metrics do not see: an expired certificate, a broken DNS record, a down tunnel, or an ingress route that is not correct.

The hub Prometheus scrapes the exporter and stores the probe series with the rest of the stack's metrics. Two consumers use the results:

• Pyrra reads probe_success as the indicator for the availability SLOs. It generates the recording rules and the multi-window burn-rate alerts.
• Uptime alerts fire when a probe fails. They go through the same Alertmanager route as every other alert: grouped by cluster, alert name and namespace, and sent as email.

The prober runs on a different cluster from the one that serves the products, so a fault on the production cluster does not also stop the probes that report it.

Gotchas

• IPv6 is the default. preferred_ip_protocol defaults to ip6 with fallback on. On IPv4-only clusters, set ip4 so that the reported address family is the one under test.
• One address, one attempt. With round-robin DNS, each probe tests one address at random. A single bad backend shows as intermittent failures, not a steady failure.
• The target label is the identity. Without the relabel to instance (or the target label from a Probe), every probe series looks like it comes from the exporter, and alerts cannot name the failing site.
• Scrape timeout limits the probe. A probe cannot take longer than the Prometheus scrape_timeout. A slow endpoint with a short timeout shows as down; probe_duration_seconds / probe_timeout_seconds shows how close each probe is to the limit.
• v0.29.0 rejects invalid prober values. Validate the config before an upgrade, or the exporter fails to start.
• v0.28.0 moved probe logs to DEBUG. Old log-based checks can go quiet. Use --log.prober=debug, or debug=true on one request.
• check_revoked never fails a probe. It only emits probe_ssl_crl_* metrics. Alert on them if revocation is important.
• Helm config and binary payloads. The chart passes config: through toYaml, which corrupts !!binary bytes. Use configExistingSecretName for binary query payloads.
• ICMP needs a capability. On Linux, add NET_RAW to the container securityContext or the ping prober fails.

Risks

• Pre-1.0 versioning. Minor releases have changed config validation and logging. Read the release notes before each upgrade.
• Single vantage point. One exporter measures one network path. If the exporter's network fails, every probe fails together. A dead-man's-switch alert, or a probe of a known-good external host, separates "everything is down" from "the prober is down."
• Exposed /probe endpoint. Anyone who can reach port 9115 can make the exporter send requests to arbitrary targets. Keep it cluster-internal, or protect it with --web.config.file.
• Licence and lock-in are low. It is Apache 2.0 and governed by the Prometheus project. Its output is ordinary Prometheus metrics, so dashboards and rules move with the data.

Alternatives

• Grafana Synthetic Monitoring — hosted probes from many regions plus scripted multi-step checks. Pick it when geographic coverage or browser flows are important and a hosted service is acceptable.
• Uptime Kuma — a self-hosted uptime monitor with its own UI, status pages and notifications. Pick it when there is no Prometheus and a click-to-configure tool is enough.
• Gatus — a self-hosted health dashboard with endpoint checks and conditions in YAML. Pick it for a status page and simple alerts without a metrics pipeline.
• In-cluster probes and app metrics — Kubernetes readiness probes and RED metrics from the app. Keep them in all cases; they show the service's own view, not the path from outside.

Related

• Prometheus — scrapes the exporter and evaluates the alert rules.
• Pyrra — builds the availability SLOs from probe_success.
• Alertmanager — routes the uptime and burn-rate alerts to email.
• Grafana — dashboards for probe latency and certificate expiry.
• Cloudflare and Traefik — the public path that each probe goes through.
• Official: Configuration reference, Multi-target exporter guide, Releases, Helm chart.