Prometheus
| Channel | Revision | Published | Runs on |
|---|---|---|---|
| 1/stable | 247 | 14 May 2025 | |
| 1/candidate | 247 | 14 May 2025 | |
| 1/beta | 247 | 14 May 2025 | |
| 1/edge | 247 | 14 May 2025 | |
| 2/edge | 254 | 14 Jul 2025 |
juju deploy prometheus-k8s --channel 1/stable
Deploy Kubernetes operators easily with Juju, the Universal Operator Lifecycle Manager. Need a Kubernetes cluster? Install MicroK8s to create a full CNCF-certified Kubernetes system in under 60 seconds.
Platform:
charms.prometheus_k8s.v1.prometheus_remote_write
-
- Last updated 23 Jun 2025
- Revision Library version 1.8
Prometheus remote-write library.
This library facilitates the integration of the prometheus_remote_write interface.
Source code can be found on GitHub at: https://github.com/canonical/prometheus-k8s-operator/tree/main/lib/charms/prometheus_k8s
Charms that need to push data to a charm exposing the Prometheus remote_write API,
should use the PrometheusRemoteWriteConsumer. Charms that operate software that exposes
the Prometheus remote_write API, that is, they can receive metrics data over remote_write,
should use the PrometheusRemoteWriteProducer.
Index
class RelationNotFoundError
Description
Raised if there is no relation with the given name. None
Methods
RelationNotFoundError. __init__( self , relation_name: str )
class RelationInterfaceMismatchError
Description
Raised if the relation with the given name has a different interface. None
Methods
RelationInterfaceMismatchError. __init__( self , relation_name: str , expected_relation_interface: str , actual_relation_interface: str )
class RelationRoleMismatchError
Description
Raised if the relation with the given name has a different direction. None
Methods
RelationRoleMismatchError. __init__( self , relation_name: str , expected_relation_role: RelationRole , actual_relation_role: RelationRole )
class InvalidAlertRuleEvent
Event emitted when alert rule files are not parsable.
Description
Enables us to set a clear status on the provider.
Methods
InvalidAlertRuleEvent. __init__( self , handle , errors: str , valid: bool )
InvalidAlertRuleEvent. snapshot( self )
Description
Save alert rule information. None
InvalidAlertRuleEvent. restore( self , snapshot )
Description
Restore alert rule information. None
class PrometheusRemoteWriteEndpointsChangedEvent
Description
Event emitted when Prometheus remote_write endpoints change. None
Methods
PrometheusRemoteWriteEndpointsChangedEvent. __init__( self , handle , relation_id )
PrometheusRemoteWriteEndpointsChangedEvent. snapshot( self )
Description
Save scrape Prometheus remote_write information. None
PrometheusRemoteWriteEndpointsChangedEvent. restore( self , snapshot )
Description
Restore scrape Prometheus remote_write information. None
class InvalidAlertRulePathError
Description
Raised if the alert rules folder cannot be found or is otherwise invalid. None
Methods
InvalidAlertRulePathError. __init__( self , alert_rules_absolute_path: str , message: str )
class PrometheusRemoteWriteConsumerEvents
Description
Event descriptor for events raised by PrometheusRemoteWriteConsumer. None
class PrometheusRemoteWriteConsumer
API that manages a required prometheus_remote_write relation.
Description
The PrometheusRemoteWriteConsumer is intended to be used by charms that need to push data to
other charms over the Prometheus remote_write API.
The PrometheusRemoteWriteConsumer object can be instantiated as follows in your charm:
from charms.prometheus_k8s.v1.prometheus_remote_write import PrometheusRemoteWriteConsumer
def __init__(self, *args):
...
self.remote_write_consumer = PrometheusRemoteWriteConsumer(self)
...
The PrometheusRemoteWriteConsumer assumes that, in the metadata.yaml of your charm,
you declare a required relation as follows:
requires:
send-remote-write: # Relation name
interface: prometheus_remote_write # Relation interface
The charmed operator is expected to use the PrometheusRemoteWriteConsumer as follows:
def __init__(self, *args):
...
self.remote_write_consumer = PrometheusRemoteWriteConsumer(self)
...
self.framework.observe(
self.remote_write_consumer.on.endpoints_changed,
self._handle_endpoints_changed,
)
The endpoints_changed event will fire in situations such as provider ip change (e.g.
relation created, provider upgrade, provider pod churn) or provider config change (e.g.
metadata settings).
Then, inside the logic of _handle_endpoints_changed, the updated endpoint list is
retrieved with:
self.remote_write_consumer.endpoints
which returns a dictionary structured like the Prometheus configuration object (see https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write).
Regarding the default relation name, send-remote-write: if you choose to change it,
you would need to explicitly provide it to the PrometheusRemoteWriteConsumer via the
relation_name constructor argument. (The relation interface, on the other hand, is
fixed and, if you were to change it, your charm would not be able to relate with other
charms using the correct relation interface. The library prevents you from doing that by
raising an exception.)
In any case, it is strongly discouraged to change the relation name: having consistent
relation names across charms that do similar things is good practice and more
straightforward for the users of your charm. The one exception to the rule above,
is if your charm needs to both consume and provide a relation using the
prometheus_remote_write interface, in which case changing the relation name to
differentiate between "incoming" and "outgoing" remote write interactions is necessary.
It is also possible to specify alert rules. By default, this library will search
<charm_parent_dir>/prometheus_alert_rules, which in standard charm
layouts resolves to src/prometheus_alert_rules. Each set of alert rules, grouped
by the topology identifier, goes into a separate *.rule file.
If the syntax of a rule is invalid, the MetricsEndpointProvider logs an error and
does not load the particular rule.
To avoid false positives and false negatives the library will inject label filters
automatically in the PromQL expression. For example if the charm provides an
alert rule with an expr like this one:
expr: up < 1
it will be modified with label filters ensuring that the only timeseries evaluated are those scraped from this charm, and no other.
expr: up{juju_application="traefik",
juju_charm="traefik-k8s",
juju_model="cos",
juju_model_uuid="b5ed878d-2671-42e8-873a-e8d58c0ec325"
} < 1
labels:
juju_application: traefik
juju_charm: traefik-k8s
juju_model: cos
juju_model_uuid: b5ed878d-2671-42e8-873a-e8d58c0ec325
Methods
PrometheusRemoteWriteConsumer. __init__( self , charm: CharmBase , relation_name: str , alert_rules_path: str , refresh_event )
API to manage a required relation with the prometheus_remote_write interface.
Arguments
The charm object that instantiated this class.
Name of the relation with the prometheus_remote_write interface as
defined in metadata.yaml.
Path of the directory containing the alert rules.
an optional bound event or list of bound events which will be observed to re-set alerts data.
Flag to toggle forwarding of charmed alert rules.
PrometheusRemoteWriteConsumer. reload_alerts( self )
Description
Reload alert rules from disk and push to relation data. None
PrometheusRemoteWriteConsumer. endpoints( self )
A config object ready to be dropped into a prometheus config file.
Returns
A list of dictionaries where each dictionary provides information about a single remote_write endpoint.
Description
The endpoints are deduplicated.
The format of the dict is specified in the official prometheus docs: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write
class PrometheusRemoteWriteAlertsChangedEvent
Description
Event emitted when Prometheus remote_write alerts change. None
Methods
PrometheusRemoteWriteAlertsChangedEvent. __init__( self , handle , relation_id )
PrometheusRemoteWriteAlertsChangedEvent. snapshot( self )
Description
Save Prometheus remote_write information. None
PrometheusRemoteWriteAlertsChangedEvent. restore( self , snapshot )
Description
Restore Prometheus remote_write information. None
class PrometheusRemoteWriteProviderConsumersChangedEvent
Description
Event emitted when Prometheus remote_write alerts change. None
class PrometheusRemoteWriteProviderEvents
Description
Event descriptor for events raised by PrometheusRemoteWriteProvider. None
class PrometheusRemoteWriteProvider
API that manages a provided prometheus_remote_write relation.
Description
The PrometheusRemoteWriteProvider is intended to be used by charms whose workloads need
to receive data from other charms' workloads over the Prometheus remote_write API.
The PrometheusRemoteWriteProvider object can be instantiated as follows in your charm:
from charms.prometheus_k8s.v1.prometheus_remote_write import PrometheusRemoteWriteProvider
def __init__(self, *args):
...
self.remote_write_provider = PrometheusRemoteWriteProvider(self)
...
The PrometheusRemoteWriteProvider assumes that, in the metadata.yaml of your charm,
you declare a provided relation as follows:
provides:
receive-remote-write: # Relation name
interface: prometheus_remote_write # Relation interface
About the name of the relation managed by this library: technically, you could change
the relation name, receive-remote-write, but that requires you to provide the new
relation name to the PrometheusRemoteWriteProducer via the relation_name constructor
argument. (The relation interface, on the other hand, is immutable and, if you were to change
it, your charm would not be able to relate with other charms using the right relation
interface. The library prevents you from doing that by raising an exception.) In any case, it
is strongly discouraged to change the relation name: having consistent relation names across
charms that do similar things is a very good thing for the people that will use your charm.
The one exception to the rule above, is if you charm needs to both consume and provide a
relation using the prometheus_remote_write interface, in which case changing the relation
name to differentiate between "incoming" and "outgoing" remote write interactions is necessary.
Methods
PrometheusRemoteWriteProvider. __init__( self , charm: CharmBase , relation_name: str )
API to manage a provided relation with the prometheus_remote_write interface.
Arguments
The charm object that instantiated this class.
Name of the relation with the prometheus_remote_write interface as
defined in metadata.yaml.
A callable returning the URL for your prometheus server.
The path of the server's remote_write endpoint.
PrometheusRemoteWriteProvider. update_endpoint( self , relation )
Triggers programmatically the update of the relation data.
Arguments
An optional instance of class:ops.model.Relation to update.
If not provided, all instances of the prometheus_remote_write
relation are updated.
Description
This method should be used when the charm relying on this library needs
to update the relation data in response to something occurring outside
the prometheus_remote_write relation lifecycle, e.g., in case of a
host address change because the charmed operator becomes connected to an
Ingress after the prometheus_remote_write relation is established.
PrometheusRemoteWriteProvider. alerts( self )
Fetch alert rules from all relations.
Returns
a dictionary mapping the name of an alert rule group to the group.
Description
A Prometheus alert rules file consists of a list of "groups". Each
group consists of a list of alerts (rules) that are sequentially
executed. This method returns all the alert rules provided by each
related metrics provider charm. These rules may be used to generate a
separate alert rules file for each relation since the returned list
of alert groups are indexed by relation ID. Also, for each relation ID
associated scrape metadata such as Juju model, UUID and application
name are provided so the unique name may be generated for the rules
file. For each relation the structure of data returned is a dictionary
with four keys
- groups
- model
- model_uuid
- application
The value of the groups key is such that it may be used to generate
a Prometheus alert rules file directly using yaml.dump but the
groups key itself must be included as this is required by Prometheus,
for example as in yaml.safe_dump({"groups": alerts["groups"]}).
The PrometheusRemoteWriteProvider accepts a list of rules and these
rules are all placed into one group.
class CosTool
Description
Uses cos-tool to inject label matchers into alert rule expressions and validate rules. None
Methods
CosTool. __init__( self , charm )
CosTool. path( self )
Description
Lazy lookup of the path of cos-tool. None
CosTool. apply_label_matchers( self , rules )
Description
Will apply label matchers to the expression of all alerts in all supplied groups. None
CosTool. validate_alert_rules( self , rules: dict )
Description
Will validate correctness of alert rules, returning a boolean and any errors. None
CosTool. inject_label_matchers( self , expression , topology )
Description
Add label matchers to an expression. None