Grafana Agent

By Canonical Observability

Architecture:

Channel	Revision	Published	Runs on
latest/stable	68	12 Mar 2024	Ubuntu 22.04
latest/candidate	95	10 Apr 2024	Ubuntu 20.04
latest/beta	95	10 Apr 2024	Ubuntu 20.04
latest/edge	136	Yesterday	Ubuntu 22.04

Learn to deploy on juju >

Platform:

22.04

charms.grafana_agent.v0.cos_agent

Docstrings Source code
- Fetch library
  
  charmcraft fetch-lib charms.grafana_agent.v0.cos_agent
  Download cos_agent.py
- 08 Mar 2024
- Library version 0.8

Overview.

This library can be used to manage the cos_agent relation interface:

COSAgentProvider: Use in machine charms that need to have a workload's metrics or logs scraped, or forward rule files or dashboards to Prometheus, Loki or Grafana through the Grafana Agent machine charm.
COSAgentConsumer: Used in the Grafana Agent machine charm to manage the requirer side of the cos_agent interface.

COSAgentProvider Library Usage

Grafana Agent machine Charmed Operator interacts with its clients using the cos_agent library. Charms seeking to send telemetry, must do so using the COSAgentProvider object from this charm library.

Using the COSAgentProvider object only requires instantiating it, typically in the __init__ method of your charm (the one which sends telemetry).

The constructor of COSAgentProvider has only one required and nine optional parameters:

    def __init__(
        self,
        charm: CharmType,
        relation_name: str = DEFAULT_RELATION_NAME,
        metrics_endpoints: Optional[List[_MetricsEndpointDict]] = None,
        metrics_rules_dir: str = "./src/prometheus_alert_rules",
        logs_rules_dir: str = "./src/loki_alert_rules",
        recurse_rules_dirs: bool = False,
        log_slots: Optional[List[str]] = None,
        dashboard_dirs: Optional[List[str]] = None,
        refresh_events: Optional[List] = None,
        scrape_configs: Optional[Union[List[Dict], Callable]] = None,
    ):

Parameters

charm: The instance of the charm that instantiates COSAgentProvider, typically self.
relation_name: If your charmed operator uses a relation name other than cos-agent to use the cos_agent interface, this is where you have to specify that.
metrics_endpoints: In this parameter you can specify the metrics endpoints that Grafana Agent machine Charmed Operator will scrape. The configs of this list will be merged with the configs from scrape_configs.
metrics_rules_dir: The directory in which the Charmed Operator stores its metrics alert rules files.
logs_rules_dir: The directory in which the Charmed Operator stores its logs alert rules files.
recurse_rules_dirs: This parameters set whether Grafana Agent machine Charmed Operator has to search alert rules files recursively in the previous two directories or not.
log_slots: Snap slots to connect to for scraping logs in the form ["snap-name:slot", ...].
dashboard_dirs: List of directories where the dashboards are stored in the Charmed Operator.
refresh_events: List of events on which to refresh relation data.
scrape_configs: List of standard scrape_configs dicts or a callable that returns the list in case the configs need to be generated dynamically. The contents of this list will be merged with the configs from metrics_endpoints.

Example 1 - Minimal instrumentation:

In order to use this object the following should be in the charm.py file.

from charms.grafana_agent.v0.cos_agent import COSAgentProvider
...
class TelemetryProviderCharm(CharmBase):
    def __init__(self, *args):
        ...
        self._grafana_agent = COSAgentProvider(self)

Example 2 - Full instrumentation:

In order to use this object the following should be in the charm.py file.

from charms.grafana_agent.v0.cos_agent import COSAgentProvider
...
class TelemetryProviderCharm(CharmBase):
    def __init__(self, *args):
        ...
        self._grafana_agent = COSAgentProvider(
            self,
            relation_name="custom-cos-agent",
            metrics_endpoints=[
                # specify "path" and "port" to scrape from localhost
                {"path": "/metrics", "port": 9000},
                {"path": "/metrics", "port": 9001},
                {"path": "/metrics", "port": 9002},
            ],
            metrics_rules_dir="./src/alert_rules/prometheus",
            logs_rules_dir="./src/alert_rules/loki",
            recursive_rules_dir=True,
            log_slots=["my-app:slot"],
            dashboard_dirs=["./src/dashboards_1", "./src/dashboards_2"],
            refresh_events=["update-status", "upgrade-charm"],
            scrape_configs=[
                {
                    "job_name": "custom_job",
                    "metrics_path": "/metrics",
                    "authorization": {"credentials": "bearer-token"},
                    "static_configs": [
                        {
                            "targets": ["localhost:9003"]},
                            "labels": {"key": "value"},
                        },
                    ],
                },
            ]
        )

Example 3 - Dynamic scrape configs generation:

Pass a function to the scrape_configs to decouple the generation of the configs from the instantiation of the COSAgentProvider object.

from charms.grafana_agent.v0.cos_agent import COSAgentProvider
...

class TelemetryProviderCharm(CharmBase):
    def generate_scrape_configs(self):
        return [
            {
                "job_name": "custom",
                "metrics_path": "/metrics",
                "static_configs": [{"targets": ["localhost:9000"]}],
            },
        ]

    def __init__(self, *args):
        ...
        self._grafana_agent = COSAgentProvider(
            self,
            scrape_configs=self.generate_scrape_configs,
        )

COSAgentConsumer Library Usage

This object may be used by any Charmed Operator which gathers telemetry data by implementing the consumer side of the cos_agent interface. For instance Grafana Agent machine Charmed Operator.

For this purpose the charm needs to instantiate the COSAgentConsumer object with one mandatory and two optional arguments.

Parameters

