Prometheus Blackbox Monitoring for Sites and APIs

Short answer. blackbox_exporter is a standalone Prometheus service that probes endpoints "from the outside": it performs an HTTP request, TCP connect, DNS resolution, or ICMP Ping and exposes metrics like probe_success, probe_duration_seconds, and probe_http_status_code. Prometheus periodically scrapes the exporter, passing it a target through relabeling, and Alertmanager sends notifications on failure. It is the ideal tool for availability checks without an agent on the target host.

Why you need blackbox_exporter

Regular exporters (node_exporter, cAdvisor) look at a system "from the inside." Blackbox looks "from the outside" — like a user. It answers the question "is my site responding" without installing an agent on the target machine. One exporter serves many targets — the list arrives from Prometheus on every scrape.

• http_2xx — checks HTTP/SSL/TLS проверку, response code, redirects, SSL expiry;
• tcp_connect — TCP port availability (DB, queue, SMTP);
• dns — record resolution and answer validation;
• icmp — ping (requires raw socket privileges).

blackbox_exporter config

Modules are defined in blackbox.yml. Each module is a probe preset: protocol, timeout, expected codes, IP version.

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      valid_http_versions: ["HTTP/1.1", "HTTP/2.0"]
      valid_status_codes: [200, 301, 302]
      method: GET
      follow_redirects: true
      fail_if_ssl: false
      fail_if_not_ssl: true
      preferred_ip_protocol: "ip4"
  tcp_connect:
    prober: tcp
    timeout: 5s
  dns_example:
    prober: dns
    dns:
      query_name: "example.com"
      query_type: "A"

The job in prometheus.yml

The key trick is relabeling: the target address is swapped for the exporter address, while the real URL is passed in the target parameter. That lets one exporter probe dozens of endpoints.

scrape_configs:
  - job_name: 'blackbox-http'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://example.com
          - https://api.example.com/health
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115

Key metrics

Metric	What it shows	Example alert
probe_success	1 = ok, 0 = failure	probe_success == 0
probe_duration_seconds	Total probe time	> 2s for 5 min
probe_http_status_code	HTTP response code	>= 500
probe_ssl_earliest_cert_expiry	SSL validity	< 14 days

Alerting rule

An alert for downtime and for an expiring certificate:

groups:
  - name: blackbox
    rules:
      - alert: EndpointDown
        expr: probe_success == 0
        for: 3m
        labels:
          severity: critical
        annotations:
          summary: "Endpoint {{ $labels.instance }} is down"
      - alert: SslCertExpiringSoon
        expr: probe_ssl_earliest_cert_expiry - time() < 14 * 24 * 3600
        for: 1h
        labels:
          severity: warning
        annotations:
          summary: "SSL on {{ $labels.instance }} expires in less than 14 days"

The for: 3m parameter is critical: without it, any single network error becomes an incident and wakes the on-call engineer at night for nothing.

The blind spot and the external layer

blackbox_exporter runs inside your own infrastructure. If the network or the data center it lives in goes down, the probe goes down too — and you get no alert about the real site outage. This is the classic blind spot of self-hosted monitoring.

enterno.io closes it as external synthetic monitoring: HTTP / SSL / ping / DNS checks run from independent RU / EU / US regions. Free tier offers 10 monitors at a 5-minute interval; paid tiers go to 1 minute and 30 seconds. It is a complement to Prometheus, not a replacement: the internal blackbox gives detailed diagnostics, the external checker gives an honest outside view and a backup alert channel via Telegram, Slack, email, and webhook.

FAQ

How is blackbox_exporter different from node_exporter?

node_exporter exposes system metrics from the inside (CPU, memory, disk). blackbox_exporter probes endpoints from the outside, emulating a user. They are different layers of monitoring.

Can I monitor an API endpoint and check the response body?

Yes, in the http module you can set fail_if_body_not_matches_regexp so the alert fires if the expected string is missing from the response.

Do I need a separate exporter per site?

No. One blackbox_exporter serves any number of targets — the list comes from prometheus.yml via relabeling.

How do I add an external check next to blackbox?

Spin up an external synthetic monitor on enterno.io and pull the metrics via API. You get an outside view with no dependency on your own network.

Want the outside view? Create a monitor at enterno.io/monitors and wire it into Prometheus/Grafana through the API v4. More on this: monitoring as code, health-check endpoints, API uptime monitoring.