Observer Docs

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 firstObserver also supports HTTP, TCP, DNS, ICMP, TLS certificate, gRPC, WebSocket, database, OTLP, CloudWatch, Loki, Elasticsearch and custom 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 Add agent. Pick where it will run, give it a name (typically the hostname), and select Create agent and key. The install command then carries the agent key, shown 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
Kubernetes

docker run

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.7.2

agent.yaml

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.7.2
          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 link card shows a recent Last heartbeat. 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:

PromQL

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 comparisonsThreshold 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 Polling 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 once the new status has held for the confirmation time (180 seconds by default). Restore the original threshold and the metric returns to healthy after the recovery confirmation time (300 seconds by default).

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 results stay in your network.

Quickstart

Concepts

Guides

Notifications

MCP server

CLI

Reference

Troubleshooting

Define your first metric

Prerequisites

Steps

Result

Next

​Prerequisites

​Steps

​Result

​Next

Prerequisites

Steps

Result

Next