charm: A reference to the parent (Grafana Agent machine) charm.
relation_name: The name of the relation that the charm uses to interact with its clients that provides telemetry data using the COSAgentProvider object.

If provided, this relation name must match a provided relation in metadata.yaml with the cos_agent interface. The default value of this argument is "cos-agent".
refresh_events: List of events on which to refresh relation data.

Example 1 - Minimal instrumentation:

In order to use this object the following should be in the charm.py file.

from charms.grafana_agent.v0.cos_agent import COSAgentConsumer
...
class GrafanaAgentMachineCharm(GrafanaAgentCharm)
    def __init__(self, *args):
        ...
        self._cos = COSAgentRequirer(self)

Example 2 - Full instrumentation:

In order to use this object the following should be in the charm.py file.

from charms.grafana_agent.v0.cos_agent import COSAgentConsumer
...
class GrafanaAgentMachineCharm(GrafanaAgentCharm)
    def __init__(self, *args):
        ...
        self._cos = COSAgentRequirer(
            self,
            relation_name="cos-agent-consumer",
            refresh_events=["update-status", "upgrade-charm"],
        )

Index

class CosAgentProviderUnitData
class CosAgentPeersUnitData
- def app_name( self)
class COSAgentProvider
- def __init__( self, charm, relation_name, metrics_endpoints, metrics_rules_dir, logs_rules_dir, recurse_rules_dirs, log_slots, dashboard_dirs, refresh_events)
class COSAgentDataChanged
class COSAgentValidationError
- def __init__( self, handle, message)
- def snapshot( self)
- def restore( self, snapshot)
class COSAgentRequirerEvents
class COSAgentRequirer
- def __init__( self, charm)
- def peer_relation( self)
- def trigger_refresh( self, _)
- def metrics_alerts( self)
- def metrics_jobs( self)
- def snap_log_endpoints( self)
- def logs_alerts( self)
- def dashboards( self)

Description

Unit databag model for cos-agent relation. None

Description

Unit databag model for peers cos-agent machine charm peer relation. None

Methods

CosAgentPeersUnitData. app_name( self )

Parse out the app name from the unit name.

Description

TODO: Switch to using model_post_init when pydantic v2 is released? https://github.com/pydantic/pydantic/issues/1729#issuecomment-1300576214

Description

Integration endpoint wrapper for the provider side of the cos_agent interface. None

Methods

COSAgentProvider. __init__( self , charm: CharmType , relation_name: str , metrics_endpoints , metrics_rules_dir: str , logs_rules_dir: str , recurse_rules_dirs: bool , log_slots , dashboard_dirs , refresh_events )

Create a COSAgentProvider instance.

Arguments

charm

The CharmBase instance that is instantiating this object.

relation_name

The name of the relation to communicate over.

metrics_endpoints

List of endpoints in the form [{"path": path, "port": port}, ...]. This argument is a simplified form of the scrape_configs. The contents of this list will be merged with the contents of scrape_configs.

metrics_rules_dir

Directory where the metrics rules are stored.

logs_rules_dir

Directory where the logs rules are stored.

recurse_rules_dirs

Whether to recurse into rule paths.

log_slots

Snap slots to connect to for scraping logs in the form ["snap-name:slot", ...].

dashboard_dirs

Directory where the dashboards are stored.

refresh_events

List of events on which to refresh relation data.

scrape_configs

List of standard scrape_configs dicts or a callable that returns the list in case the configs need to be generated dynamically. The contents of this list will be merged with the contents of metrics_endpoints.

Description

Event emitted by COSAgentRequirer when relation data changes. None

Description

Event emitted by COSAgentRequirer when there is an error in the relation data. None

Methods

COSAgentValidationError. __init__( self , handle , message: str )

COSAgentValidationError. snapshot( self )

Description

Save COSAgentValidationError source information. None

COSAgentValidationError. restore( self , snapshot )

Description

Restore COSAgentValidationError source information. None

Description

COSAgentRequirer events. None

Description

Integration endpoint wrapper for the Requirer side of the cos_agent interface. None

Methods

COSAgentRequirer. __init__( self , charm: CharmType )

Create a COSAgentRequirer instance.

Arguments

charm

The CharmBase instance that is instantiating this object.

relation_name

The name of the relation to communicate over.

peer_relation_name

The name of the peer relation to communicate over.

refresh_events

List of events on which to refresh relation data.

COSAgentRequirer. peer_relation( self )

Helper function for obtaining the peer relation object.

Description

Returns: peer relation object (NOTE: would return None if called too early, e.g. during install).

COSAgentRequirer. trigger_refresh( self , _ )

Description

Trigger a refresh of relation data. None

COSAgentRequirer. metrics_alerts( self )

Description

Fetch metrics alerts. None

COSAgentRequirer. metrics_jobs( self )

Description

Parse the relation data contents and extract the metrics jobs. None

COSAgentRequirer. snap_log_endpoints( self )

Description

Fetch logging endpoints exposed by related snaps. None

COSAgentRequirer. logs_alerts( self )

Description

Fetch log alerts. None

COSAgentRequirer. dashboards( self )

Fetch dashboards as encoded content.

Description

Dashboards are assumed not to vary across units of the same primary.

Grafana Agent

charms.grafana_agent.v0.cos_agent

Overview.

COSAgentProvider Library Usage

Parameters

Example 1 - Minimal instrumentation:

Example 2 - Full instrumentation:

Example 3 - Dynamic scrape configs generation:

COSAgentConsumer Library Usage

Parameters

Example 1 - Minimal instrumentation:

Example 2 - Full instrumentation:

class CosAgentProviderUnitData

class CosAgentPeersUnitData

class COSAgentProvider

class COSAgentDataChanged

class COSAgentValidationError

class COSAgentRequirerEvents

class COSAgentRequirer