Grafana Agent

  • Canonical Observability
Channel Revision Published Runs on
latest/stable 216 01 Aug 2024
Ubuntu 22.04 Ubuntu 20.04
latest/stable 217 01 Aug 2024
Ubuntu 22.04 Ubuntu 20.04
latest/stable 219 01 Aug 2024
Ubuntu 22.04 Ubuntu 20.04
latest/stable 218 01 Aug 2024
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 260 07 Oct 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/candidate 224 01 Aug 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/candidate 226 01 Aug 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/candidate 225 01 Aug 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/candidate 223 01 Aug 2024
Ubuntu 24.04 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 327 Yesterday
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/edge 326 Yesterday
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/edge 325 Yesterday
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/edge 324 Yesterday
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
latest/edge 319 20 Nov 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04
juju deploy grafana-agent
Show information

Learn to deploy on juju >

Platform:

Ubuntu
24.04 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 ten 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,
        tracing_protocols: Optional[List[str]] = 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.

  • tracing_protocols: List of requested tracing protocols that the charm requires to send traces.

  • 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"],
            tracing_protocols=["otlp_http", "otlp_grpc"],
            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 TransportProtocolType

Description

Receiver Type. None

class TracingError

Description

Base class for custom errors raised by tracing. None

class NotReadyError

Description

Raised by the provider wrapper if a requirer hasn't published the required data (yet). None

class ProtocolNotRequestedError

Description

Raised if the user attempts to obtain an endpoint for a protocol it did not request. None

class DataValidationError

Description

Raised when data validation fails on IPU relation data. None

class AmbiguousRelationUsageError

Description

Raised when one wrongly assumes that there can only be one relation on an endpoint. None

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 Receiver

Description

Specification of an active receiver. None

class CosAgentRequirerUnitData

Description

Application databag model for the COS-agent requirer. None

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 , tracing_protocols )

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.

tracing_protocols

List of protocols that the charm will be using for sending traces.

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.

COSAgentProvider. relations( self )

Description

The tracing relations associated with this endpoint. None

COSAgentProvider. is_ready( self , relation )

Description

Is this endpoint ready? None

COSAgentProvider. get_all_endpoints( self , relation )

Description

Unmarshalled relation data. None

COSAgentProvider. get_tracing_endpoint( self , protocol: ReceiverProtocol , relation )

Description

Receiver endpoint for the given protocol. None

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. update_tracing_receivers( self )

Description

Updates the list of exposed tracing receivers in all relations. None

COSAgentRequirer. trigger_refresh( self , _ )

Description

Trigger a refresh of relation data. None

COSAgentRequirer. requested_tracing_protocols( self )

Description

All receiver protocols that have been requested by our related apps. 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. snap_log_endpoints_with_topology( self )

Description

Fetch logging endpoints and charm topology for each related snap. 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.

def charm_tracing_config(
    endpoint_requirer: COSAgentProvider,
    cert_path
)

Utility function to determine the charm_tracing config you will likely want.

Description

If no endpoint is provided: disable charm tracing. If https endpoint is provided but cert_path is not found on disk: disable charm tracing. If https endpoint is provided and cert_path is None: ERROR Else: proceed with charm tracing (with or without tls, as appropriate)

Usage: If you are using charm_tracing >= v1.9:

from lib.charms.tempo_k8s.v1.charm_tracing import trace_charm from lib.charms.tempo_k8s.v0.cos_agent import charm_tracing_config @trace_charm(tracing_endpoint="my_endpoint", cert_path="cert_path") class MyCharm(...): _cert_path = "/path/to/cert/on/charm/container.crt" def init(self, ...): self.cos_agent = COSAgentProvider(...) self.my_endpoint, self.cert_path = charm_tracing_config( ... self.cos_agent, self._cert_path)

If you are using charm_tracing < v1.9:

from lib.charms.tempo_k8s.v1.charm_tracing import trace_charm from lib.charms.tempo_k8s.v2.tracing import charm_tracing_config @trace_charm(tracing_endpoint="my_endpoint", cert_path="cert_path") class MyCharm(...): _cert_path = "/path/to/cert/on/charm/container.crt" def init(self, ...): self.cos_agent = COSAgentProvider(...) self.my_endpoint, self.cert_path = charm_tracing_config( ... self.cos_agent, self._cert_path) @property def my_endpoint(self): return self._my_endpoint @property def cert_path(self): return self._cert_path