Grafana
- By Jose C. Massón
Channel | Version | Revision | Published | Runs on |
---|---|---|---|---|
latest/stable | 64 | 64 | 31 Jan 2023 | |
latest/candidate | 64 | 64 | 31 Jan 2023 | |
latest/beta | 64 | 64 | 31 Jan 2023 | |
latest/edge | 67 | 67 | 02 Feb 2023 | |
1.0/stable | 64 | 64 | 31 Jan 2023 | |
1.0/candidate | 64 | 64 | 31 Jan 2023 | |
1.0/beta | 64 | 64 | 31 Jan 2023 | |
1.0/edge | 64 | 64 | 31 Jan 2023 |
juju deploy grafana-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.grafana_k8s.v0.grafana_source
-
- Last updated 23 Jan 2023
- Revision Library version 0
Overview.
This document explains how to integrate with the Grafana charm
for the purpose of providing a datasource which can be used by
Grafana dashboards. It also explains the structure of the data
expected by the grafana-source
interface, and may provide a
mechanism or reference point for providing a compatible interface
or library by providing a definitive reference guide to the
structure of relation data which is shared between the Grafana
charm and any charm providing datasource information.
Provider Library Usage
The Grafana charm interacts with its datasources using its charm
library. The goal of this library is to be as simple to use as
possible, and instantiation of the class with or without changing
the default arguments provides a complete use case. For the simplest
use case of a Prometheus (or Prometheus-compatible) datasource
provider in a charm which provides: grafana-source
, creation of a
GrafanaSourceProvider
object with the default arguments is sufficient.
The default arguments are:
`charm`: `self` from the charm instantiating this library
`source_type`: None
`source_port`: None
`source_url`: None
`relation_name`: grafana-source
`refresh_event`: A `PebbleReady` event from `charm`, used to refresh
the IP address sent to Grafana on a charm lifecycle event or
pod restart
The value of source_url
should be a fully-resolvable URL for a valid Grafana
source, e.g., http://example.com/api
or similar.
If your configuration requires any changes from these defaults, they may be set from the class constructor. It may be instantiated as follows:
from charms.grafana_k8s.v0.grafana_source import GrafanaSourceProvider
class FooCharm:
def __init__(self, *args):
super().__init__(*args, **kwargs)
...
self.grafana_source_provider = GrafanaSourceProvider(
self, source_type="prometheus", source_port="9090"
)
...
The first argument (self
) should be a reference to the parent (datasource)
charm, as this charm's model will be used for relation data, IP addresses,
and lifecycle events.
An instantiated GrafanaSourceProvider
will ensure that each unit of its
parent charm is added as a datasource in the Grafana configuration once a
relation is established, using the Grafana datasource provisioning
specification via YAML files.
This information is added to the relation data for the charms as serialized JSON from a dict, with a structure of:
{
"application": {
"model": charm.model.name, # from `charm` in the constructor
"model_uuid": charm.model.uuid,
"application": charm.model.app.name,
"type": source_type,
},
"unit/0": {
"uri": {ip_address}:{port}{path} # `ip_address` is derived at runtime, `port` from the constructor,
# and `path` from the constructor, if specified
},
This is ingested by :class:GrafanaSourceConsumer
, and is sufficient for configuration.
Consumer Library Usage
The GrafanaSourceConsumer
object may be used by Grafana
charms to manage relations with available datasources. For this
purpose, a charm consuming Grafana datasource information should do
the following things:
- Instantiate the
GrafanaSourceConsumer
object by providing it a
reference to the parent (Grafana) charm and, optionally, the name of
the relation that the Grafana charm uses to interact with datasources.
This relation must confirm to the grafana-source
interface.
For example a Grafana charm may instantiate the
GrafanaSourceConsumer
in its constructor as follows
from charms.grafana_k8s.v0.grafana_source import GrafanaSourceConsumer
def __init__(self, *args):
super().__init__(*args)
...
self.grafana_source_consumer = GrafanaSourceConsumer(self)
...
- A Grafana charm also needs to listen to the
GrafanaSourceEvents
events emitted by the GrafanaSourceConsumer
by adding itself as an observer for these events:
self.framework.observe(
self.grafana_source_consumer.on.sources_changed,
self._on_sources_changed,
)
self.framework.observe(
self.grafana_source_consumer.on.sources_to_delete_changed,
self._on_sources_to_delete_change,
)
The reason for two separate events is that Grafana keeps track of removed datasources in its datasource provisioning.
If your charm is merely implementing a grafana-source
-compatible API,
and is does not follow exactly the same semantics as Grafana, observing these
events may not be needed.
Index
def _type_convert_stored(obj)
Description
Convert Stored* to their appropriate types, recursively. None
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 )
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 SourceFieldsMissingError
Description
An exception to indicate there a missing fields from a Grafana datsource definition. None
class GrafanaSourcesChanged
Description
Event emitted when Grafana sources change. None
Methods
GrafanaSourcesChanged. __init__( self , handle , data )
GrafanaSourcesChanged. snapshot( self )
Description
GrafanaSourcesChanged. restore( self , snapshot )
Description
class GrafanaSourceEvents
Description
Events raised by :class:`GrafanaSourceEvents. None
class GrafanaSourceProvider
Description
A provider object for Grafana datasources. None
Methods
GrafanaSourceProvider. __init__( self , charm: CharmBase , source_type: str , source_port , source_url , refresh_event , relation_name: str , extra_fields )
Construct a Grafana charm client.
Arguments
Description
GrafanaSourceProvider. update_source( self , source_url )
Description
GrafanaSourceProvider. _set_sources_from_event( self , event: RelationJoinedEvent )
Description
GrafanaSourceProvider. _set_sources( self , rel: Relation )
Description
GrafanaSourceProvider. _scrape_data( self )
Generate source metadata.
Returns
GrafanaSourceProvider. _set_unit_details( self , _ )
Set unit host details.
Description
class GrafanaSourceConsumer
Description
A consumer object for working with Grafana datasources. None
Methods
GrafanaSourceConsumer. __init__( self , charm: CharmBase , relation_name: str )
A Grafana based Monitoring service consumer, i.e., the charm that uses a datasource.
Arguments
GrafanaSourceConsumer. _on_grafana_source_relation_changed( self , event )
Handle relation changes in related providers.
Description
GrafanaSourceConsumer. _on_grafana_peer_changed( self , _: RelationChangedEvent )
Description
GrafanaSourceConsumer. _get_source_config( self , rel: Relation )
Description
GrafanaSourceConsumer. _relation_hosts( self , rel: Relation )
Fetch host names and address of all provider units for a single relation.
Arguments
Returns
GrafanaSourceConsumer. _on_grafana_source_relation_departed( self , event: RelationDepartedEvent )
Update job config when providers depart.
Description
GrafanaSourceConsumer. _remove_source_from_datastore( self , event: RelationDepartedEvent )
Remove the grafana-source from the datastore.
Description
GrafanaSourceConsumer. _remove_source( self , source_name: str )
Description
GrafanaSourceConsumer. upgrade_keys( self )
Description
GrafanaSourceConsumer. update_sources( self , relation )
Re-establish sources on one or more relations.
Arguments
Description
GrafanaSourceConsumer. sources( self )
Description
GrafanaSourceConsumer. sources_to_delete( self )
Description
GrafanaSourceConsumer. _set_default_data( self )
Description
GrafanaSourceConsumer. set_peer_data( self , key: str , data: Any )
Description
GrafanaSourceConsumer. get_peer_data( self , key: str )
Description