Grafana Agent

  • By Canonical Observability
Channel Revision Published Runs on
latest/stable 165 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/stable 166 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/stable 167 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/stable 164 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 216 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 218 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 219 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 217 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/beta 223 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/beta 226 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/beta 224 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/beta 225 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/edge 226 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/edge 225 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/edge 224 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/edge 223 28 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
juju deploy grafana-agent
Show information

Platform:

Ubuntu
22.04 20.04

charms.grafana_agent.v0.cos_agent

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"],
        )

class CosAgentProviderUnitData

Description

Unit databag model for cos-agent relation. None

class CosAgentPeersUnitData

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

class COSAgentProvider

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.

class COSAgentDataChanged

Description

Event emitted by COSAgentRequirer when relation data changes. None

class COSAgentValidationError

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

class COSAgentRequirerEvents

Description

COSAgentRequirer events. None

class COSAgentRequirer

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.