WebSocket Monitoring

Gasoline is an open-source MCP server that captures WebSocket connection lifecycle and message payloads, making real-time communication debuggable by AI coding assistants like Claude Code, Cursor, and Windsurf.

The Problem

WebSocket-heavy apps (chat, real-time dashboards, collaborative editors) are notoriously hard to debug. Messages fly by too fast to inspect manually, connections drop silently, and by the time you open DevTools the relevant data is gone.

Your AI assistant can’t help if it can’t see what’s happening on the wire. Gasoline captures it all with zero browsing impact.

What Gets Captured

Connection Lifecycle

• Open — connection established (URL, protocols)
• Close — connection closed (code, reason, clean/dirty)
• Error — connection errors

Message Payloads

• Sent messages — data your app sends
• Received messages — data arriving from the server
• Direction tagging — each message labeled sent or received

Adaptive Sampling

High-frequency streams (live data feeds, game state) can produce thousands of messages/second. Gasoline uses adaptive sampling to keep overhead under 0.1ms per message:

• Low-frequency connections: all messages captured
• High-frequency streams: statistically sampled
• Lifecycle events: always captured (never sampled)

// High-frequency stream (e.g., 200 msg/s stock ticker)
// Gasoline samples automatically:
{
  "sampling": {
    "active": true,
    "rate": 0.1,
    "reason": "high_frequency",
    "totalSeen": 2000,
    "totalCaptured": 200
  }
}

Your AI still sees message patterns, schemas, and any errors — without the memory cost of storing every message.

MCP Tools

get_websocket_events

Get captured messages and lifecycle events with filters:

Filter	Description
URL	Events for a specific WebSocket URL
Connection ID	Events for a specific connection
Direction	incoming, outgoing, or both
Limit	Max events to return (default: 50)

get_websocket_status

Get live connection health:

{
  "connections": [{
    "id": "ws_1",
    "url": "wss://api.example.com/stream",
    "state": "open",
    "duration": "2m30s",
    "messageRate": {
      "incoming": { "perSecond": 45.2, "total": 5420 },
      "outgoing": { "perSecond": 2.1, "total": 252 }
    }
  }]
}

Performance Budget

Metric	Budget
Handler latency per message	< 0.1ms
Memory buffer	500 events max, 4MB limit
Sampling threshold	Activates above 1000 msg/s
Impact on page load	Zero (deferred to after load event)

Extension Settings

Two capture modes:

1. Lifecycle only — open/close/error events (minimal overhead)
2. Include messages — message payloads with adaptive sampling

Toggle in the extension popup.

Use Cases

Debugging Dropped Connections

“My WebSocket keeps disconnecting.”

Your AI sees the connection lifecycle, error events, and timing patterns to diagnose whether it’s a server timeout, network issue, or client-side problem.

Message Schema Issues

“The real-time updates stopped working.”

Your AI inspects recent messages to see if the server started sending a different payload format.

Performance Debugging

“The app is getting slow.”

Message rate data reveals if you’re receiving too many updates or if message processing is backing up.

Reconnection Behavior

“The socket reconnects but data is stale.”

Your AI sees the close/reopen cycle and can identify whether the server is sending a full state refresh or just resuming the stream.