Prometheus

By Canonical Observability

Architecture:

Channel	Revision	Published	Runs on
latest/stable	103	31 Jan 2023	Ubuntu 20.04
latest/candidate	103	31 Jan 2023	Ubuntu 20.04
latest/beta	103	31 Jan 2023	Ubuntu 20.04
latest/edge	117	Yesterday	Ubuntu 20.04
1.0/stable	103	31 Jan 2023	Ubuntu 20.04
1.0/candidate	103	31 Jan 2023	Ubuntu 20.04
1.0/beta	103	31 Jan 2023	Ubuntu 20.04
1.0/edge	103	31 Jan 2023	Ubuntu 20.04

Platform:

charms.prometheus_k8s.v0.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 AlertRules
- def __init__( self, topology)
- def add_path( self, path)
- def as_dict( self)
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, endpoint_schema, endpoint_address, endpoint_port, endpoint_path)
- 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

An `AlertRules` object supports aggregating alert rules from files and directories in both official and single rule file formats using the `add_path()` method. All the alert rules read are annotated with Juju topology labels and amalgamated into a single data structure in the form of a Python dictionary using the `as_dict()` method. Such a dictionary can be easily dumped into JSON format and exchanged over relation data. The dictionary can also be dumped into YAML format and written directly into an alert rules file that is read by Prometheus. Note that multiple `AlertRules` objects must not be written into the same file, since Prometheus allows only a single list of alert rule groups per alert rules file. The official Prometheus format is a YAML file conforming to the Prometheus documentation (https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/). The custom single rule format is a subsection of the official YAML, having a single alert rule, effectively "one alert per file".

Methods

AlertRules. __init__( self , topology )

Build and alert rule object.

Arguments

topology

an optional `JujuTopology` instance that is used to annotate all alert rules.

AlertRules. add_path( self , path: str )

Add rules from a dir path.

Arguments

path

either a rules file or a dir of rules files.

recursive

whether to read files recursively or not (no impact if `path` is a file).

Returns

True if path was added else False.

Description

All rules from files are aggregated into a data structure representing a single rule file. All group names are augmented with juju topology.

AlertRules. as_dict( self )

Return standard alert rules file in dict representation.

Returns

a dictionary containing a single list of alert rule groups. The list of alert rule groups is provided as value of the "groups" dictionary key.

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.v0.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: ```yaml 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. ```yaml 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.

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.v0.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 , endpoint_schema: str , endpoint_address: str , endpoint_port , endpoint_path: 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.

endpoint_schema

The URL schema for your remote_write endpoint. Defaults to `http`.

endpoint_address

The URL host for your remote_write endpoint as reachable from the client. This might be either the pod IP, or you might want to expose an address routable from outside the Kubernetes cluster, e.g., the host address of an Ingress. If not provided, it defaults to the unit's FQDN.

endpoint_port

The URL port for your remote_write endpoint. Defaults to `9090`.

endpoint_path

The URL path for your remote_write endpoint. Defaults to `/api/v1/write`.

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.v0.prometheus_remote_write

Prometheus remote-write library.

class RelationNotFoundError

class RelationInterfaceMismatchError

class RelationRoleMismatchError

class InvalidAlertRuleEvent

class AlertRules

class PrometheusRemoteWriteEndpointsChangedEvent

class InvalidAlertRulePathError

class PrometheusRemoteWriteConsumerEvents

class PrometheusRemoteWriteConsumer

class PrometheusRemoteWriteAlertsChangedEvent

class PrometheusRemoteWriteProviderConsumersChangedEvent

class PrometheusRemoteWriteProviderEvents

class PrometheusRemoteWriteProvider

class CosTool