wsstat

wsstat

This project provides a way to stat a WebSocket connection; measure the latency and learn the transport details. It implements the Go package wsstat and a CLI tool, also named wsstat.

wsstat CLI Client

The CLI client provides a simple and easy to use tool to check the status of a WebSocket endpoint:

~ wsstat example.org

Target: example.org
IP: 1.2.3.4
WS version: 13
TLS version: TLS 1.3

  DNS Lookup    TCP Connection    TLS Handshake    WS Handshake    Message RTT
|     61ms  |           22ms  |          44ms  |         29ms  |        27ms  |
|           |                 |                |               |              |
|  DNS lookup:61ms            |                |               |              |
|                 TCP connected:84ms           |               |              |
|                                       TLS done:128ms         |              |
|                                                        WS done:158ms        |
-                                                                         Total:186ms

The client replicates what reorx/httpstat and davecheney/httpstat does for HTTP, but for WebSocket. It is said that imitation is the sincerest form of flattery, and inspiration has for certain been sourced from these projects.

Install

Snap

If you are using a Linux distribution that supports Snap, you can install the tool from the Snap Store:

sudo snap install wsstat

Go

Requires that you have Go installed on your system and that you have $GOPATH/bin in your PATH. Recommended Go version is 1.26 or later.

Install via Go:

# To install the latest version, specify other releases with @<tag>
go install github.com/jkbrsn/wsstat/v3@latest

# To include the version in the binary, run the install from the root of the repo
git clone github.com/jkbrsn/wsstat
cd wsstat
git fetch --all
git checkout origin/main
go install -ldflags "-X main.version=$(cat VERSION)" ./cmd/wsstat

Note: installing the package with @latest will always install the latest version no matter the other parameters of the command.

The snap is listed here: snapcraft.io/wsstat

Maintainers: see docs/operations/snap-release-flow.md for how snap revisions are built, published to edge, and promoted.

Binary

Prebuilt release binaries are currently published for Linux/amd64 only. On other platforms, build from source (see macOS and Windows below).

Download the binary from the latest release (amd64) on the release page:

wget https://github.com/jkbrsn/wsstat/releases/download/<tag>/wsstat-<tag>

Make the binary executable:

chmod +x wsstat

Move the binary to a directory in your PATH:

sudo mv wsstat /usr/local/bin/wsstat  # system-wide
mv wsstat ~/bin/wsstat  # user-specific, ensure ~/bin is in your PATH

Currently not actively supported, but you may build and try it yourself:

git clone https://github.com/jkbrsn/wsstat.git
cd wsstat
make build-all

# Binary ends up in ./bin/wsstat-<OS>-<ARCH>

Then for Windows:

1. Place the binary in a directory of your choice and add the directory to your PATH environment variable.
2. Rename the binary to wsstat.exe for convenience.
3. You should now be able to run wsstat from the command prompt or PowerShell.

For macOS:

1. Make the binary executable: chmod +x wsstat-darwin-<ARCH>
2. Move the binary to a directory in your PATH: sudo mv wsstat-darwin-<ARCH> /usr/local/bin/wsstat

Usage

Some examples:

# Basic request
wsstat wss://echo.example.com

# Send a text message
wsstat -t "ping" wss://echo.example.com

# Read the payload from a file or stdin (@file / @-)
wsstat -t @payload.json wss://echo.example.com
echo '{"hello":"world"}' | wsstat -t @- wss://echo.example.com

# Send an RPC method (JSON-RPC 2.0 by default; --rpc-version 1.0 for legacy servers)
wsstat --rpc-method eth_blockNumber wss://rpc.example.com/ws

# Start a stream
wsstat stream --summary-interval 5s wss://stream.example.com/feed

# Attach headers to dial request
wsstat -H "Authorization: Bearer TOKEN" -H "Origin: https://foo" wss://api.example.com/ws

