Configure WebSocket probes

Connect to a ws:// or wss:// endpoint and measure handshake latency, round-trip latency, or connection success.

WebSocket probes open a connection to a ws:// or wss:// endpoint on the configured interval and report one of: time to open the connection, time to receive a reply to a message you send, or a plain 1/0 for whether the socket opened at all.

Use this for realtime backends that don't answer a normal HTTP probe: streaming APIs, chat gateways, collaborative-editing servers, GraphQL subscriptions, and anything that lives behind a WebSocket upgrade.

What it measures

The probe connects, optionally sends one message and waits for a reply, then closes the connection cleanly. It measures wall-clock time at the agent. The connection is always closed after the measurement, so the probe does not hold open sockets against your endpoint.

The agent uses an application message to measure round-trip time, not a protocol-level ping. The standard WebSocket client API does not expose ping/pong control frames, so the endpoint must echo or respond to a message you define.

Configuration shape

A handshake-latency probe needs only a URL:

{
  "url": "wss://stream.example.com/socket",
  "interpretation": "handshake_latency",
  "timeout_ms": 10000
}

A round-trip probe sends a message and waits for a matching reply:

{
  "url": "wss://stream.example.com/socket",
  "interpretation": "round_trip_latency",
  "ping_mode": "message",
  "send_message": "{\"op\":\"ping\"}",
  "expect_message": "\"op\":\"pong\"",
  "timeout_ms": 10000
}

Field reference

Field	Default	Notes
`url`	required	Must start with `ws://` or `wss://`.
`interpretation`	`handshake_latency`	What the metric value represents. See below.
`timeout_ms`	`10000`	Deadline for the whole probe (open, and reply when round-trip), 100 to 30000 ms.
`ping_mode`	`none`	`message` sends `send_message` after open. The metric form sets this for you when you pick round-trip; set it to `message` yourself only when writing the config through the API.
`send_message`	none	Round-trip only. The text sent once the socket opens. Required for round-trip.
`expect_message`	none	Round-trip only. Substring the reply must contain. Leave blank to accept any reply.
`protocols`	none	Optional subprotocol offer, sent as `Sec-WebSocket-Protocol`.
`headers`	none	Optional headers sent with the opening handshake (for example `Authorization`).

Interpretations

Interpretation	Value	Threshold idea
`handshake_latency`	Milliseconds from connect to open.	Healthy: under 200, Unhealthy: over 1000
`round_trip_latency`	Milliseconds from sending the message to a matching reply. Needs `send_message`.	Healthy: under 200, Unhealthy: over 1000
`connection_success`	`1` if the socket opened, else `0`. Never reports no_data.	Healthy: over 0, Unhealthy: under 1

Pick connection_success for "can a client connect at all", handshake_latency for connection setup health, and round_trip_latency when the endpoint echoes or answers a known message and you care about responsiveness.

Authentication

For an endpoint that needs a token, add an Authorization header. Tokens in the metric configuration are visible to anyone who can read the metric. For secrets, prefer a gateway in front of the endpoint that the agent reaches over the private network, rather than embedding a long-lived token here.

wss:// terminates TLS at the endpoint (or its load balancer). The probe does not perform client-certificate authentication. If you need mutual TLS, place it behind a sidecar that terminates mTLS, or use the HTTP probe's mTLS support against a parallel HTTP health route.

Reason codes

ws_open_failed: the socket never opened. The endpoint refused the connection, rejected the handshake, or the URL is wrong. The raw error detail is in the metric's metadata. With connection_success this reports 0 instead of no_data.
ws_handshake_timeout: the connection did not open within timeout_ms. The endpoint may be slow, unreachable, or not speaking WebSocket on that path.
ws_reply_timeout: the socket opened and the message was sent, but no reply arrived in time (round-trip only). Confirm the endpoint responds to send_message.
ws_closed_early: the endpoint closed the connection before sending the awaited reply. The close code is in the metadata.
ws_reply_mismatch: a reply arrived but did not contain expect_message. Check the endpoint's response format.

Troubleshooting

ws_open_failed against a working browser client. Browsers send an Origin header and sometimes a subprotocol. If the endpoint requires either, set headers (Origin: https://yourapp.example) and protocols to match what the browser sends.
ws_reply_timeout but the endpoint does respond. The endpoint may send a server greeting before it accepts input, or expect a specific first frame. Set send_message to the exact handshake the protocol expects, and expect_message to a substring of the known response.
Round-trip latency looks higher than expected. It includes the full open plus the message round trip. Compare against a handshake_latency metric on the same URL to separate connect time from response time.
wss:// fails but ws:// works. A TLS problem at the endpoint. Check the certificate with a TLS certificate probe against the same host and port.