Observer Docs

Each sample a metric reports is one number. Its unit follows from the source_type and, for some types, one source_config field. The API returns it as unit on metrics and on probe tests: ms, %, days, s, B/s, or null for a bare number (a query result in whatever unit the query returns, or a 1/0 state). Set thresholds in the same unit.

`source_type`	Value	Unit	Status
`prometheus`	Scalar result of the PromQL query, as the query returns it	none	shipped
`http`	Response time. With `json_path` set: the number extracted from the JSON response (booleans read as 1/0)	`ms`; none with `json_path`	shipped
`tcp`	TCP connect time	`ms`	shipped
`dns`	DNS resolve time	`ms`	shipped
`tls_cert`	Days until the certificate expires	`days`	shipped
`icmp`	By `interpretation`: `latency` (default) average round-trip time; `packet_loss` percentage of pings lost, 0 to 100; `reachability` 1 when any ping returned, else 0	`ms` / `%` / none	shipped
`grpc`	By `interpretation`: `health_state` (default) 1 when SERVING, 0 when NOT_SERVING; `latency` health check round-trip time	none / `ms`	shipped
`websocket`	By `interpretation`: `handshake_latency` (default) handshake time; `round_trip_latency` message round-trip time; `connection_success` 1 when the socket opened, else 0	`ms` / `ms` / none	shipped
`database`	Scalar returned by the read-only query (one row, one column)	none	shipped
`otlp`	Aggregated value of the pushed data points, in the instrument’s own unit	none	shipped
`cloudwatch`	Latest datapoint for the chosen statistic, in the metric’s CloudWatch unit	none	shipped
`loki`	Scalar result of the LogQL aggregation	none	shipped
`elasticsearch`	Value of the named aggregation	none	shipped
`custom`	Number returned by the registered probe function	none	shipped
`host`	By `metric`: `cpu` (default) CPU utilisation; `memory` used memory; `filesystem` used space of the mountpoint; `network` bytes received plus sent per second (Linux only); `load` 1-minute load average divided by the CPU count	`%` / `%` / `%` / `B/s` / none	shipped
`mtls_http`	Same as `http`	`ms`; none with `json_path`	deprecated

Three further source types exist on metrics but are not probes. Observer evaluates them itself and they never reach the agent:

`source_type`	Value	Unit
`manual`	No measured value. The status is set by hand, through the API, or by an open incident. See Manual metrics.	none
`heartbeat`	Seconds since the last successful ping from a scheduled job. See Heartbeat monitoring.	`s`
`alert`	The worst firing alert as a score: 0 none, 1 degraded, 2 unhealthy. See Inbound alerts.	none

When a probe gets no value, the metric reports no_data with a reason code instead. See Reason codes.

Per-type guides

Each runtime has a dedicated guide:

Notes on specific types

icmp shells out to the system ping. It needs the CAP_NET_RAW capability on the agent host. When the capability or the ping binary is unavailable, the probe reports a privilege/availability reason rather than falling back to TCP. The published container image has no ping, so ICMP needs the release binary or a custom image that adds iputils. See ICMP probes.
grpc runs the standard gRPC Health Checking Protocol only. It does not invoke arbitrary methods.
websocket measures the handshake, and optionally an application-level round-trip when configured with a send/expect message pair.
database runs a single read-only query per tick and reports the scalar result. PostgreSQL and MySQL accept SELECT-only statements; Redis accepts a small read-only command allowlist; MongoDB accepts document-count operations. The connection string is read from an environment variable on the agent host and is never sent to the cloud.
host reads the machine the agent runs on (inside its container, when it runs in one). On Linux, memory is used memory from MemAvailable. On macOS, memory is Activity Monitor’s Memory Used: wired, active and compressed pages over physical memory, read from vm_stat and sysctl. Older agents count only free pages as available on macOS, so memory reads close to 100% on a healthy Mac. Network throughput is Linux only; elsewhere it reports no_data with host_metric_unsupported_platform.
mtls_http is deprecated. Use the http source with its mTLS fields instead.

Adding a new source typeNew source types require a coordinated agent and cloud release. Contact Observer if you need a type not listed.

Common contract

Every source’s runtime exports the same interface:

ProbeSource

interface ProbeSource<TConfig> {
  validateConfig(config: unknown): null | string;
  execute(config: TConfig, env?: AgentEnv): Promise<ProbeResult>;
}

interface ProbeResult {
  value: number | null;
  timestamp: string;
  status_hint?: "no_data";
  reason?: string;
  metadata?: Record<string, unknown>;
}

Sources never throw. Network errors, malformed config, missing fields all resolve to { value: null, status_hint: "no_data", reason: "<code>" }. The dispatcher applies the threshold rule only when status_hint is absent. metadata stays on the agent: only the value, status and reason code reach the cloud, and the agent does not log probe error details. To see why a probe failed, reproduce the request from the agent’s host with the protocol’s own tool (curl, openssl s_client, grpcurl, logcli, the database client, ping, nc).

Quickstart

Concepts

Guides

Reference

Probe types

Per-type guides

Notes on specific types

Common contract

​Per-type guides

​Notes on specific types

​Common contract

Per-type guides

Notes on specific types

Common contract