Integrate with COS

This guide explains how to integrate the Generic Exporter operator with the Canonical Observability Stack (COS) by using the Opentelemetry Collector machine charm as the telemetry collector.

Requirements

• A Juju controller managing:
  • A machine model where your principal application, the Generic Exporter operator, and the Opentelemetry Collector machine charm will run.
  • A Kubernetes model where COS Lite (Prometheus, Loki, Grafana, etc.) is deployed.
• COS Lite up and running according to the COS documentation.
• Your principal application and the Generic Exporter operator are already deployed and related (as in the tutorial).

Deploy COS Lite

Follow the official COS Lite documentation to deploy COS on a Kubernetes cluster (for example, MicroK8s):

• Install MicroK8s and deploy COS Lite
• Ensure you use the offers overlay to enable cross-model relations, as described in the COS documentation.

This will give you a model (for example, cos) containing prometheus-k8s, loki-k8s, grafana-k8s, alertmanager-k8s, catalogue-k8s and traefik-k8s.

Deploy Opentelemetry Collector (machine)

In your machine model, deploy the Opentelemetry Collector machine charm:

juju switch applications
juju deploy opentelemetry-collector --channel=2/stable

Relate the Opentelemetry Collector to your principal application (if appropriate) so it can collect host-level metrics and logs. For a simple ubuntu principal:

juju integrate opentelemetry-collector ubuntu

Opentelemetry Collector will run as a subordinate on the same machines as your principal units.

Relate Generic Exporter to Opentelemetry Collector

The Generic Exporter operator uses the cos-agent relation and the cos_agent library to forward metrics and alert rules to the Opentelemetry Collector.

Relate the applications:

juju integrate generic-exporter-operator opentelemetry-collector

This informs Opentelemetry Collector about:

• The scrape job (target address, port, path) for the exporter
• The on-disk directory where alert rule files are written (for example, /run/node-exporter-0/alerts.yaml)

The Opentelemetry Collector, in turn, forwards metrics and alerts to COS Lite via prometheus_remote_write and loki_push_api relations, per the COS integration tutorial.

Relate Opentelemetry Collector to COS

From the Kubernetes model running COS Lite, expose Opentelemetry Collector’s remote write and logging interfaces as offers, or follow the standard “instrument machine charms” tutorial to connect Opentelemetry Collector to COS Lite:

For example:

# In the COS model
juju switch cos
juju offer prometheus-k8s:receive-remote-write prom-remote-write
juju offer loki-k8s:logging loki-logging

# In the machine model
juju switch applications
juju consume <controller>/cos.prom-remote-write
juju consume <controller>/cos.loki-logging
juju integrate opentelemetry-collector prom-remote-write
juju integrate cpentelemetry-collector loki-logging

Refer to the latest COS Lite and Opentelemetry Collector machine documentation for the exact relation names and topology.

Verify metrics and alerts in COS

Once all relations are established:

1. Confirm that all units are active:

   juju status
   

2. In the COS Grafana dashboard:
   • Search for a Prometheus job corresponding to the app name you chose (for example, node-exporter).
   • Confirm that the alert rules you attached (see next how-to) appear under Alerting → Rules, with topology labels derived from the exporter and principal charms.

If metrics or alerts do not appear, check:

• The Generic Exporter unit status (it may be Blocked if the metrics endpoint is not reachable).
• Opentelemetry Collector relations to COS Lite (juju status opentelemetry-collector).