Define your first metric

This page walks through installing the Observer agent, defining a metric backed by a Prometheus query, and confirming that the cloud receives status pushes.

Prerequisites

• A Prometheus server reachable from the host or cluster that will run the agent.
• A container runtime (Docker or Kubernetes) or a Linux host with systemd.
• An Observer Cloud account. Sign up at use.observer.

Steps

1. •

   Create an organisation

   Sign in at use.observer and create an organisation. The organisation slug becomes the URL path under /console/<org> and defines the tenant boundary for every resource below.

2. •

   Create an agent and copy its key

   In the console, open Agents, then New agent. Provide a name (typically the hostname) and submit. The next screen reveals the agent key once. Copy it before navigating away.

   The key has the form obs_live_<43 base64url characters>. Observer Cloud stores its hash, never the plaintext. A lost key requires rotation through the console.

3. •

   Run the agent

   Pick the runtime that matches your environment. The container exposes a debug dashboard on port 10101.

   Verify the connection. With Docker, browse http://<host>:10101. In Kubernetes, port-forward the deployment with kubectl port-forward deploy/observer-agent 10101:10101 and open http://localhost:10101. The dashboard's Cloud panel shows a recent last_heartbeat_at. The Agents page in the console marks the agent as running within roughly 90 seconds.

4. •

   Define a metric

   In the console, open Metrics, then New metric. Select the agent created above and set the source type to Prometheus.

   Enter a query that returns a single scalar. A standard example is the five-minute 5xx error ratio:

   rate(http_requests_total{job="checkout-api",status=~"5.."}[5m])
     /
   rate(http_requests_total{job="checkout-api"}[5m])

   Set thresholds:

   • Healthy: under 0.005 (less than 0.5% errors).
   • Unhealthy: over 0.02 (greater than 2% errors).

   Values that match neither boundary resolve to degraded.

   Set Interval to 1 minute and save.

5. •

   Confirm reporting

   Within one push interval the metric appears in the Metrics list with its current status. Open the metric to see the latest value, last push timestamp, and rolling history.

   To verify the round trip, lower the unhealthy threshold below the current value. The metric flips to unhealthy on the next push. Restore the original threshold and the metric returns to healthy.

Result

Prometheus  →  Observer Agent  →  Observer Cloud
                (your network)     (control plane,
                 debug on :10101)   status pages)

The agent computes status client-side and pushes { metric_id, value, status, timestamp } only. Raw query strings stay in your network.

Next

• Define your first SLO
• Publish your first status page
• Observer Agent reference