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.
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:186msThe 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.
If you are using a Linux distribution that supports Snap, you can install the tool from the Snap Store:
sudo snap install wsstatRequires that you have Go installed on your system and that you have $GOPATH/bin in your PATH. Recommended Go version is 1.21 or later.
Install via Go:
# To install the latest version, specify other releases with @<tag>
go install github.com/jkbrsn/wsstat/v2@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)" github.com/jkbrsn/wsstat@latestNote: 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
Download the binary from the latest release (amd64) on the release page:
wget https://github.com/jkbrsn/wsstat/releases/download/<tag>/wsstatMake the binary executable:
chmod +x wsstatMove 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 PATHCurrently 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:
- Place the binary in a directory of your choice and add the directory to your
PATHenvironment variable. - Rename the binary to
wsstat.exefor convenience. - You should now be able to run
wsstatfrom the command prompt or PowerShell.
For macOS:
- Make the binary executable:
chmod +x wsstat-darwin-<ARCH> - Move the binary to a directory in your
PATH:sudo mv wsstat-darwin-<ARCH> /usr/local/bin/wsstat
Some examples:
# Basic request
wsstat wss://echo.example.com
# Send an RPC method
wsstat --rpc-method eth_blockNumber wss://rpc.example.com/ws
# Start a subscription
wsstat --subscribe --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.comFor a full list of the available options, check the wsstat --help option of your client.
Long-lived streaming endpoints can be exercised with the subscription mode:
wsstat -subscribe -text '{"method":"subscribe"}' wss://example.org/streamWhen -subscribe is supplied the client keeps the socket open, forwards each
incoming frame to stdout, and periodically snapshots timing metrics. Use
-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.
Control how many interactions occur by setting -count. Non-subscription
commands default to -count 1. When streaming (-subscribe), -count 0
keeps the connection open until you cancel it, while any positive value limits
delivery to that many events before wsstat disconnects:
wsstat -subscribe -count 5 -text '{"method":"subscribe"}' wss://example.org/streamFor a single-response probe, you can either run -subscribe -count 1 or use the
dedicated helper -subscribe-once, both of which subscribe and exit after the
first event:
wsstat -subscribe -count 1 -text '{"method":"subscribe_ticker"}' wss://example.org/wswsstat -subscribe-once -text '{"method":"subscribe_ticker"}' wss://example.org/wsFor machine-readable output of summaries, add -format json.
Use the wsstat Golang package to trace WebSocket connection and latency in your Go applications. It wraps gorilla/websocket for the WebSocket protocol implementation, and measures the duration of the different phases of the connection cycle.
Install to use in your Go project:
go get github.com/jkbrsn/wsstat/v2The 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>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
# test
make test
make test V=1 RACE=1 # test with optional flags
# lint
make lintFor 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.