Debugging WebSocket Applications
1. Using Browser DevTools
| Tab | Use |
|---|---|
Network → filter WS | Connection list |
| Messages | Frame stream |
| Headers | Handshake req/res |
| Console | Inspect ws instance |
2. Inspecting WebSocket Frames
| Indicator | Meaning |
|---|---|
| ↑ green | Client → Server text |
| ↓ green | Server → Client text |
| red | Control frame (close/ping/pong) |
| binary | Shown as hex |
3. Monitoring Connection State
| Property | Insight |
|---|---|
| readyState | Current phase |
| bufferedAmount | Backpressure |
| extensions | Compression on? |
| protocol | Negotiated subprotocol |
4. Logging Messages
Example: Conditional verbose log
if (localStorage.WS_DEBUG === "1") {
ws.addEventListener("message", (e) => console.debug("← ws", e.data));
const origSend = ws.send.bind(ws);
ws.send = (d) => { console.debug("→ ws", d); origSend(d); };
}5. Using wscat Tool
Example: wscat session
npm i -g wscat
wscat -c wss://api.example.com/ws -s chat.v2 -H "Authorization: Bearer $TOKEN"
> {"type":"ping"}
< {"type":"pong"}| Flag | Use |
|---|---|
-c | Connect URL |
-s | Subprotocol |
-H | Custom header |
-x | Send + exit |
6. Using Postman WebSocket
| Feature | Detail |
|---|---|
| Saved requests | Reusable WS sessions |
| Auth helpers | Bearer, Basic, etc. |
| Messages history | Inspect direction + timing |
| JSON viewer | Pretty-print payloads |
7. Implementing Debug Mode
| Trigger | Effect |
|---|---|
Env WS_DEBUG=1 | Verbose logs |
Query ?debug=1 | Client-side log |
| Header on msg | Server echoes meta back |
8. Capturing Network Traffic
| Tool | Detail |
|---|---|
| Wireshark | Frame-level (needs TLS keys) |
| tcpdump | Server-side capture |
SSLKEYLOGFILE | Decrypt TLS in Wireshark |
| mitmproxy | Intercept + modify |
9. Debugging Server Code
| Tool | Detail |
|---|---|
node --inspect | Chrome DevTools attach |
| VS Code debugger | Breakpoints, watch |
| Pino transport | Pretty + persisted |
| Async hooks | Trace async ctx |
10. Analyzing Performance Issues
| Symptom | Likely Cause |
|---|---|
High bufferedAmount | Slow network / consumer |
| CPU spikes | JSON parse / deflate |
| Memory growth | Listener / queue leak |
| Stalls | Synchronous handler blocking event loop |