---
title: "prometheus.exporter.blackbox | Grafana Agent documentation"
description: "Learn about prometheus.exporter.blackbox"
---

# prometheus.exporter.blackbox

The `prometheus.exporter.blackbox` component embeds [`blackbox_exporter`](https://github.com/prometheus/blackbox_exporter). `blackbox_exporter` lets you collect blackbox metrics (probes) and expose them as Prometheus metrics.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.blackbox "LABEL" {
  target {
    name    = "example"
    address = "EXAMPLE_ADDRESS"
  }
}
```

## Arguments

The following arguments can be used to configure the exporter’s behavior. Omitted fields take their default values.

Expand table

| Name                   | Type                 | Description                                                      | Default  | Required |
|------------------------|----------------------|------------------------------------------------------------------|----------|----------|
| `config_file`          | `string`             | blackbox\_exporter configuration file path.                      |          | no       |
| `config`               | `string` or `secret` | blackbox\_exporter configuration as inline string.               |          | no       |
| `probe_timeout_offset` | `duration`           | Offset in seconds to subtract from timeout when probing targets. | `"0.5s"` | no       |

Either `config_file` or `config` must be specified. The `config_file` argument points to a YAML file defining which blackbox\_exporter modules to use. The `config` argument must be a YAML document as string defining which blackbox\_exporter modules to use. `config` is typically loaded by using the exports of another component. For example,

- `local.file.LABEL.content`
- `remote.http.LABEL.content`
- `remote.s3.LABEL.content`

See [blackbox\_exporter](https://github.com/prometheus/blackbox_exporter/blob/master/example.yml) for details on how to generate a config file.

## Blocks

The following blocks are supported inside the definition of `prometheus.exporter.blackbox` to configure collector-specific options:

Expand table

| Hierarchy | Name                    | Description                   | Required |
|-----------|-------------------------|-------------------------------|----------|
| target    | [target](#target-block) | Configures a blackbox target. | yes      |

### target block

The `target` block defines an individual blackbox target. The `target` block may be specified multiple times to define multiple targets. `name` attribute is required and will be used in the target’s `job` label.

Expand table

| Name      | Type          | Description                         | Default | Required |
|-----------|---------------|-------------------------------------|---------|----------|
| `name`    | `string`      | The name of the target to probe.    |         | yes      |
| `address` | `string`      | The address of the target to probe. |         | yes      |
| `module`  | `string`      | Blackbox module to use to probe.    | `""`    | no       |
| `labels`  | `map(string)` | Labels to add to the target.        |         | no       |

Labels specified in the `labels` argument will not override labels set by `blackbox_exporter`.

## Exported fields

The following fields are exported and can be referenced by other components.

Expand table

| Name      | Type                | Description                                               |
|-----------|---------------------|-----------------------------------------------------------|
| `targets` | `list(map(string))` | The targets that can be used to collect exporter metrics. |

For example, the `targets` can either be passed to a `discovery.relabel` component to rewrite the targets’ label sets or to a `prometheus.scrape` component that collects the exposed metrics.

The exported targets use the configured [in-memory traffic](/docs/agent/v0.43/flow/concepts/component_controller/#in-memory-traffic) address specified by the [run command](/docs/agent/v0.43/flow/reference/cli/run/).

## Component health

`prometheus.exporter.blackbox` is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

## Debug information

`prometheus.exporter.blackbox` does not expose any component-specific debug information.

## Debug metrics

`prometheus.exporter.blackbox` does not expose any component-specific debug metrics.

## Examples

### Collect metrics using a blackbox exporter config file

This example uses a [`prometheus.scrape` component](../prometheus.scrape/) to collect metrics from `prometheus.exporter.blackbox`. It adds an extra label, `env="dev"`, to the metrics emitted by the `grafana` target. The `example` target does not have any added labels.

The `config_file` argument is used to define which `blackbox_exporter` modules to use. You can use the [blackbox example config file](https://github.com/prometheus/blackbox_exporter/blob/master/example.yml).

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.blackbox "example" {
  config_file = "blackbox_modules.yml"

  target {
    name    = "example"
    address = "http://example.com"
    module  = "http_2xx"
  }

  target {
    name    = "grafana" 
    address = "http://grafana.com"
    module  = "http_2xx"
    labels = {
      "env" = "dev",
    }
  }
}

// Configure a prometheus.scrape component to collect Blackbox metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.blackbox.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = PROMETHEUS_REMOTE_WRITE_URL

    basic_auth {
      username = USERNAME
      password = PASSWORD
    }
  }
}
```

Replace the following:

- `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote\_write-compatible server to send metrics to.
- `USERNAME`: The username to use for authentication to the remote\_write API.
- `PASSWORD`: The password to use for authentication to the remote\_write API.

### Collect metrics using an embedded configuration

This example is the same above with using an embedded configuration:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.exporter.blackbox "example" {
  config = "{ modules: { http_2xx: { prober: http, timeout: 5s } } }"

  target {
    name    = "example"
    address = "http://example.com"
    module  = "http_2xx"
  }

  target {
    name    = "grafana"
    address = "http://grafana.com"
    module  = "http_2xx"
    labels = {
      "env" = "dev",
    }
  }
}

// Configure a prometheus.scrape component to collect Blackbox metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.blackbox.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = PROMETHEUS_REMOTE_WRITE_URL

    basic_auth {
      username = USERNAME
      password = PASSWORD
    }
  }
}
```

Replace the following:

- `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote\_write-compatible server to send metrics to.
- `USERNAME`: The username to use for authentication to the remote\_write API.
- `PASSWORD`: The password to use for authentication to the remote\_write API.

## Compatible components

`prometheus.exporter.blackbox` has exports that can be consumed by the following components:

- Components that consume [Targets](../../compatibility/#targets-consumers)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.