Tutorial

This tutorial walks you through deploying the Generic Exporter operator on a machine model, installing a Prometheus exporter snap using it, and validating that metrics are exposed.

As an example, we will use the node-exporter snap to export basic system metrics.

Requirements

• A Juju controller on a machine substrate (for example, LXD, MAAS, or a public cloud).
• Juju 3.x or later.
• Network access from units to the snap store.
• A principal machine charm to which the Generic Exporter operator will attach (for example, ubuntu).

Create a model

Create a new model for the tutorial:

juju add-model generic-exporter-tutorial

You should see the new, empty model with:

juju status

Deploy a principal application

Deploy a simple principal charm to host the exporter. In this example, we use the ubuntu charm:

juju deploy ubuntu --series=jammy ubuntu-node

Wait for the ubuntu-node/0 unit to become active:

juju status ubuntu-node

Deploy the Generic Exporter operator

Deploy the Generic Exporter operator as a subordinate application and configure it to manage the node-exporter snap:

juju deploy generic-exporter-operator node-exporter \
  --config snap-name="node-exporter" \
  --config snap-channel="latest/stable" \
  --config exporter-port=9100 \
  --config snap-config='{"collectors":"ntp"}'

Here:

• snap-name – exporter snap to install (node-exporter in this example).
• snap-channel – snap channel such as latest/stable, latest/candidate, or a track like 1.6/stable.
• exporter-port – TCP port on which the exporter will expose /metrics.
• snap-config – Raw JSON passed to configure exporter settings (e.g., listen port and device filter)

Relate Generic Exporter to the principal

Relate the Generic Exporter operator to the principal application so that units are co-located:

juju integrate node-exporter ubuntu-node

This uses the juju-info relation to deploy the Generic Exporter operator as a subordinate on the same machines as ubuntu-node. Each principal unit will get a corresponding subordinate unit running the exporter snap.

Wait until both applications are active:

juju status

You should see a model similar to:

Model          Controller  Cloud/Region   Version  SLA          Timestamp
generic-exporter-tutorial  ...           ...        ...      ...

App           Version  Status  Scale  Charm                      Channel         Rev  Exposed  Message
ubuntu-node   v1.10.2  active      1  ubuntu                     latest/stable   ...  no
node-exporter          blocked     1  generic-exporter-operator  1/stable        ...  no       Missing relation: [cos-agent]

Unit                Workload   Agent   Machine  Public Address  Ports  Message
ubuntu-node/0*      active     idle    0        ...                   
  node-exporter/0*  blocked    idle             ...                    Missing relation: [cos-agent]
...

If Grafana Agent (COS Agent) is not related to the exporter, the Generic Exporter unit will enter a blocked state, because it detects no COS integration has been established.

Verify metrics

SSH into the machine and query the metrics endpoint:

juju ssh ubuntu-node/0
curl http://localhost:9100/metrics | head

You should see text in Prometheus exposition format (for example, # HELP node_cpu_seconds_total ...).

If the charm cannot reach the metrics endpoint, it will report a Blocked status with a message such as Metrics endpoint not reachable.

Clean up

When you are done, destroy the model:

juju destroy-model generic-exporter-tutorial --no-prompt

This removes the principal charm, the Generic Exporter operator, and all associated machines.