Grafana Agent
- By Canonical Observability
Channel | Revision | Published | Runs on |
---|---|---|---|
latest/stable | 216 | 01 Aug 2024 | |
latest/stable | 217 | 01 Aug 2024 | |
latest/stable | 219 | 01 Aug 2024 | |
latest/stable | 218 | 01 Aug 2024 | |
latest/candidate | 260 | 07 Oct 2024 | |
latest/candidate | 224 | 01 Aug 2024 | |
latest/candidate | 226 | 01 Aug 2024 | |
latest/candidate | 225 | 01 Aug 2024 | |
latest/candidate | 223 | 01 Aug 2024 | |
latest/beta | 223 | 28 Jun 2024 | |
latest/beta | 226 | 28 Jun 2024 | |
latest/beta | 224 | 28 Jun 2024 | |
latest/beta | 225 | 28 Jun 2024 | |
latest/edge | 289 | 07 Oct 2024 | |
latest/edge | 288 | 07 Oct 2024 | |
latest/edge | 287 | 07 Oct 2024 | |
latest/edge | 286 | 07 Oct 2024 | |
latest/edge | 285 | 07 Oct 2024 |
juju deploy grafana-agent
Deploy universal operators easily with Juju, the Universal Operator Lifecycle Manager.
Platform:
charms.grafana_agent.v0.cos_agent
-
- Last updated 22 Aug 2024
- Revision Library version 0.11
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 thecos_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 instantiatesCOSAgentProvider
, typicallyself
.relation_name
: If your charmed operator uses a relation name other thancos-agent
to use thecos_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 fromscrape_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 frommetrics_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 theCOSAgentProvider
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
The CharmBase
instance that is instantiating this object.
The name of the relation to communicate over.
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
.
Directory where the metrics rules are stored.
Directory where the logs rules are stored.
Whether to recurse into rule paths.
Snap slots to connect to for scraping logs in the form ["snap-name:slot", ...].
Directory where the dashboards are stored.
List of events on which to refresh relation data.
List of protocols that the charm will be using for sending traces.
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
The CharmBase
instance that is instantiating this object.
The name of the relation to communicate over.
The name of the peer relation to communicate over.
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