Prometheus
- By Balbir Thomas
| Channel | Version | Revision | Published | Runs on |
|---|---|---|---|---|
| latest/candidate | 55 | 55 | 08 Aug 2022 | |
| latest/beta | 55 | 55 | 08 Aug 2022 | |
| latest/edge | 70 | 70 | 22 Sep 2022 |
juju deploy prometheus-k8s --channel candidate
You will need Juju 2.9 to be able to run this command. Learn how to upgrade to Juju 2.9.
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.v0.prometheus_remote_write
-
- Last updated 03 Aug 2022
- Revision Library version 0
Prometheus remote-write library.
This library facilitates the integration of the prometheus_remote_write interface.
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
InvalidAlertRuleEvent. restore( self , snapshot )
Description
def _is_official_alert_rule_format(rules_dict: dict)
Are alert rules in the upstream format as supported by Prometheus.
Arguments
Returns
Description
Alert rules in dictionary format are in "official" form if they contain a "groups" key, since this implies they contain a list of alert rule groups.
def _is_single_alert_rule_format(rules_dict: dict)
Are alert rules in single rule format.
Returns
Description
The Prometheus charm library supports reading of alert rules in a custom format that consists of a single alert rule per file. This does not conform to the official Prometheus alert rule file format which requires that each alert rules file consists of a list of alert rule groups and each group consists of a list of alert rules. Alert rules in dictionary form are considered to be in single rule format if in the least it contains two keys corresponding to the alert rule name and alert expression.
class AlertRules
Utility class for amalgamating prometheus alert rule files and injecting juju topology.
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
AlertRules. _from_file( self , root_path: Path , file_path: Path )
Read a rules file from path, injecting juju topology.
Arguments
Returns
AlertRules. _group_name( self , root_path: str , file_path: str , group_name: str )
Generate group name from path and topology.
Arguments
Returns
Description
AlertRules. _is_already_modified( self , name: str )
Description
AlertRules. _multi_suffix_glob( cls , dir_path: Path , suffixes , recursive: bool )
Helper function for getting all files in a directory that have a matching suffix.
Arguments
Returns
AlertRules. _from_dir( self , dir_path: Path , recursive: bool )
Read all rule files in a directory.
Arguments
Returns
Description
AlertRules. add_path( self , path: str )
Add rules from a dir path.
Arguments
Returns
Description
AlertRules. as_dict( self )
Return standard alert rules file in dict representation.
Returns
def
_validate_relation_by_interface_and_direction(
charm: CharmBase,
relation_name: str,
expected_relation_interface: str,
expected_relation_role: RelationRole
)
Verifies that a relation has the necessary characteristics.
Arguments
Description
Verifies that the `relation_name` provided: (1) exists in metadata.yaml, (2) declares as interface the interface name passed as `relation_interface` and (3) has the right "direction", i.e., it is a relation that `charm` provides or requires.
class PrometheusRemoteWriteEndpointsChangedEvent
Description
Event emitted when Prometheus remote_write endpoints change. None
Methods
PrometheusRemoteWriteEndpointsChangedEvent. __init__( self , handle , relation_id )
PrometheusRemoteWriteEndpointsChangedEvent. snapshot( self )
Description
PrometheusRemoteWriteEndpointsChangedEvent. restore( self , snapshot )
Description
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 )
def _resolve_dir_against_charm_path(charm: CharmBase)
Resolve the provided path items against the directory of the main file.
Description
Look up the directory of the main .py file being executed. This is normally going to be the charm.py file of the charm including this library. Then, resolve the provided path elements and, if the result path exists and is a directory, return its absolute path; otherwise, return `None`.
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.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: receive-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 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, `receive-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 negatives in the evaluation of your alert rules, you must always add the `%%juju_topology%%` token as label filters in the PromQL expression, e.g.: alert: UnitUnavailable expr: up{%%juju_topology%%} < 1 for: 0m labels: severity: critical annotations: summary: Unit {{ $labels.juju_model }}/{{ $labels.juju_unit }} unavailable description: > The unit {{ $labels.juju_model }} {{ $labels.juju_unit }} is unavailable The `%%juju_topology%%` token will be replaced with label filters ensuring that the only timeseries evaluated are those scraped from this charm, and no other. Failing to ensure that the `%%juju_topology%%` token is applied to each and every of the queries timeseries will lead to unpredictable alert rule evaluation if your charm is deployed multiple times and various of its instances are monitored by the same Prometheus.
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
PrometheusRemoteWriteConsumer. _handle_endpoints_changed( self , event: RelationEvent )
PrometheusRemoteWriteConsumer. _push_alerts_on_relation_joined( self , event: RelationEvent )
PrometheusRemoteWriteConsumer. _push_alerts_to_all_relation_databags( self , _ )
PrometheusRemoteWriteConsumer. _push_alerts_to_relation_databag( self , relation: Relation )
PrometheusRemoteWriteConsumer. reload_alerts( self )
Description
PrometheusRemoteWriteConsumer. endpoints( self )
A config object ready to be dropped into a prometheus config file.
Returns
Description
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.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
PrometheusRemoteWriteProvider. _on_relation_change( self , event: RelationEvent )
PrometheusRemoteWriteProvider. update_endpoint( self , relation: Relation )
Triggers programmatically the update of the relation data.
Arguments
Description
PrometheusRemoteWriteProvider. _set_endpoint_on_relation( self , relation: Relation )
Set the remote_write endpoint on relations.
Arguments
PrometheusRemoteWriteProvider. alerts( self )
Fetch alert rules from all relations.
Returns
Description
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
CosTool. apply_label_matchers( self , rules )
Description
CosTool. validate_alert_rules( self , rules: dict )
Description
CosTool. inject_label_matchers( self , expression , topology )
Description
CosTool. _get_tool_path( self )
CosTool. _exec( self , cmd )