Prometheus
- By Canonical Observability
Channel | Revision | Published | Runs on |
---|---|---|---|
latest/stable | 103 | 31 Jan 2023 | |
latest/candidate | 103 | 31 Jan 2023 | |
latest/beta | 103 | 31 Jan 2023 | |
latest/edge | 117 | Yesterday | |
1.0/stable | 103 | 31 Jan 2023 | |
1.0/candidate | 103 | 31 Jan 2023 | |
1.0/beta | 103 | 31 Jan 2023 | |
1.0/edge | 103 | 31 Jan 2023 |
juju deploy prometheus-k8s
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 10 Mar 2023
- Revision Library version 0
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
InvalidAlertRuleEvent. restore( self , snapshot )
Description
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. 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
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 )
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: 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
PrometheusRemoteWriteConsumer. reload_alerts( self )
Description
PrometheusRemoteWriteConsumer. endpoints( self )
A config object ready to be dropped into a prometheus config file.
Returns
Description
class PrometheusRemoteWriteAlertsChangedEvent
Description
Event emitted when Prometheus remote_write alerts change. None
Methods
PrometheusRemoteWriteAlertsChangedEvent. __init__( self , handle , relation_id )
PrometheusRemoteWriteAlertsChangedEvent. snapshot( self )
Description
PrometheusRemoteWriteAlertsChangedEvent. restore( self , snapshot )
Description
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.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. update_endpoint( self , relation )
Triggers programmatically the update of the relation data.
Arguments
Description
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