blackbox-exporter-k8s

Charmed Blackbox Exporter

  • Canonical Observability
Channel Revision Published Runs on
latest/stable 25 18 Mar 2025
Ubuntu 22.04 Ubuntu 20.04
latest/stable 1 16 Jan 2024
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 26 01 Apr 2025
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 1 12 Dec 2023
Ubuntu 22.04 Ubuntu 20.04
latest/beta 27 01 Apr 2025
Ubuntu 22.04 Ubuntu 20.04
latest/beta 1 22 Nov 2023
Ubuntu 22.04 Ubuntu 20.04
latest/edge 31 Today
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/edge 30 Today
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/edge 27 18 Mar 2025
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
juju deploy blackbox-exporter-k8s
Show information

Learn to deploy on juju >

Platform:

charms.blackbox_exporter_k8s.v0.blackbox_probes

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

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.