--- /dev/null
+# Copyright 2023 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""## Overview.
+
+This document explains how to use the `JujuTopology` class to
+create and consume topology information from Juju in a consistent manner.
+
+The goal of the Juju topology is to uniquely identify a piece
+of software running across any of your Juju-managed deployments.
+This is achieved by combining the following four elements:
+
+- Model name
+- Model UUID
+- Application name
+- Unit identifier
+
+
+For a more in-depth description of the concept, as well as a
+walk-through of it's use-case in observability, see
+[this blog post](https://juju.is/blog/model-driven-observability-part-2-juju-topology-metrics)
+on the Juju blog.
+
+## Library Usage
+
+This library may be used to create and consume `JujuTopology` objects.
+The `JujuTopology` class provides three ways to create instances:
+
+### Using the `from_charm` method
+
+Enables instantiation by supplying the charm as an argument. When
+creating topology objects for the current charm, this is the recommended
+approach.
+
+```python
+topology = JujuTopology.from_charm(self)
+```
+
+### Using the `from_dict` method
+
+Allows for instantion using a dictionary of relation data, like the
+`scrape_metadata` from Prometheus or the labels of an alert rule. When
+creating topology objects for remote charms, this is the recommended
+approach.
+
+```python
+scrape_metadata = json.loads(relation.data[relation.app].get("scrape_metadata", "{}"))
+topology = JujuTopology.from_dict(scrape_metadata)
+```
+
+### Using the class constructor
+
+Enables instantiation using whatever values you want. While this
+is useful in some very specific cases, this is almost certainly not
+what you are looking for as setting these values manually may
+result in observability metrics which do not uniquely identify a
+charm in order to provide accurate usage reporting, alerting,
+horizontal scaling, or other use cases.
+
+```python
+topology = JujuTopology(
+ model="some-juju-model",
+ model_uuid="00000000-0000-0000-0000-000000000001",
+ application="fancy-juju-application",
+ unit="fancy-juju-application/0",
+ charm_name="fancy-juju-application-k8s",
+)
+```
+
+"""
+from collections import OrderedDict
+from typing import Dict, List, Optional
+from uuid import UUID
+
+# The unique Charmhub library identifier, never change it
+LIBID = "bced1658f20f49d28b88f61f83c2d232"
+
+LIBAPI = 0
+LIBPATCH = 6
+
+
+class InvalidUUIDError(Exception):
+ """Invalid UUID was provided."""
+
+ def __init__(self, uuid: str):
+ self.message = "'{}' is not a valid UUID.".format(uuid)
+ super().__init__(self.message)
+
+
+class JujuTopology:
+ """JujuTopology is used for storing, generating and formatting juju topology information.
+
+ DEPRECATED: This class is deprecated. Use `pip install cosl` and
+ `from cosl.juju_topology import JujuTopology` instead.
+ """
+
+ def __init__(
+ self,
+ model: str,
+ model_uuid: str,
+ application: str,
+ unit: Optional[str] = None,
+ charm_name: Optional[str] = None,
+ ):
+ """Build a JujuTopology object.
+
+ A `JujuTopology` object is used for storing and transforming
+ Juju topology information. This information is used to
+ annotate Prometheus scrape jobs and alert rules. Such
+ annotation when applied to scrape jobs helps in identifying
+ the source of the scrapped metrics. On the other hand when
+ applied to alert rules topology information ensures that
+ evaluation of alert expressions is restricted to the source
+ (charm) from which the alert rules were obtained.
+
+ Args:
+ model: a string name of the Juju model
+ model_uuid: a globally unique string identifier for the Juju model
+ application: an application name as a string
+ unit: a unit name as a string
+ charm_name: name of charm as a string
+ """
+ if not self.is_valid_uuid(model_uuid):
+ raise InvalidUUIDError(model_uuid)
+
+ self._model = model
+ self._model_uuid = model_uuid
+ self._application = application
+ self._charm_name = charm_name
+ self._unit = unit
+
+ def is_valid_uuid(self, uuid):
+ """Validate the supplied UUID against the Juju Model UUID pattern.
+
+ Args:
+ uuid: string that needs to be checked if it is valid v4 UUID.
+
+ Returns:
+ True if parameter is a valid v4 UUID, False otherwise.
+ """
+ try:
+ return str(UUID(uuid, version=4)) == uuid
+ except (ValueError, TypeError):
+ return False
+
+ @classmethod
+ def from_charm(cls, charm):
+ """Creates a JujuTopology instance by using the model data available on a charm object.
+
+ Args:
+ charm: a `CharmBase` object for which the `JujuTopology` will be constructed
+ Returns:
+ a `JujuTopology` object.
+ """
+ return cls(
+ model=charm.model.name,
+ model_uuid=charm.model.uuid,
+ application=charm.model.app.name,
+ unit=charm.model.unit.name,
+ charm_name=charm.meta.name,
+ )
+
+ @classmethod
+ def from_dict(cls, data: dict):
+ """Factory method for creating `JujuTopology` children from a dictionary.
+
+ Args:
+ data: a dictionary with five keys providing topology information. The keys are
+ - "model"
+ - "model_uuid"
+ - "application"
+ - "unit"
+ - "charm_name"
+ `unit` and `charm_name` may be empty, but will result in more limited
+ labels. However, this allows us to support charms without workloads.
+
+ Returns:
+ a `JujuTopology` object.
+ """
+ return cls(
+ model=data["model"],
+ model_uuid=data["model_uuid"],
+ application=data["application"],
+ unit=data.get("unit", ""),
+ charm_name=data.get("charm_name", ""),
+ )
+
+ def as_dict(
+ self,
+ *,
+ remapped_keys: Optional[Dict[str, str]] = None,
+ excluded_keys: Optional[List[str]] = None,
+ ) -> OrderedDict:
+ """Format the topology information into an ordered dict.
+
+ Keeping the dictionary ordered is important to be able to
+ compare dicts without having to resort to deep comparisons.
+
+ Args:
+ remapped_keys: A dictionary mapping old key names to new key names,
+ which will be substituted when invoked.
+ excluded_keys: A list of key names to exclude from the returned dict.
+ uuid_length: The length to crop the UUID to.
+ """
+ ret = OrderedDict(
+ [
+ ("model", self.model),
+ ("model_uuid", self.model_uuid),
+ ("application", self.application),
+ ("unit", self.unit),
+ ("charm_name", self.charm_name),
+ ]
+ )
+ if excluded_keys:
+ ret = OrderedDict({k: v for k, v in ret.items() if k not in excluded_keys})
+
+ if remapped_keys:
+ ret = OrderedDict(
+ (remapped_keys.get(k), v) if remapped_keys.get(k) else (k, v) for k, v in ret.items() # type: ignore
+ )
+
+ return ret
+
+ @property
+ def identifier(self) -> str:
+ """Format the topology information into a terse string.
+
+ This crops the model UUID, making it unsuitable for comparisons against
+ anything but other identifiers. Mainly to be used as a display name or file
+ name where long strings might become an issue.
+
+ >>> JujuTopology( \
+ model = "a-model", \
+ model_uuid = "00000000-0000-4000-8000-000000000000", \
+ application = "some-app", \
+ unit = "some-app/1" \
+ ).identifier
+ 'a-model_00000000_some-app'
+ """
+ parts = self.as_dict(
+ excluded_keys=["unit", "charm_name"],
+ )
+
+ parts["model_uuid"] = self.model_uuid_short
+ values = parts.values()
+
+ return "_".join([str(val) for val in values]).replace("/", "_")
+
+ @property
+ def label_matcher_dict(self) -> Dict[str, str]:
+ """Format the topology information into a dict with keys having 'juju_' as prefix.
+
+ Relabelled topology never includes the unit as it would then only match
+ the leader unit (ie. the unit that produced the dict).
+ """
+ items = self.as_dict(
+ remapped_keys={"charm_name": "charm"},
+ excluded_keys=["unit"],
+ ).items()
+
+ return {"juju_{}".format(key): value for key, value in items if value}
+
+ @property
+ def label_matchers(self) -> str:
+ """Format the topology information into a promql/logql label matcher string.
+
+ Topology label matchers should never include the unit as it
+ would then only match the leader unit (ie. the unit that
+ produced the matchers).
+ """
+ items = self.label_matcher_dict.items()
+ return ", ".join(['{}="{}"'.format(key, value) for key, value in items if value])
+
+ @property
+ def model(self) -> str:
+ """Getter for the juju model value."""
+ return self._model
+
+ @property
+ def model_uuid(self) -> str:
+ """Getter for the juju model uuid value."""
+ return self._model_uuid
+
+ @property
+ def model_uuid_short(self) -> str:
+ """Getter for the juju model value, truncated to the first eight letters."""
+ return self._model_uuid[:8]
+
+ @property
+ def application(self) -> str:
+ """Getter for the juju application value."""
+ return self._application
+
+ @property
+ def charm_name(self) -> Optional[str]:
+ """Getter for the juju charm name value."""
+ return self._charm_name
+
+ @property
+ def unit(self) -> Optional[str]:
+ """Getter for the juju unit value."""
+ return self._unit
projects / osm / devops.git / blobdiff