Check types

A monitor runs one check on a schedule and records a heartbeat: up or not, plus latency, a code and a message. This page lists every check type and explains how a result becomes up.

The check types

Settings without a column of their own live in the monitor’s config map. Default ports apply when the target has none.

Type	What it checks	Up when (no conditions)	Key settings
http	One HTTP(S) request to the target URL. Redirects are followed.	status 2xx	method: GET (default), POST, HEAD, PUT, DELETE. Body read up to 1 MiB for conditions.
tcp	A TCP connection to host:port.	connected	—
icmp	One IPv4 echo request.	matching echo reply	Uses an unprivileged ping socket when available, otherwise a raw socket.
dns	Resolves the hostname with the executor’s resolver.	at least one address	Addresses are joined into [BODY].
tls	TLS handshake; reads the leaf certificate without chain verification.	handshake succeeds and certificate not expired	Port 443. Days to expiry in [CERT_EXPIRY].
grpc	grpc.health.v1 Check on the whole server, plaintext.	SERVING	Port 50051.
postgres	Connects and runs a query.	query succeeds	username, database (required); sslmode: disable, require (default), verify-ca, verify-full; query (default SELECT 1). Port 5432.
mysql	Connects and runs a query.	query succeeds	username, database (required); tls (default true); tls_skip_verify (default false); query (default SELECT 1). Port 3306.
redis	Optional AUTH, then PING.	reply +PONG	username (optional); tls (default true); tls_skip_verify. Port 6379.
promql	GET <target>/api/v1/query with the query.	HTTP 200, status success, and a scalar or first vector sample	query (required); auth_mode: none (default) or basic with username. Value in [RESULT].
rabbitmq	mode: amqp: AMQP 0-9-1 protocol handshake. mode: management: GET on the management API.	handshake reply; for management, status 2xx	mode (required). For management: username, path (default /api/overview), tls (default true). Ports 5672, 15672 or 15671 with TLS.
websocket	HTTP Upgrade handshake (ws://, wss://).	101 with a valid Sec-WebSocket-Accept	The certificate is not verified for wss://.
ssh	Reads the server identification banner.	a line starting SSH-	Port 22. Banner in [BODY].
composite	Current status of its child monitors. No network call.	all (default): every child up; any: at least one; quorum: fewer than quorum children down	children (comma-separated monitor IDs), mode, quorum. Always runs in region core.
push	Nothing; the watched job calls cerbix.	a push arrives within interval_seconds + grace_seconds	The job POSTs /api/v1/public/push/<token>, optionally with ?status=down and msg.
synthetic	An ordered multi-step HTTP scenario, up to 50 steps.	every step completes and its assertions pass	scenario: steps with url, method, headers, body, extract (json, header, status, body) and assert (status, latency_ms, body_contains, json). {{var}} reuses extracted values.
async_canary	One asynchronous transaction: submit, correlate, await a terminal result, assert, clean up.	every stage succeeds	workflow of kind async_transaction_v1: submit (http_json or multipart_fixture, POST), correlate, completion (sse or poll_json), result, cleanup. HTTPS only. retries must be 0, and the interval must be at least the timeout.

A composite records no latency. For push, failure_threshold is always 1.

Schedule, retries and timeouts

Field	Default	Limit
interval_seconds	60	at most 86,400
timeout_seconds	10	at most 300
retries	0	at most 10
grace_seconds (push only)	0	at most 86,400
failure_threshold	1	—
confirm_interval_seconds	10	0 turns it off; otherwise clamped to [5, interval]

When you omit interval, timeout, retries or failure threshold on create, the values come from the instance’s monitor defaults (shown above as shipped). Each attempt gets its own timeout, so one run can take up to (retries + 1) × timeout_seconds.

How up is decided

1. The check runs. If it fails to connect or complete, the attempt is down with the failure as its message. Conditions cannot rescue a failed attempt.
2. If the check completed and the monitor has conditions, every condition must pass.
3. Without conditions, http and rabbitmq management require a 2xx status; other types pass on success.
4. A failed attempt is retried while attempts remain. The first passing attempt is recorded.

The heartbeat records the raw up. The monitor’s status turns down after failure_threshold consecutive failed checks, and confirm_interval_seconds shortens the wait between them. Service reliability reads the raw heartbeats, not the status. See How the SLI is computed.

Conditions

A condition has the form [PLACEHOLDER] OP VALUE, for example [STATUS] == 200. Conditions apply to every active type.

Placeholder	Value	Operators
[STATUS]	status code	== != < <= > >=
[RESPONSE_TIME]	latency in ms	same
[CONNECTED]	1/0, or true/false	same
[CERT_EXPIRY]	days until the certificate expires (tls)	same
[RESULT]	query value (promql)	same
[BODY]	response body or type-specific text	== != contains matches (regular expression)

An unknown placeholder or malformed condition is an error, and the check is down.

Target safety

Every network probe connects to an address it has already checked. cerbix resolves the target, checks the resulting IP, and dials that IP, so DNS rebinding and redirects cannot reach a blocked address. Every redirect hop is checked again, and probes never use a proxy.

Setting	Default	Covers
prober.allow_private_ips	true	loopback, RFC 1918, IPv6 ULA, 100.64.0.0/10
prober.allow_metadata_ips	false	link-local and cloud metadata endpoints such as 169.254.169.254

Unspecified and multicast addresses are always blocked. dns only queries the resolver and never connects to the target. async_canary uses its own fixed policy that no setting relaxes: HTTPS only, and no loopback, private, link-local or metadata addresses. Notification delivery has a separate policy under notification_egress. A URL target that carries user:password is rejected on every surface.

Region affinity

Each monitor belongs to exactly one region, core by default. Its checks run only on executors in that region, whether an AMQP worker or an HTTP-pull agent. There is no fallback to another region, so a private target is reached only from its own region. composite monitors always run in core. See Geo probers.

POST /api/v1/projects/{projectID}/monitors/test runs one check before saving, in the monitor’s region. If no executor in that region answers, it returns 502: the result is unknown, not a target outage. push and composite monitors cannot be tested.

Secret references

Credentials live in the project’s secret inventory (/api/v1/projects/{projectID}/secrets). Values are write-only and never returned by the API. Monitors reference secrets by name.

Types	How to reference
postgres, mysql, redis, rabbitmq (management), promql (basic)	Exactly one of password or password_ref through the API. Bundles must use password_ref.
synthetic	{{secret:<binding>}} in a header or body, plus scenario_secret_<binding>_ref naming the secret. Up to 16 bindings.
async_canary	A secret_ref node in the workflow, plus canary_secret_<binding>_ref. Up to 8 bindings.

The inventory requires secrets.enabled: true. With it off, the inventory endpoints and password_ref return 404 feature_disabled. An inline password is encrypted at rest and never returned. In synthetic and async_canary, credential headers such as authorization, cookie and x-api-key must hold only a secret reference, and a secret may never appear in a URL. A scenario or workflow with bindings cannot be tested before it is saved.

Caution

If a credential is missing or cannot be opened when a check is dispatched, the check fails before connecting to the target. It never runs without the credential.

Rotating a referenced secret changes the monitor’s evaluation settings. Every Service that uses the monitor as an SLI member starts a new evaluation epoch. See Services and definitions.