Define your first metric
Install the agent, define a metric backed by a Prometheus query, and report status to Observer Cloud.
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.
Why Prometheus first
Observer also supports HTTP, TCP, DNS, and TLS certificate probes. Prometheus is documented first because most operators already run it, and the agent's reported value is straightforward to verify against a number you already trust.
Steps
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.
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.
Run the agent
Pick the runtime that matches your environment. The container
exposes a debug dashboard on port 10101.
docker run -d \
--name observer-agent \
-p 10101:10101 \
-e AGENT_KEY=obs_live_... \
-e CLOUD_SERVER_URL=https://use.observer \
-e PROMETHEUS_SERVER_URL=http://prometheus:9090 \
ghcr.io/useobserver/agent:1.1.0
apiVersion: apps/v1
kind: Deployment
metadata:
name: observer-agent
spec:
replicas: 1
selector: { matchLabels: { app: observer-agent } }
template:
metadata: { labels: { app: observer-agent } }
spec:
containers:
- name: agent
image: ghcr.io/useobserver/agent:1.1.0
ports: [{ containerPort: 10101 }]
env:
- name: AGENT_KEY
valueFrom: { secretKeyRef: { name: observer, key: agent-key } }
- name: CLOUD_SERVER_URL
value: https://use.observer
- name: PROMETHEUS_SERVER_URL
value: http://prometheus.monitoring:9090
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.
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.
Strict comparisons
Threshold operators are strict. A value exactly equal to a
threshold under over or under does not match the band.
Configure thresholds with this in mind: a 0.5% healthy boundary
expressed as under 0.005 does not call exactly 0.005 healthy.
Set Interval to 1 minute and save.
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.