---
title: Charmhub | Deploy Charmed Blackbox Exporter using Charmhub - The Open Operator
  Collection
description: Deploy the latest version of Charmed Blackbox Exporter as a Kubernetes
  Operator on any cloud.
url: https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes
---

# Charmed Blackbox Exporter

[Canonical Observability](https://charmhub.io/publisher/observability "View all packages from Canonical Observability")

* [Canonical Observability](https://charmhub.io/publisher/observability "View all packages from Canonical Observability")

Platform:

0.28/stable rev69-4-gff4c937

```
juju deploy blackbox-exporter-k8s --channel 0.28/stable
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

[Toggle side navigation](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#drawer)

## charms.blackbox\_exporter\_k8s.v0.blackbox\_probes

* [*Docstrings*Docstrings](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes)
  [*Code*Source code](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes/source-code)
* + Download

    Fetch library

    ```
    charmcraft fetch-lib charms.blackbox_exporter_k8s.v0.blackbox_probes
    ```

    [Download blackbox\_probes.py](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes/download)
  + *Last updated* 29 Apr 2026
  + *Revision* Library version 0.3

Blackbox Exporter Probes Library.

##### Overview

This document explains how to integrate with the Blackbox Exporter charm
for the purpose of providing a probes metrics endpoint to Prometheus.

##### Provider Library Usage

The Blackbox Exporter charm interacts with its datasources using this charm
library.
Charms seeking to expose probes for Blackbox, may do so
using the `BlackboxProbesProvider` object from this charm library.
For the simplest use cases, the BlackboxProbesProvider object requires
to be instantiated with a list of jobs with the endpoints to monitor.
A probe in blackbox is defined by a module and a static\_config target. Those
are then organised in a prometheus job for proper scraping.
The `BlackboxProbesProvider` constructor requires
the name of the relation over which a probe target
is exposed to the Blakcbox Exporter charm. This relation must use the
`blackbox_exporter_probes` interface.
The default name for the metrics endpoint relation is
`probes`. It is strongly recommended to use the same
relation name for consistency across charms and doing so obviates the
need for an additional constructor argument. The
`BlackboxProbesProvider` object may be instantiated as follows:

```
from charms.blackbox_k8s.v0.blackbox_probes import BlackboxProbesProvider

def __init__(self, *args):
    super().__init__(*args)
    ...
    self.probes_provider = BlackboxProbesProvider(
        self,
        probes=[{
            'params': {'module': ['http_2xx']},
            'static_configs': [
                {'targets': ['http://endpoint.com']}
            ]
        }]
    )
    ...
```

Note that the first argument (`self`) to `BlackboxProbesProvider` is
always a reference to the parent charm.

A `BlackboxProbesProvider` object will ensure that
the list of probes are provided to Blackbox which will ,
which will export them to Prometheus for scraping.
The list of probes is provided via the constructor argument `probes`.
The probes argument represents a necessary subset (module and static\_configs) of a
Prometheus scrape job using Python standard data structures.
This job specification is a subset of Prometheus' own
[scrape
configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config)
format but represented using Python data structures. More than one probe job
may be provided using the `probes` argument. Hence `probes` accepts a list
of dictionaries where each dictionary represents a subset of a `<scrape_config>`
object. The currently supported configuration subset is: `job_name`, `params`,
`static_configs`.

Suppose a client charm might want to monitor a particular service
via the http\_2xx module.
This may be done by providing the following data
structure as the value of `probes`.

```
[
    {
        'params': {
            'module': ['http_2xx']
        },
        "static_configs": [
            {
                "targets": ["http://endpoint.com"]
            }
        ]
    }
]
```

It is also possible to add labels to the given probes as such:

```
[
    {
        'params': {
            'module': ['http_2xx']
        },
        'static_configs': [
            {
                'targets': [address],
                'labels': {'name': endpoint-a}
            }
        ]
    }
]

Multiple jobs with different probes and labels are allowed, but
each job must be given a unique name:
```

[
{
"job\_name": "blackbox-icmp-job",
'params': {
'module': ['http\_2xx']
},
'static\_configs': [
{
'targets': [address],
'labels': {'name': endpoint-a}
}
]
},
{
"job\_name": "blackbox-http-2xx",
'params': {
'module': ['icmp']
},
'static\_configs': [
{
'targets': [address],
'labels': {'name': endpoint-a}
}
]
}
]

```
It is also possible for the client charm to define new probing modules.
This is achieved by providing the `BlackboxProbesProvider`
constructor an optional argument (`modules`), that represents a blackbox module.
For details on how to write pass a module, see the
[docs upstream](https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md).
Further examples are provided [upstream](https://github.com/prometheus/blackbox_exporter/blob/master/example.yml).
An example of defining a module is:

modules={
            "http_2xx_longer_timeout": {
                "prober": "http"
                "timeout": "30s"  # default is 5s
            }
        }

## Consumer Library Usage

The `BlackboxProbesRequirer` object may be used by the Blackbox Exporter
charms to retrieve the probes to be monitored. For this
purposes a Blackbox Exporter charm needs to do two things:

1. Instantiate the `BlackboxProbesRequirer` object by providing it a
reference to the parent (Blackbox Exporter) charm and, optionally, the name of
the relation that the Blackbox Exporter charm uses to interact with probes
targets. This relation must conform to the `blackbox_exporter_probes`
interface and it is strongly recommended that this relation be named
`probes` which is its default value.

For example a Blackbox Exporter may instantiate the
`BlackboxProbesRequirer` in its constructor as follows

    from charms.blackbox_k8s.v0.blackbox_probes import BlackboxProbesRequirer

    def __init__(self, *args):
        super().__init__(*args)
        ...
        self.probes_requirer = BlackboxProbesRequirer(
            charm=self,
            relation_name="probes",
        )
        ...

The probes requirer must be instantiated before the prometheus_scrape MetricsEndpoint Provider,
because Blackbox defines new metrics endpoints to send to Prometheus.

2. A Blackbox Exporter charm also needs to respond to the
`TargetsChangedEvent` event of the `BlackboxProbesRequirer` by adding itself as
an observer for these events, as in

    self.framework.observe(
        self.probes_requirer.on.targets_changed,
        self._on_scrape_targets_changed,
    )

In responding to the `TargetsChangedEvent` event the Blackbox Exporter
charm must update its configuration so that any new probe
is added and/or old ones removed from the list.
For this purpose the `BlackboxProbesRequirer` object
exposes a `probes()` method that returns a list of probes jobs. Each
element of this list is a probes configuration to be added to the list of jobs for
Prometheus to monitor.
Same goes for the list of client charm defined modules. The `BlackboxProbesRequirer` object
exposes a `modules()` method that returns a dict of the new modules to be added to the
Blackbox configuration file.
```

---

Index

* [class DataValidationError](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#datavalidationerror)
* [class DatabagModel](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#databagmodel)
* + [def load(
    cls,
    databag)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#databagmodel-load)
* + [def dump(
    self,
    databag,
    clear)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#databagmodel-dump)
* [class ProbesStaticConfigModel](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#probesstaticconfigmodel)
* + [class Config](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#probesstaticconfigmodel-config)
* [class ProbesJobModel](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#probesjobmodel)
* + [class Config](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#probesjobmodel-config)
* [class ListProbesModel](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#listprobesmodel)
* [class ModuleConfig](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#moduleconfig)
* + [class Config](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#moduleconfig-config)
* [class ScrapeMetadataModel](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#scrapemetadatamodel)
* + [class Config](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#scrapemetadatamodel-config)
* [class ApplicationDataModel](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#applicationdatamodel)
* [class InvalidProbeEvent](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#invalidprobeevent)
* + [def \_\_init\_\_(
    self,
    handle,
    errors)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#invalidprobeevent-__init__)
* + [def snapshot(
    self)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#invalidprobeevent-snapshot)
* + [def restore(
    self,
    snapshot)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#invalidprobeevent-restore)
* [class BlackboxProbesProvider](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesprovider)
* + [def \_\_init\_\_(
    self,
    charm,
    probes,
    modules,
    refresh\_event,
    relation\_name)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesprovider-__init__)
* + [def get\_status(
    self)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesprovider-get_status)
* [class TargetsChangedEvent](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#targetschangedevent)
* + [def \_\_init\_\_(
    self,
    handle,
    relation\_id)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#targetschangedevent-__init__)
* + [def snapshot(
    self)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#targetschangedevent-snapshot)
* + [def restore(
    self,
    snapshot)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#targetschangedevent-restore)
* [class MonitoringEvents](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#monitoringevents)
* [class BlackboxProbesRequirer](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesrequirer)
* + [def \_\_init\_\_(
    self,
    charm,
    relation\_name)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesrequirer-__init__)
* + [def get\_status(
    self)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesrequirer-get_status)
* + [def probes(
    self)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesrequirer-probes)
* + [def modules(
    self)](https://charmhub.io/blackbox-exporter-k8s/libraries/blackbox_probes#blackboxprobesrequirer-modules)

#### class DataValidationError

Description

Raised when data validation fails on IPU relation data. None

#### class DatabagModel

Description

Base databag model. None

Methods

DatabagModel.
load(

cls

,
databag: MutableMapping
)

Description

Load this model from a Juju databag. None

DatabagModel.
dump(

*self*

,
databag

,
clear: bool
)

Write the contents of this model to Juju databag.

Arguments

databag

the databag to write the data to.

clear

ensure the databag is cleared before writing it.

#### class ProbesStaticConfigModel

Methods

ProbesStaticConfigModel.
Config

#### class ProbesJobModel

Methods

ProbesJobModel.
Config

#### class ListProbesModel

#### class ModuleConfig

Methods

ModuleConfig.
Config

#### class ScrapeMetadataModel

Methods

ScrapeMetadataModel.
Config

#### class ApplicationDataModel

#### class InvalidProbeEvent

Description

Event emitted when alert rule files are not valid. None

Methods

InvalidProbeEvent.
\_\_init\_\_(

*self*

,
handle

,
errors: str
)

InvalidProbeEvent.
snapshot(

*self*
)

Description

Save error information. None

InvalidProbeEvent.
restore(

*self*

,
snapshot
)

Description

Restore error information. None

#### class BlackboxProbesProvider

Description

A provider object for Blackbox Exporter probes. None

Methods

BlackboxProbesProvider.
\_\_init\_\_(

*self*

,
charm: CharmBase

,
probes

,
modules

,
refresh\_event

,
relation\_name: str
)

BlackboxProbesProvider.
get\_status(

*self*
)

Collect the status of probes and errors from stored state.

Returns

StatusBase

Status representing the state of the probes collection.

* ActiveStatus: All probes are valid and ready to be used.
* BlockedStatus: Errors occurred during probes parsing and require intervention.

#### class TargetsChangedEvent

Description

Event emitted when Blackbox Exporter scrape targets change. None

Methods

TargetsChangedEvent.
\_\_init\_\_(

*self*

,
handle

,
relation\_id
)

TargetsChangedEvent.
snapshot(

*self*
)

Description

Save scrape target relation information. None

TargetsChangedEvent.
restore(

*self*

,
snapshot
)

Description

Restore scrape target relation information. None

#### class MonitoringEvents

Description

Event descriptor for events raised by `BlackboxProbesRequirer`. None

#### class BlackboxProbesRequirer

Description

A requirer object for Blackbox Exporter probes. None

Methods

BlackboxProbesRequirer.
\_\_init\_\_(

*self*

,
charm: CharmBase

,
relation\_name: str
)

"A requirer object for Blackbox Exporter probes.

Arguments

charm

a `CharmBase` instance that manages this
instance of the Blackbox Exporter service.

relation\_name

an optional string name of the relation between `charm`
and the Blackbox Exporter charmed service. The default is "probes".

BlackboxProbesRequirer.
get\_status(

*self*
)

Collect the status of probes and errors from stored state.

Returns

StatusBase

Status representing the state of the probes collection.

* ActiveStatus: All probes are valid and ready to be used.
* BlockedStatus: Errors occurred during probes parsing and require intervention.
* WaitingStatus: Probes are still being fetched or processed.

BlackboxProbesRequirer.
probes(

*self*
)

Fetch the list of probes to scrape, if they need update

Returns

A list consisting of all the static probes configurations
for each related `BlackboxExporterProvider'.

BlackboxProbesRequirer.
modules(

*self*
)

Fetch the dict of blackbox modules to configure.

Returns

A dict consisting of all the modueles configurations
for each related `BlackboxExporterProvider`.