# Observer Documentation

> Status pages powered by metrics, not vanity pings.

Three products covered:
- `Observer` — cloud control plane
- `Observer Agent` — open-source data plane
- `API` — REST API reference

- [How Observer works](https://docs.use.observer/docs/concepts/architecture) — A high-level view of the agent, the cloud, and how they exchange data.
- [Why metrics, not pings](https://docs.use.observer/docs/concepts/metrics-vs-pings) — The case for metric-based status over availability pings.
- [SLOs and error budgets](https://docs.use.observer/docs/concepts/slos-and-error-budgets) — How service level objectives translate metric status into a contractual signal.
- [Customer scopes](https://docs.use.observer/docs/concepts/customer-scopes) — Per-customer status pages, JWT-verified, with per-customer SLO targets.
- [Thresholds and dwell](https://docs.use.observer/docs/concepts/thresholds-and-dwell) — How a metric's status is decided, and how dwell gating prevents flapping.
- [Observer availability](https://docs.use.observer/docs/concepts/observer-availability) — What happens when Observer Cloud is degraded, when the agent stops pushing, and why your customers will not see a red status page because of our outage.
- [Incidents and metrics](https://docs.use.observer/docs/concepts/incidents-and-metrics) — How customer-facing incidents relate to metric-driven status.
- [Manual metrics](https://docs.use.observer/docs/concepts/manual-metrics) — When the agent can't measure it, set the status explicitly.
- [Incident SLO impact](https://docs.use.observer/docs/concepts/incident-slo-impact) — How the auto-impact panel computes burn rate and time to budget exhaustion.
- [Define your first metric](https://docs.use.observer/docs/quickstart/first-metric) — Install the agent, define a metric backed by a Prometheus query, and report status to Observer Cloud.
- [Define your first metric (HTTP probe)](https://docs.use.observer/docs/quickstart/first-metric-http) — Install the agent, define a metric backed by an HTTP probe, and report status to Observer Cloud.
- [Define your first SLO](https://docs.use.observer/docs/quickstart/first-slo) — Attach a service level objective to a metric and read the error budget.
- [Publish your first status page](https://docs.use.observer/docs/quickstart/first-status-page) — Compose services, metrics, and SLOs into a customer-facing status page on a subdomain.
- [File your first incident](https://docs.use.observer/docs/quickstart/first-incident) — Walk a draft → publish → update → resolve incident through the console.
- [Schedule your first maintenance](https://docs.use.observer/docs/quickstart/first-maintenance) — Schedule a maintenance window with auto-start and auto-complete.
- [Add email subscribers to your status page](https://docs.use.observer/docs/quickstart/first-subscriber) — Configure the subscribe block, set up double opt-in, and verify a test subscription.
- [Configure outbound webhooks](https://docs.use.observer/docs/guides/outbound-webhooks) — Subscribe an HTTPS endpoint to status, SLO, and agent events.
- [Serve a status page on your own domain](https://docs.use.observer/docs/guides/custom-domain) — Point status.yourdomain.com at Observer with automatic TLS.
- [Password-protect a status page](https://docs.use.observer/docs/guides/password-protected-pages) — Require visitors to enter a password before the page renders.
- [Configure JWT-scoped access](https://docs.use.observer/docs/guides/jwt-scoped-access) — Gate a status page behind a Bearer token verified against your public key or JWKS endpoint.
- [Configure customer-scoped pages](https://docs.use.observer/docs/guides/customer-scoped-pages) — Render the same status page differently per customer, with per-customer SLO thresholds.
- [Use multiple metric sources](https://docs.use.observer/docs/guides/multiple-metric-sources) — Mix Prometheus, HTTP, TCP, DNS, and TLS certificate probes in one Observer organisation.
- [Customise the status page theme](https://docs.use.observer/docs/guides/theme-customization) — Apply a built-in theme preset or override colours, typography, and spacing on a per-page basis.
- [Define a manual metric](https://docs.use.observer/docs/guides/define-a-manual-metric) — The cleanest path for operators without metrics infrastructure.
- [Create incidents via API](https://docs.use.observer/docs/guides/incidents-via-api) — For IR automation and ChatOps integrations.
- [Auto-incident creation](https://docs.use.observer/docs/guides/auto-incident-creation) — Opt a metric in to automatic draft-incident creation when it flips unhealthy. Drafts ship with email CTAs so a human always verifies before customers see the incident.
- [Migrate from Statuspage](https://docs.use.observer/docs/guides/migrate-from-statuspage) — Move services, components, incidents, and subscribers from Atlassian Statuspage to Observer.
- [Plans and quotas](https://docs.use.observer/docs/reference/plans-and-quotas) — Per-plan limits for resources, retention, and API throughput.
- [Webhook payload reference](https://docs.use.observer/docs/reference/webhook-payloads) — JSON shapes for every event type Observer emits.
- [Audit log events](https://docs.use.observer/docs/reference/audit-log-events) — Categories of administrative events recorded in the audit log.
- [Threshold operators](https://docs.use.observer/docs/reference/threshold-operators) — How healthy / degraded / unhealthy is decided from a metric value.
- [Incident and maintenance lifecycle](https://docs.use.observer/docs/reference/incident-lifecycle) — States, transitions, and the events fired on each.
- [Subscriber notification events](https://docs.use.observer/docs/reference/subscriber-events) — Which incident and maintenance transitions trigger subscriber emails.
- [RSS / Atom feed reference](https://docs.use.observer/docs/reference/feed) — Public feed shape, caching headers, and exclusion rules.
- [Status page renders blank](https://docs.use.observer/docs/troubleshooting/page-renders-blank) — Diagnose a public status page that returns 200 but shows no content blocks.
- [Metric shows no data](https://docs.use.observer/docs/troubleshooting/metric-shows-no-data) — Diagnose a metric that displays no current value or status in the console.
- [Webhook deliveries failing](https://docs.use.observer/docs/troubleshooting/webhook-deliveries-failing) — Diagnose a webhook subscription whose deliveries do not reach the receiver, or whose receiver rejects them.
- [SSO not working](https://docs.use.observer/docs/troubleshooting/sso-not-working) — Diagnose JWT-based access on customer-scoped pages and authentication issues for the console.
- [Documentation](https://docs.use.observer/docs) — Reference and guidance for Observer, the metrics-driven status page platform.
- [Agent and cloud boundary](https://docs.use.observer/agent/concepts/agent-cloud-boundary) — What crosses the network and what does not.
- [Probes vs scraping](https://docs.use.observer/agent/concepts/probes-vs-scraping) — Why the agent runs probes from inside your network instead of having the cloud scrape endpoints.
- [The local queue](https://docs.use.observer/agent/concepts/local-queue) — Why the agent buffers status pushes locally, and how the buffer behaves under cloud unreachability.
- [Bun and distroless: design choices](https://docs.use.observer/agent/concepts/bun-distroless-design) — Why the agent runs on Bun and ships in a distroless image.
- [Install from a release binary](https://docs.use.observer/agent/quickstart/install-binary) — Download a single-file executable from GitHub Releases. No runtime install required on the host.
- [Install on Docker](https://docs.use.observer/agent/quickstart/install-docker) — Run the published image with three required environment variables.
- [Install on Kubernetes](https://docs.use.observer/agent/quickstart/install-kubernetes) — Deployment manifest with Secret-bound credentials.
- [Configure Prometheus query metrics](https://docs.use.observer/agent/guides/prometheus-source) — Define a metric whose value comes from a PromQL query the agent runs against your Prometheus.
- [Configure HTTP probes](https://docs.use.observer/agent/guides/http-probes) — Probe an HTTP endpoint and report response time as the metric value.
- [Configure TCP probes](https://docs.use.observer/agent/guides/tcp-probes) — Open a TCP connection and report connect time as the metric value.
- [Configure DNS probes](https://docs.use.observer/agent/guides/dns-probes) — Resolve a record and report resolve time as the metric value.
- [Configure TLS certificate probes](https://docs.use.observer/agent/guides/tls-cert-probes) — Connect to a TLS endpoint and report days until certificate expiry.
- [Connect to Grafana Cloud](https://docs.use.observer/agent/guides/connect-grafana-cloud) — Use a Grafana Cloud Prometheus endpoint as the agent's metric source.
- [Read the agent dashboard](https://docs.use.observer/agent/guides/read-the-dashboard) — How to interpret the panels exposed on the agent's debug HTTP surface.
- [Diagnose a stalled agent](https://docs.use.observer/agent/guides/diagnose-stalled-agent) — Triage path when an agent stops reporting or its queue depth grows.
- [Rotate the agent's authentication key](https://docs.use.observer/agent/guides/rotate-agent-key) — Generate a new agent key, deploy it, and retire the old one with no observability gap.
- [Environment variables](https://docs.use.observer/agent/reference/environment-variables) — Every environment variable the agent reads, with defaults and meaning.
- [Probe types](https://docs.use.observer/agent/reference/probe-types) — Source types the agent supports, with their value semantics and runtime status.
- [Dashboard panels](https://docs.use.observer/agent/reference/dashboard-panels) — Read-only state surface served on the agent's debug HTTP port.
- [Heartbeat payload](https://docs.use.observer/agent/reference/heartbeat-payload) — JSON shape the agent posts to /api/agent/heartbeat.
- [Observer Agent](https://docs.use.observer/agent) — The Observer data plane. Probes metric sources, computes status, pushes verdicts to the cloud.
- [Authentication](https://docs.use.observer/api/getting-started/auth) — API keys, scopes, and how to authenticate requests against the public API.
- [GET /services](https://docs.use.observer/api/services/get-services) — List services
- [GET /services/{id}](https://docs.use.observer/api/services/get-services-by-id) — Get service by id
- [GET /metrics](https://docs.use.observer/api/metrics/get-metrics) — List metrics
- [GET /metrics/{id}](https://docs.use.observer/api/metrics/get-metrics-by-id) — Get metric by id
- [GET /metrics/{id}/history](https://docs.use.observer/api/metrics/get-metrics-by-id-history) — Aggregated metric values over a window (max 30 days)
- [POST /metrics/{id}/status](https://docs.use.observer/api/metrics/post-metrics-by-id-status) — Set status on a manual metric (source_type='manual')
- [GET /slos](https://docs.use.observer/api/slos/get-slos) — List SLOs
- [GET /slos/{id}](https://docs.use.observer/api/slos/get-slos-by-id) — Get SLO with latest burn event
- [DELETE /incidents/{id}](https://docs.use.observer/api/incidents/delete-incidents-by-id) — Soft-delete incident
- [GET /incidents](https://docs.use.observer/api/incidents/get-incidents) — List incidents
- [GET /incidents/{id}](https://docs.use.observer/api/incidents/get-incidents-by-id) — Get incident
- [PATCH /incidents/{id}](https://docs.use.observer/api/incidents/patch-incidents-by-id) — Patch incident (title, severity, affected services, visibility)
- [POST /incidents](https://docs.use.observer/api/incidents/post-incidents) — Create incident (draft or published)
- [POST /incidents/{id}/messages](https://docs.use.observer/api/incidents/post-incidents-by-id-messages) — Append a timeline message; type=Resolved auto-resolves the parent
- [POST /incidents/{id}/publish](https://docs.use.observer/api/incidents/post-incidents-by-id-publish) — Publish a draft incident
- [POST /incidents/{id}/resolve](https://docs.use.observer/api/incidents/post-incidents-by-id-resolve) — Resolve an incident with optional final message
- [POST /incidents/from-metric/{metricId}](https://docs.use.observer/api/incidents/post-incidents-from-metric-by-metricId) — Pre-fill a draft incident from the metric's current state (idempotent within 30 minutes)
- [GET /maintenances](https://docs.use.observer/api/maintenances/get-maintenances) — List maintenances
- [GET /maintenances/{id}](https://docs.use.observer/api/maintenances/get-maintenances-by-id) — Get maintenance
- [PATCH /maintenances/{id}](https://docs.use.observer/api/maintenances/patch-maintenances-by-id) — Edit maintenance (only allowed before actual_start_at is set)
- [POST /maintenances](https://docs.use.observer/api/maintenances/post-maintenances) — Schedule a maintenance window
- [POST /maintenances/{id}/cancel](https://docs.use.observer/api/maintenances/post-maintenances-by-id-cancel) — Cancel a maintenance before completion
- [POST /maintenances/{id}/complete](https://docs.use.observer/api/maintenances/post-maintenances-by-id-complete) — Manually transition an in-progress maintenance to completed
- [POST /maintenances/{id}/start](https://docs.use.observer/api/maintenances/post-maintenances-by-id-start) — Manually transition a scheduled maintenance to in_progress
- [API reference](https://docs.use.observer/api) — Observer's public REST API. Authenticated with API keys scoped per organisation.