Observability Libs
- Jon Seager
Channel | Revision | Published | Runs on |
---|---|---|---|
latest/edge | 50 | 11 Oct 2024 |
juju deploy observability-libs --channel edge
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.observability_libs.v0.juju_topology
-
- Last updated 01 Mar 2023
- Revision Library version 0.6
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 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.
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.
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.
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",
)
Index
class InvalidUUIDError
Description
Invalid UUID was provided. None
Methods
InvalidUUIDError. __init__( self , uuid: str )
class JujuTopology
JujuTopology is used for storing, generating and formatting juju topology information.
Description
DEPRECATED: This class is deprecated. Use pip install cosl
and
from cosl.juju_topology import JujuTopology
instead.
Methods
JujuTopology. __init__( self , model: str , model_uuid: str , application: str , unit , charm_name )
Build a JujuTopology object.
Arguments
a string name of the Juju model
a globally unique string identifier for the Juju model
an application name as a string
a unit name as a string
name of charm as a string
Description
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.
JujuTopology. is_valid_uuid( self , uuid )
Validate the supplied UUID against the Juju Model UUID pattern.
Arguments
string that needs to be checked if it is valid v4 UUID.
Returns
True if parameter is a valid v4 UUID, False otherwise.
JujuTopology. from_charm( cls , charm )
Creates a JujuTopology instance by using the model data available on a charm object.
Arguments
a CharmBase
object for which the JujuTopology
will be constructed
Returns
a JujuTopology
object.
JujuTopology. from_dict( cls , data: dict )
Factory method for creating JujuTopology
children from a dictionary.
Arguments
a dictionary with five keys providing topology information. The keys are
- "model"
- "model_uuid"
- "application"
- "unit"
- "charm_name"
unit
andcharm_name
may be empty, but will result in more limited labels. However, this allows us to support charms without workloads.
Returns
a JujuTopology
object.
JujuTopology. as_dict( self )
Format the topology information into an ordered dict.
Arguments
A dictionary mapping old key names to new key names, which will be substituted when invoked.
A list of key names to exclude from the returned dict.
The length to crop the UUID to.
Description
Keeping the dictionary ordered is important to be able to compare dicts without having to resort to deep comparisons.
JujuTopology. identifier( self )
Format the topology information into a terse string.
Description
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'
JujuTopology. label_matcher_dict( self )
Format the topology information into a dict with keys having 'juju_' as prefix.
Description
Relabelled topology never includes the unit as it would then only match the leader unit (ie. the unit that produced the dict).
JujuTopology. label_matchers( self )
Format the topology information into a promql/logql label matcher string.
Description
Topology label matchers should never include the unit as it would then only match the leader unit (ie. the unit that produced the matchers).
JujuTopology. model( self )
Description
Getter for the juju model value. None
JujuTopology. model_uuid( self )
Description
Getter for the juju model uuid value. None
JujuTopology. model_uuid_short( self )
Description
Getter for the juju model value, truncated to the first eight letters. None
JujuTopology. application( self )
Description
Getter for the juju application value. None
JujuTopology. charm_name( self )
Description
Getter for the juju charm name value. None
JujuTopology. unit( self )
Description
Getter for the juju unit value. None