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

# How Observer works

> A high-level view of the agent, the cloud, and how they exchange data.

Observer has two parts:

* **Observer Agent**, a small process you run inside your network.
  It reads metrics from your existing observability stack and runs
  probes (Prometheus, HTTP, TCP, DNS, ICMP, TLS certificate, gRPC,
  WebSocket, database, OTLP, CloudWatch, Loki, Elasticsearch, host
  metrics and custom) and computes the status verdict locally.
* **Observer Cloud**, the control plane. It receives status pushes
  from agents, runs SLO evaluation, persists data, and renders
  status pages, dashboards, and the API.

```mermaid theme={null}
%%{init: {"flowchart": {"useMaxWidth": false, "padding": 18, "nodeSpacing": 60, "rankSpacing": 80}}}%%
flowchart LR
  subgraph Net["Your network"]
    A["<b>Observer Agent</b><br/>Prometheus, HTTP probes, cloud metric APIs, and more"]
  end
  subgraph Cloud["Observer Cloud (control plane)"]
    C["<b>SLO evaluation</b><br/>Status page<br/>Webhooks<br/>API and audit"]
  end
  V["<b>Customers</b><br/>status pages, API"]
  A -->|"status push: metric_id, value, status, timestamp, reason"| C
  A -->|"health heartbeat"| C
  C --> V
```

## What crosses the network

The agent sends two things to Observer Cloud: readings with their
verdict, and a health heartbeat about the agent itself every 30
seconds (agent version and build, uptime, the host name, queue depth,
active source types, and the names of any custom probes; agents
before 1.7.0 also sent their descriptions). Each reading is one row:

```json theme={null}
{ "metric_id": "<uuid>", "value": <number>, "status": "<healthy|degraded|unhealthy|no_data>", "timestamp": "<ISO8601>", "reason": "<code, when the probe produced no value>" }
```

Credentials and raw query responses stay on the agent host:
connection strings, tokens, and certificates are referenced by
environment variable name and read locally, and the response
bodies, result sets, and resolver answers behind a reading never
leave the agent. Log forwarding is off by default
(`BROADCAST_LOGS=false`). When you browse CloudWatch metrics in the
console, the agent returns metric names and dimensions, no values. The cloud has no path back into your
network; it cannot pull from your Prometheus or hit your endpoints
directly. See [Agent and cloud boundary](https://docs.use.observer/agent/concepts/agent-cloud-boundary.md)
for the full list of calls.

## What runs where

| Concern | Location |
| - | - |
| Metric collection | Agent, in your network |
| Status verdict | Agent, computed against the threshold rule |
| SLO evaluation | Cloud, against pushed status |
| Status page render | Cloud |
| Webhook delivery | Cloud |
| Audit log | Cloud |
| Public API | Cloud |

> [!NOTE]
>
> **Closed source cloud, open source agent**
>
> Observer Cloud is a closed-source SaaS. The Observer Agent is open source:
> source at
> [github.com/useobserver/agent](https://github.com/useobserver/agent),
> Apache-2.0 licensed.

## Operational implications

* The agent must run in a network segment that can reach your
  metric sources. The cloud cannot reach them on your behalf.
* The agent's own health is reported back to the cloud through
  heartbeats. The cloud surfaces a stalled agent as
  `agent.offline`.
* The agent is stateless with respect to historical data: lost
  agents do not lose history, because all status pushes are
  persisted in the cloud.


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