README

Blackbox exporter


![Docker Repository on Quay][quay]
![Docker Pulls][hub]

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:

    ./blackbox_exporter 


 Using the docker image

Images are published to [Quay][quay] (quay.io/prometheus/blackbox-exporter), [Docker Hub][hub] (prom/blackbox-exporter) and the [GitHub Container Registry][ghcr] (ghcr.io/prometheus/blackbox-exporter).

Note: You may want to enable 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

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 .

 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

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 --lo