# Resolve to a target IP and set a longer timeout
wsstat --resolve example.com:443:127.0.0.1 --timeout 30s wss://example.com/ws

# Allow insecure connection, make output extra verbose
wsstat --insecure -vv wss://self-signed.example.com

For a full list of the available options, run wsstat -h, wsstat measure -h, or wsstat stream -h.

Modes

wsstat <url> (or wsstat measure <url>) measures connection latency. wsstat stream <url> keeps the socket open for long-lived feeds. A host literally named measure/stream must be spelled with a scheme (wsstat wss://stream).

In measure mode, -c N aggregates timing across all interactions; the response printed is the first one (measure does not concatenate responses).

Stream Mode

Long-lived streaming endpoints are exercised with the stream subcommand:

wsstat stream -t '{"method":"subscribe"}' wss://example.org/stream

stream keeps the socket open, forwards each incoming frame to stdout, and periodically snapshots timing metrics. Use -b/--buffer to adjust the per-subscription queue length and --summary-interval (for example, 30s) to print recurring summaries that include per-subscription message counts, byte totals, and mean inter-arrival latency.

measure defaults to -c 1. In stream, -c 0 (the default) keeps the connection open until you cancel it, while any positive value limits delivery to that many events before wsstat disconnects:

wsstat stream -c 5 -t '{"method":"subscribe"}' wss://example.org/stream

For a single-response probe, run stream --once, which streams and exits after the first event:

wsstat stream --once -t '{"method":"subscribe_ticker"}' wss://example.org/ws

Output

Output is split across three orthogonal axes:

• -o, --output text|json|raw — the whole-stdout contract. json emits newline-delimited envelopes with a stable schema (-v/-vv never change which fields appear); raw writes payload bytes verbatim with nothing added — no label, color, or trailing newline, so frames stay binary-safe and stream frames concatenate undelimited (use -o json when you need a delimiter). In measure mode raw requires --text or --rpc-method; with --rpc-method the response frame is decoded before output, so raw emits compact JSON rather than byte-for-byte wire content.
• --body auto|compact — human body rendering (text output only). auto pretty-prints; compact puts each message on one line.
• --clip — clips each rendered line to the terminal width with a trailing ... (text output, TTY only; a no-op when piped or redirected).

# Machine-readable streaming summaries and events
wsstat stream -o json --summary-interval 5s wss://example.org/stream

# Scannable one-line-per-event output, clipped to the terminal
wsstat stream --body compact --clip wss://example.org/stream

--body, --clip, -q, -v, and -vv apply only to -o text and are rejected under -o json|raw.

Exit Codes

Usage errors (exit 2) always print plain text to stderr. Under -o json, a runtime failure (exit 1) prints a {"type":"error"} envelope to stdout so a wsstat ... -o json | jq pipeline stays parseable on the failure path:

wsstat -o json ws://127.0.0.1:1
# {"schema_version":"1.0","type":"error","error":"measuring latency: ..."}

wsstat Library Package

Use the wsstat Golang package to trace WebSocket connection and latency in your Go applications. It wraps coder/websocket for the WebSocket protocol implementation, and measures the duration of the different phases of the connection cycle.

Install

Install to use in your Go project:

go get github.com/jkbrsn/wsstat/v3

Usage

The examples/main.go program demonstrates two ways to use the wsstat package to trace a WebSocket connection. The example only executes one-hit message reads and writes, but WSStat also support operating on a continuous connection.

Run the example like this, from project root:

go run examples/main.go <a WebSocket URL>

Build & Test

The project has a Makefile that provides a number of commands to build and test the project:

# build
make build
make build-all  # build for all supported platforms
make clean      # remove built binaries and clear the golangci-lint cache

# test
make test
make test V=1 RACE=1  # test with optional flags

# lint
make lint

Contributing

For contributions, please open a GitHub issue with questions or suggestions. Before submitting an issue, have a look at the existing TODO list to see if what you've got in mind is already in the works.