Skip to content
Go to dashboard

2.14WebSocket

What it checks#

A WebSocket monitor opens a connection to a ws:// or wss:// address. The check is up when the server accepts the connection (it answers 101 Switching Protocols). It can also run a list of steps once the connection is open.

Your plan must include API monitors: WebSocket monitors come with them. On a plan without them, the WebSocket tab shows a notice instead of the form, a create through the API fails with failed_precondition, and moving to such a plan pauses the WebSocket monitors you have.

Steps#

Steps run in order, after the connection is open:

  • send sends its text to the server.
  • expect waits for the next message from the server and checks that it contains its text.

With no steps, the connection alone decides. You can add up to 10 steps.

An expect step always checks the next message, so every message the server sends has to be matched in order. Many servers send a greeting as soon as you connect. wss://echo.websocket.org, for example, first sends Request served by … and only then echoes what you send. To check the echo there, expect the greeting first:

  1. expect Request served
  2. send hello
  3. expect hello

Without step 1, the expect in step 3 would be checked against the greeting, and the check would fail.

A URL or TCP monitor can pass behind a proxy that breaks WebSockets. This one cannot.

When it is up, degraded or down#

  • Up: the server accepted the connection within the timeout. Every step passed. The response-time assertion passed, if you set one.
  • Degraded: the connection was slower than your slow limit, if you set one.
  • Down: for example:
    • the server answered with another status: the server answered the handshake with HTTP 403 Forbidden, not 101 Switching Protocols.
    • TLS failed: TLS handshake failed: ….
    • no answer in time: no handshake response within 10s (the number is your timeout).
    • an expect step got a message without its text: step 3: expected "hello", got "Request served by …" (the first 200 bytes of the message).
    • an expect step got no message in time: step 2: no message within 10s.
    • the server closed first: step 2: the server closed the connection (code 1008: no token).
    • a message too large to read past: step 2: the message is over 1088 KiB, too large to read past to the next step.
    • an assertion failed, for example assertion response_time_ms < 500: got 820.

Configuration#

Dashboard fieldDefaultLimits and notes
nameEmptyRequired. Up to 200 characters, on one line.
check interval60 secondsAt least 1 second. Your plan's minimum interval still applies: below it the form shows Your plan checks at most every N seconds.
timeout10 secondsIn seconds. An API request that leaves it unset gets 30 seconds. Covers the connection and every step. A value above 60 seconds counts as 60 seconds.
locationsNone (runs from us-west)Choose from the regions shown. The check runs from each one you pick.
on failure — notifyNone (all team channels)Pick channels to limit who is alerted. Shown only when your team has channels.
urlEmptyRequired. Starts with ws:// or wss://, such as wss://acme.io/live. Otherwise the form shows Start with ws:// or wss://.
headersNoneSent with the connection request, for example Authorization. A header value can use a secret.
stepsNoneOptional. Up to 10. Each is send (text sent to the server) or expect (text the next message must contain). Text is required, up to 4096 bytes. With none, the connection alone decides.
assertions — response-time only for websocketNoneResponse time only.

Assertions supported#

response_time_ms only: how long it took to open the connection. The time the steps take is not included. The operator list shows eq, neq, contains, lt, gt and matches.

Secrets#

Write ${NAME} in the URL, a header value or a send step to use a team secret (chapter 8). The secret is sent only over wss://, and only to the secret's allowed sites.

Example#

API request body (CreateWebsocketMonitor)
json
{
  "name": "live feed",
  "url": "wss://acme.io/live",
  "headers": {"Authorization": "Bearer ${FEED_TOKEN}"},
  "steps": [
    {"kind": "WEBSOCKET_STEP_KIND_SEND", "text": "{\"op\": \"ping\"}"},
    {"kind": "WEBSOCKET_STEP_KIND_EXPECT", "text": "pong"}
  ],
  "intervalSeconds": 60
}

Good to know#

  • Only the first 64 KiB of each message is searched for an expect step's text.
  • The older send and expect fields of CreateWebsocketMonitor are deprecated. Use steps. Monitors made with them show as a send step and an expect step.
  • A Sec-WebSocket-Protocol header is offered to the server as the list of subprotocols.
  • Server errors: url required, url must start with ws:// or wss://, steps must have at most 10 steps, steps[1]: kind must be SEND or EXPECT, steps[1]: text required, steps[1]: text must be at most 4096 bytes, send and expect cannot be given with steps, and assertions[0]: type "status_code" is not one of response_time_ms.

Last updated