---
title: Charmhub | cos_agent interface
description: Interfaces describe the relation between two charms. This interface shows
  opinionated, standardized interface specifications for charm relations.
url: https://charmhub.io/integrations/cos_agent
---

# cos\_agent

## Usage

The `cos_agent` interface is meant to exchange information on several observability-related data streams at once. This is a `SUBORDINATE`, ergo MACHINE-charm-specific relation interface.

## Direction

```
flowchart TD
    Provider["Provider (e.g. kafka)"] -- "relation_name
    metrics_endpoints
    metrics_rules_dir
    logs_rules_dir
    recursive_rules_dir
    log_slots
    dashboard_dirs
    refresh_events" --> Requirer
    Requirer["Requirer (e.g. grafana-agent)"] -- refresh_events --> Provider
```

As all Juju relations, the `cos_agent` interface consists of a provider and a requirer. In this case the `Provider` side of the relationship may provide telemetry settings, if not, the required side will use default values.

## Behavior

### Provider

* Is expected to be able to provide metrics endpoints to be scraped.
* Is expected to be able to provide a directory containing Prometheus style metrics rules files.
* Is expected to be able to provide a directory containing Loki style rules files.
* Is expected to be able to inform if metrics and logs rules directories should be scanned recursively.
* Is expected to be able to provide snap slots to connect to for scraping logs.
* Is expected to be able to provide a list of directories containing Grafana dashboard files.
* Is expected to be able to provide a list of events on which to refresh relation data.

## Relation Data

[[Pydantic Schema]](https://github.com/canonical/charmlibs/blob/main/interfaces/cos_agent/interface/vv0/schema.py)

### Provider

#### Unit data

* Exposes mtrics\_alert\_rules, log\_alert\_rules, and log\_slots

#### Example

```
{
  "config": {
    "metrics_alert_rules": {
      "groups": [
        {
          "name": "test_58b48ff0_zookeeper_cos_23790144_zinc",
          "rules": [
            {
              "alert": "ZincTargetMissing",
              "annotations": {
                "description": "A Prometheus target has disappeared. An exporter might be crashed.\n  VALUE = {{ $value }}\n  LABELS = {{ $labels }}",
                "summary": "Prometheus target missing (instance {{ $labels.instance}})"
              },
              "expr": "up{juju_application=\"zinc2\"} == 0",
              "for": "0m",
              "labels": {
                "app_group": "cloud",
                "juju_application": "zookeeper",
                "juju_charm": "zookeeper",
                "juju_model": "test",
                "juju_model_uuid": "58b48ff0-608b-435f-83b9-ea643e0b98db",
                "severity": "critical"
              }
            }
          ]
        }
      ]
    },
    "log_alert_rules": {},
    /* Dashboards list with base64 encoded, lzma-compressed, json-dumped dashboard data */
    "dashboards": [
      "/Td6WFoAAATm1rRGAgAhARYAAAB0L+Wj6hvVPXVdA…",
      "/Td6WFoAAATm1rRGAgAhARYAAAB0L+Wj6hvVPXVdB…"
    ],
    "log_slots": [
      "charmed-zookeeper:logs"
    ],
    "metrics_scrape_jobs": [{"job_name": "kafka_0", "path": "/metrics", "port": 9101}],
  }
}
```

## Charms implementing this interface

### Providers

* [zookeeper](https://charmhub.io/zookeeper)
* [kafka](https://charmhub.io/kafka)

### Requirers

* [grafana-agent](https://charmhub.io/grafana-agent)

## Other charms using this interface

### Providers

* [kafka](https://charmhub.io/kafka)
* [mongodb](https://charmhub.io/mongodb)
* [mysql](https://charmhub.io/mysql)
* [postgresql](https://charmhub.io/postgresql)
* [opensearch](https://charmhub.io/opensearch)
* [pgbouncer](https://charmhub.io/pgbouncer)
* [landscape-server](https://charmhub.io/landscape-server)
* [zookeeper](https://charmhub.io/zookeeper)
* [k8s](https://charmhub.io/k8s)
* [anbox-stream-gateway](https://charmhub.io/anbox-stream-gateway)
* [ams](https://charmhub.io/ams)
* [ceph-mon](https://charmhub.io/ceph-mon)
* [kubeapi-load-balancer](https://charmhub.io/kubeapi-load-balancer)
* [blackbox-exporter](https://charmhub.io/blackbox-exporter)
* [kubernetes-worker](https://charmhub.io/kubernetes-worker)
* [kubernetes-control-plane](https://charmhub.io/kubernetes-control-plane)
* [vault](https://charmhub.io/vault)
* [parca-agent](https://charmhub.io/parca-agent)
* [microceph](https://charmhub.io/microceph)
* [charmed-etcd](https://charmhub.io/charmed-etcd)
* [canonical-livepatch-server](https://charmhub.io/canonical-livepatch-server)
* [openstack-exporter](https://charmhub.io/openstack-exporter)
* [chrony](https://charmhub.io/chrony)
* [hardware-observer](https://charmhub.io/hardware-observer)

### Requirers

* [opentelemetry-collector](https://charmhub.io/opentelemetry-collector)