> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://use.observer).

> [!NOTE]
>
> **Why Prometheus first**
>
> Observer 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

**1. Create an organisation**

Sign in at [use.observer](https://use.observer/console/auth) 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 **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.

**3. Run the agent**

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

> [tab] Docker
>
> ```bash title="docker run" theme={null}
> 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
> ```

> [tab] Kubernetes
>
> ```yaml title="agent.yaml" theme={null}
> 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.

**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:

```text title="PromQL" theme={null}
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`.

> [!WARNING]
>
> **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 **Polling 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` 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

```text theme={null}
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.

## Next

* [Define your first SLO](https://docs.use.observer/docs/quickstart/first-slo.md)
* [Publish your first status page](https://docs.use.observer/docs/quickstart/first-status-page.md)
* [Observer Agent reference](https://docs.use.observer/agent/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.