Prometheus

Canonical Observability

Architecture:

Base version:

Channel	Revision	Published	Runs on
latest/stable	209	10 Sep 2024	Ubuntu 20.04
latest/candidate	210	10 Sep 2024	Ubuntu 20.04
latest/beta	210	01 Aug 2024	Ubuntu 20.04
latest/edge	216	13 Nov 2024	Ubuntu 20.04
1.0/stable	159	16 Feb 2024	Ubuntu 20.04
1.0/candidate	159	12 Dec 2023	Ubuntu 20.04
1.0/beta	159	12 Dec 2023	Ubuntu 20.04
1.0/edge	159	12 Dec 2023	Ubuntu 20.04

Learn to deploy on juju >

Platform:

charms.prometheus_k8s.v1.prometheus_remote_write

Docstrings Source code

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
- def __init__( self, relation_name)
class RelationInterfaceMismatchError
- def __init__( self, relation_name, expected_relation_interface, actual_relation_interface)
class RelationRoleMismatchError
- def __init__( self, relation_name, expected_relation_role, actual_relation_role)
class InvalidAlertRuleEvent
- def __init__( self, handle, errors, valid)
- def snapshot( self)
- def restore( self, snapshot)
class PrometheusRemoteWriteEndpointsChangedEvent
- def __init__( self, handle, relation_id)
- def snapshot( self)
- def restore( self, snapshot)
class InvalidAlertRulePathError
- def __init__( self, alert_rules_absolute_path, message)
class PrometheusRemoteWriteConsumerEvents
class PrometheusRemoteWriteConsumer
- def __init__( self, charm, relation_name, alert_rules_path)
- def reload_alerts( self)
- def endpoints( self)
class PrometheusRemoteWriteAlertsChangedEvent
- def __init__( self, handle, relation_id)
- def snapshot( self)
- def restore( self, snapshot)
class PrometheusRemoteWriteProviderConsumersChangedEvent
class PrometheusRemoteWriteProviderEvents
class PrometheusRemoteWriteProvider
- def __init__( self, charm, relation_name)
- def update_endpoint( self, relation)
- def alerts( self)
class CosTool
- def __init__( self, charm)
- def path( self)
- def apply_label_matchers( self, rules)
- def validate_alert_rules( self, rules)
- def inject_label_matchers( self, expression, topology)

Description

Raised if there is no relation with the given name. None

Methods

RelationNotFoundError. __init__( self , relation_name: str )

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 )

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 )

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

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

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 )

Description

Event descriptor for events raised by PrometheusRemoteWriteConsumer. None

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 )

API to manage a required relation with the prometheus_remote_write interface.

Arguments

charm

The charm object that instantiated this class.

relation_name

Name of the relation with the prometheus_remote_write interface as defined in metadata.yaml.

alert_rules_path

Path of the directory containing the 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 format of the dict is specified in the official prometheus docs: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write

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

Description

Event emitted when Prometheus remote_write alerts change. None

Description

Event descriptor for events raised by PrometheusRemoteWriteProvider. None

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

charm

The charm object that instantiated this class.

relation_name

Name of the relation with the prometheus_remote_write interface as defined in metadata.yaml.

server_url_func

A callable returning the URL for your prometheus server.

endpoint_path

The path of the server's remote_write endpoint.

PrometheusRemoteWriteProvider. update_endpoint( self , relation )

Triggers programmatically the update of the relation data.

Arguments

relation

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.

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

Prometheus

charms.prometheus_k8s.v1.prometheus_remote_write

Prometheus remote-write library.

class RelationNotFoundError

class RelationInterfaceMismatchError

class RelationRoleMismatchError

class InvalidAlertRuleEvent

class PrometheusRemoteWriteEndpointsChangedEvent

class InvalidAlertRulePathError

class PrometheusRemoteWriteConsumerEvents

class PrometheusRemoteWriteConsumer

class PrometheusRemoteWriteAlertsChangedEvent

class PrometheusRemoteWriteProviderConsumersChangedEvent

class PrometheusRemoteWriteProviderEvents

class PrometheusRemoteWriteProvider

class CosTool