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

# Probe types

> Source types the agent supports, with their value semantics and runtime status.

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](https://docs.use.observer/api/metrics/get-metrics-by-id.md) and on
[probe tests](https://docs.use.observer/api/metrics/post-metrics-test.md): `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](https://docs.use.observer/docs/concepts/manual-metrics.md). | none |
| `heartbeat` | Seconds since the last successful ping from a scheduled job. See [Heartbeat monitoring](https://docs.use.observer/docs/guides/heartbeat-monitoring.md). | `s` |
| `alert` | The worst firing alert as a score: 0 none, 1 degraded, 2 unhealthy. See [Inbound alerts](https://docs.use.observer/docs/guides/inbound-alerts.md). | none |

When a probe gets no value, the metric reports `no_data` with a reason
code instead. See [Reason codes](https://docs.use.observer/agent/reference/reason-codes.md).

## Per-type guides

Each runtime has a dedicated guide:

* [Prometheus](https://docs.use.observer/agent/guides/prometheus-source.md)
* [HTTP](https://docs.use.observer/agent/guides/http-probes.md)
* [TCP](https://docs.use.observer/agent/guides/tcp-probes.md)
* [DNS](https://docs.use.observer/agent/guides/dns-probes.md)
* [TLS certificate](https://docs.use.observer/agent/guides/tls-cert-probes.md)
* [ICMP](https://docs.use.observer/agent/guides/icmp-probes.md)
* [gRPC](https://docs.use.observer/agent/guides/grpc-probes.md)
* [WebSocket](https://docs.use.observer/agent/guides/websocket-probes.md)
* [Database](https://docs.use.observer/agent/guides/database-source.md)
* [OpenTelemetry (OTLP)](https://docs.use.observer/agent/guides/otlp-source.md)
* [AWS CloudWatch](https://docs.use.observer/agent/guides/cloudwatch-source.md)
* [Grafana Loki](https://docs.use.observer/agent/guides/loki-source.md)
* [Elasticsearch and OpenSearch](https://docs.use.observer/agent/guides/elasticsearch-source.md)
* [Custom](https://docs.use.observer/agent/guides/custom-probes.md)

## 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](https://docs.use.observer/agent/guides/icmp-probes.md).
* `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.

> [!NOTE]
>
> **Adding a new source type**
>
> New 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:

```ts title="ProbeSource" theme={null}
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`).


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