DOCSEARCHbyAlgolia
Submit Docs

Observer Documentation

website·Indexed 30 days ago

https://docs.use.observer

Documentation for Observer, a status page and monitoring platform. Includes guides on defining metrics (including HTTP probes and manual metrics), configuring SLOs and error budgets, managing incidents, and publishing status pages. Covers advanced features such as customer-scoped pages, JWT-scoped access, outbound webhooks, and custom domain configuration.

Tokens
64.4K
Snippets
205
Records
444
Agent score
50%

What's inside Observer

  1. Overview of Auto-incident creation

    Auto-incident creation automatically generates a draft incident when a monitored metric flips to an unhealthy state. Drafts are invisible to customers and require a human operator to either 'Publish' (making it public) or 'Dismiss' (deleting the draft) via email CTAs. If no action is taken within 24 hours, the draft auto-expires. This feature is available for Pro+ plans.

  2. Overview of the Observer Agent

    The Observer Agent is an open-source TypeScript process (running on Bun in a distroless container) that operates within your network. It monitors system health by reading from Prometheus or probing endpoints directly via HTTP, TCP, DNS, and TLS certificates. It computes status based on defined thresholds and pushes the results to Observer Cloud through an authenticated channel.

  3. Overview of ICMP ping probes

    ICMP probes perform layer-3 network health checks by pinging a host to report reachability, latency, or packet loss. Unlike TCP probes, ICMP tests pure network reachability and does not require a service to be listening on a specific port. Note that many cloud security groups and corporate firewalls block ICMP traffic; in such cases, a TCP probe is recommended.

  4. Overview of Elasticsearch and OpenSearch sources

    The Elasticsearch/OpenSearch source converts an aggregation into a metric (e.g., error counts, latency percentiles, unique users). It executes a search against /{index}/_search with size:0 and extracts a single numeric value from a named aggregation. It does not store or read individual documents; it only extracts the resulting number from the aggregation.

  5. Overview of WebSocket probes

    WebSocket probes monitor ws:// or wss:// endpoints to measure connection health and responsiveness. They are ideal for streaming APIs, chat gateways, collaborative-editing servers, and GraphQL subscriptions. The probe opens a connection, optionally exchanges a message, and then closes the connection cleanly to avoid holding open sockets.

  6. Overview of database metric extraction

    The Observer agent can be configured to run a single read-only query against a database on each cron tick and report the scalar result. This is intended for health signals (e.g., replication lag, queue depth) or business KPIs.

    Constraints:

    • One metric definition maps to one query against one database.
    • The query must return exactly one row and one column.
    • The agent enforces a hard statement timeout (default 5s, max 30s).

    When NOT to use this:

    • If the signal already exists in Prometheus (via exporters).
    • If the query is expensive (e.g., takes several seconds); materialize expensive queries into a summary table instead.
    • If you need transaction-aware metrics, as the probe issues a single one-shot query.

  7. Overview of Observer platform documentation

    Observer is a metrics-driven status page platform. Its documentation is divided into three primary areas: the main documentation (product setup, day-two operations, and concepts), the Observer Agent (on-premise data plane), and the REST API reference.

  8. Install Observer agent using Docker

    The Observer agent can be run as a Docker container for development, single VMs, or proofs of concept. It requires an agent key from the Observer console and a valid PROMETHEUS_SERVER_URL. If the agent is not running Prometheus probes, a placeholder URL must still be provided, otherwise the agent will exit at startup.

    Prerequisites:

    • Docker installed.
    • Agent key (obtained via Agents > New agent in the Observer console).
    • A reachable PROMETHEUS_SERVER_URL.

    Verification: After starting, open http://<host>:10101 to access the debug dashboard. Check the Cloud panel for a last_heartbeat_at timestamp. The agent should appear as running in the console within 90 seconds.

    # Pull the image
docker pull ghcr.io/useobserver/agent:1.2.0

# Run the container
docker run -d \
  --name observer-agent \
  --restart unless-stopped \
  -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.2.0

  9. Understand the agent's local queue durability and behavior

    The agent uses a local SQLite file as a durability layer to buffer status pushes before delivering them to the cloud. This ensures that data survives container restarts, daemon restarts, and temporary cloud unreachability.

    Key behaviors include:

    • Batching: A background drain controller sends batches of up to 100 samples per request to the /api/agent/receiver/batch endpoint (available in agent 1.5.0+).
    • Acknowledgement: Successful posts remove rows from the queue. If the cloud rejects specific rows (e.g., due to out-of-range timestamps), those rows are dropped and logged, while the rest of the batch is accepted.
    • Error Handling: Failed posts trigger an exponential backoff. The queue continues to accept new pushes during outages.
    • Eviction: When the queue reaches its maximum capacity, the oldest entries are evicted to make room for new ones.

  10. Understand the difference between pings and metrics for status monitoring

    Availability pings (e.g., a GET request every 60 seconds) only verify that a public endpoint is reachable and returning a 2xx code. They fail to detect internal issues such as high error rates for actual customers, 95th percentile latency spikes, internal queue backups, or degraded backends masked by upstream retries.

    Metric-based status uses actual system signals (Prometheus queries, TCP connection times, DNS resolution, etc.) to ensure the public status page reflects the same data seen on internal engineering dashboards, eliminating the gap between 'green' status pages and active customer support tickets.

  11. Understand the Observer probe model vs centralized scraping

    Unlike traditional observability patterns (e.g., Prometheus, Datadog) that use centralized scraping to pull metrics from endpoints, Observer uses an agent-based probe model. The agent runs inside the user's network, executes probes against targets locally, and pushes the results (verdicts) to the cloud. This eliminates the need for public exposure of internal endpoints, reverse proxies, VPNs, or IP allowlists at the network edge, reducing the attack surface and simplifying compliance for regulated environments (PCI, HIPAA, finance).